[Getting Started] - The Getting Started Guide for Dash Reactbrowsing

Reactive, Variables, Automation:

Your systems are only as good as their programming allows them to be. Home Automation is a canvas of possibilities. It's our job to create powerful solutions by integrating these possibilities into a system which will improve our users lives. So how do we improve and where does "Home Automation" go from here? ... Up! Our industry (by that I mean "Home Automation") is growing at an astounding rate. Every day it seems a new "smart gadget" has entered the market and is in the news or viral on kickstarter. So how do you stay a step ahead of the giants like Google and Apple all entering the market? Well that is simple, evolve.

React was built as a tool to enhance anything from simple systems to the most complex. It provides a means to split our programming into simple to understand macros each with a specific purpose. We then define "Reactive Variables which we can set and manipulate from any macro.

With React we also create "listeners" which are simply URC Device Events that will trigger a given macro whenever our Reactive Variable's value meets the parameters we define. For a more in-depth look at the concepts of React, you can read more on the official Dash React Product Page.

What we will be doing

This guide is being written with the hopes of becoming a reference guide for using React and accomplishing amazing new functionalities. With each Chapter we will dive deeper into what's possible with React. When possible, a chapter will be paired with a video which also goes over the concept to aid in your learning and files that you can examine and learn with will be provided.

In many of the guides we will be exploring programming, not a specific thing. Everyone builds systems their own way, and if we always use the products we know and use in examples, they may not provide benefit to one whom simply doesn't implement those kinds of systems. While sometimes it will get specific, our goal throughout the chapters of this guide is to provide examples which can be applied in many situations.

Instead of showing examples where TV's may turn on or Video Distribution might be controlled, we will use the Dash System Monitor feature "Output to Cloud Logs" to help us visualize what is happening at a given point during our testing. This also makes it much easier for all of us to view and understand exactly how React works and how we can apply it to our own needs.

It is important not to think about why we are doing something while you run through these guides, instead focus on what is happening and why it happened. Once you understand why and how React works, you will quickly find countless ways it can be used within your own programming to yield powerful results.

Chapter One: "Hello, World!"

In case you're not familiar with the concept of "Hello, World!" A common practice is to show how one would accomplish the simple task of printing "Hello, World!" onto the screen. This is generally one of the most basic commands that can be done and is provided as a starting point to build your knowledge of the languages syntax.

This guide is going to provide it's own version of "Hello, World" by building the basic building blocks upon which a React-Powered System is built, a "Reactive Variable" and a "Listener."

While the Video Guide will go over this concept from file creation to completion, we will begin our walkthrough after the initial system has been built and configured as much of that is information covered in other documentation such as:

Creating Our First Variable and Listener

In a sense, creating a variable and creating a listener are sort of the same thing. A listener is a Device Event which monitors the value of a Reactive Variable and triggers the given macro whenever it meets the parameters that are set within it. We will start by creating a listener which will monitor our variable and then program another macro which will trigger the listener to execute it's macro.

Step 1. Create a Device Event

Start by creating a new Device Event. If you are unfamiliar with Device Events you can read through the blog post that was created which goes over what they are and how they work. With React we create "Device Events" which we reference as "listeners." This is because we are indicating to React that it should monitor the variable that we define and listen to it's value until it matches the parameters we define in the Device Event - at which point it will trigger the macro it creates.

We can define many listeners on a single variable.

When you create a listener it will check to see if the variable listed has already been created. If it hasn't, it will automatically create it for you.

Variable names are case sensitive! In many cases you may find it best to just use all lower case so this does not become a problem. Always have a standard for how you handle variable casing!

Step 2. Specify the Variable Name

For our first Reactive Variable we are going to call our variable MyFirstVariable - simple enough, so we enter that into our Device Event for the "Variable Name" parameter.

Step 3. Specify the "Becomes" and/or "Was" Parameter(s)

Next we need to decide the parameters that we want to specify which will trigger our macro to occur. You will notice there are two fields here "Becomes" and "Was."

Becomes: This parameter allows us to define that we want the macro to occur when our variable's value "becomes" what we fill in here. So if the variable changes from "One" into "Two", if "becomes" was "Two" the macro will occur! Simple as that.

Was: This parameter allows us to define that we want the macro to occur when our variable's value "was" what we will in here. So using the same example as above, if our variable changes from "One" into "Two", then using "One" in the "Was" field would cause our macro to occur.

We can mix & match the becomes and was values to create very specific functionality. For example, "Trigger this macro if the variable WAS "One" then BECOMES "Two". Only when both of these statements are true will the macro occur.

Pro Note: Leaving a field "empty" will mean it will be ignored. So if "Becomes Value" is empty, it will not care what the variable has become (and same with the Was Value). If we wish to specify "If the Variable Value Becomes {}" (or it is an empty string), we can enter "null" as the value. This will trigger if we set our variable to an empty string (which is also the default value of the variable upon creation).

In our case we just want something simple, so lets use "Event1" within the "Becomes" input field.

Our last step is simply to name the Device Event. Naming is very important for your own organization so that as your number of Device Events in a system grows you can easily find and understand each one in the list. Dash has adopted a system for naming our Device Events which follows this specification:

The name will always start with a "prefix" which indicates which Dash App or Module controls it. For example, Lutron might start with "L:" while React may start with "R:"

The name should follow a common convention across all Device Events filled in using the same general language. For example:

R: MyFirstVariable = Event1

R: MyFirstVariable = Event1 from Event2

This will help you stay organized and have a much easier time as your systems grow in size and complexity. Below we can see the final Device Event that we have configured:

Step 4. Programming our Listener / Device Event Macro

Now that we have finished creating our first listener, we can start to build the macro that will occur whenever the event's parameters are met. In our case we are simply going to use the System Monitor "Output to Cloud Logs" TCL Command to send a message to our logs indicating that the execution of our macro occurred:

Step 5. Setting our Variable's Value

Before we can accomplish these steps, we will need to create a custom macro on our User Interface which we will use to set the current value of our Reactive Variable. How to specifically accomplish that is outside the scope of this guide (however we do go over it in the video that accompanies this guide), but we wanted to provide screenshots of the process just in case:

When the user interacts with this custom macro we want to set the value of our Reactive Variable "MyFirstVariable" so that it becomes "Event1". We do this by using TCL Commands. If you are unfamiliar with what TCL Commands are, you can read about them in this blog post where we go over them in fairly fine detail.

When you look at React's TCL Commands, you will notice there are tons of options available. Ignore them for now, we will use the first command for this guide "Set Variable (String)" which we can use to set a variable's value to whatever we would like.

Our "Variable Name" is of course MyFirstVariable and the value we setup in our listener is going to trigger when we set the value to Event1 so we will fill this values into our TCL Command as shown:

The Final Result

We are now ready to test the final result of our programming! Congratulations on making it this far! Below you can find a ink to download our "React Playground" file for Chapter One which includes all the programming you've seen up to this point.