Adding Devices - Running Scripts
Scripts are commonly used to add a device into the system. Another common use is to set up the system (devices, device configuration, wiring).
To run a Script, find its name on the Scripts page and click on the "Run" action to the right of it. After clicking, you will usually be presented with a parameters dialog box asking you to fill in any parameters the Script may need. Some Scripts, (e.g., some Scripts in the "examples" area), need no parameters and will run without showing the parameters box.
Most Scripts will need parameters. Device Scripts and their parameters are more fully described in the Devices section. Information about a Script and its parameters is also available inside a Script. Instead of clicking on a Script's "Run" action, click on the "Show" action and read through the Script. Lines starting with a '#' are comment lines and describe what the Script does and it parameters.
Most Scripts take a set of parameters, and when a user runs a Script, the system will query the user for the parameters using a dialog box. In the illustration above, the user has run the Script for an And device, and the system is asking the user to define the "id" and "inputs" parameters.
After the user submits the parameters, behind the scenes, the system will submit these parameters to a Script interpreter. All Script parameters must be interpretable by the Script interpreter.
The Script interpreter understands the following value types: numbers (e.g. 1,2,1.0,-2,..),
If a parameter is not
So if a Script parameter is looking for a pin name:
It's looking for a name, which, given the possible choices, has to be a double quoted string. So the parameter could be
If a Script parameter is looking for pin numbers:
It's looking for a number (1,2,3, ...) or a set of numbers. Typing a single number (e.g.
When supplying a parameter, make sure you supply a number,
Some Interesting Script Parameters
As mentioned earlier in this section, device Scripts are described in the Devices section and within the Script itself. However, one parameter is common to all device Scripts and it is best described here. The parameter is the "id" parameter. IDs are user defined names assigned to devices. They can be any name as long as the name starts with a letter and is followed by letters, numbers or underscores. Valid device IDs are "Switch", "happy_day", "light2". Invalid IDs are "1switch", "_switch", or "happy day". Since an ID is a device name, no devices can have the same name. IDs are case sensitive.
In some of the web screens, screens for viewing or wiring devices as examples, devices will be identified by their IDs. Also, when running a Script which alters a device in some way (say adding a pin to a device), the Script will need a device ID parameter. The device ID parameter identifies which device is being modified, and the parameter is the ID parameter of the device. So device IDs both identify a device, and they are parameters for other Scripts specifying which device the Scripts will act upon.
Function and Scaling Parameters (less common)
Sometimes it is necessary to take a number on a device terminal and change it into another number. For example, perhaps a terminal has a light intensity in Lux (with a max of 500), and we want to convert it into in a percentage value between 0 and 100. One could create a new device (using Ruby code) for doing this, but this is a common enough occurrence that there is an easier way to do it.
Some devices take a "function" or "scaling" parameter which defines a formula for changing their starting numeric output value into another. So for example, a function parameter which inverts an output value would look like:
As seen above, inversion is cased by dividing 1 by the initial output (1/x). The "x" value is a place holder representing the initial value supplied to the function. It could be any unknown string ("y", "z", "a", "b"). Functions work by performing the known mathematical operations (+,-,\,* etc.) on the numbers, constants, and unrecognized strings in the function, substituting the initial value in for any unrecognized strings. So to get back to our original problem of converting Lux (max of 500) to percentage (0..100):
This function introduces an internal function "round" which takes a floating point number and rounds it to the nearest integer. Functions work in floating point, so results which are not whole numbers will be returned as floating point numbers, unless they are rounded. The "lux" string is an unknown string, so it becomes the input value for the function.
Taking the problem a step further, if we wanted to get a percentage value with one digit of resolution after the decimal point:
Function/scaling parameters support the following operators, functions, and predefined constants.
Examples of other formulas:
* Additional Information about the rand() Function
The rand() function takes a single "max value" integer parameter which must be greater than or equal to 0. If the value is 0, it will generate random floating point values greater than or equal to 0.0 and less than 1.0. For all other integer values, it will generate random integers starting at 0 and less than the "max value" integer. A side effect of this definition is that rand(1) is not very interesting - it will always return 0.
The rand() function is useful if you want to create a Device which generates pseudo data for testing. Using the Mapper Device and the rand() function, you can create Devices which generate data within any range you choose.
For example, here is a Device which generates floating point output data from 90.0 to 94.9: