Viewing and Controlling the System

All the Devices in the Virtual Wiring system are viewable and controllable from the Device Explorer page. The Device Explorer page provides a view of all all the Devices in the system, their terminals, and the state of the terminals. In addition, one can click on any terminal and alter that state of the terminal.

The View

To get to the Device Explorer page, click on the "Home" tab at the top of any Virtual Wiring web page. The Device Explorer page presents a 2 level hierarchy. The Devices are at the top level, and their terminals are at the bottom. To the left of each Device, there is an expander icon. Clicking on the expander icon will toggle between hiding and revealing a Device's terminals.

Device terminals begin with a small icon, are followed by some text in brackets, and are optionally followed by more text. The icon represents three types of terminals - generic, an "on" terminal, and an "off" terminal. The text in brackets is the name of the terminal. The optional trailing text is the value at that terminal. Terminals with no value will have no text after their terminal names.

At the bottom of the page, there are 2 buttons - the "Refresh" button and the "Auto Refresh" button. The "Refresh" button will update the values for all the terminals on the Device Explorer page. Instead of using the "Refresh" button, one could refresh the entire Explorer page, but the "Refresh" button will refresh the page more quickly and without disrupting the page.

The other button is the "Auto Refresh" button. If one clicks the "Auto Refresh" button, the page will self refresh every few seconds. Use this button if you need an up to date display of terminal values, but you can't keep clicking on the "Refresh" button (or if you're tired of doing it). The downside of "Auto Refreshing" is that it does use additional CPU horsepower. This may be an issue for some lower end systems.

Controlling the System

Clicking on the text for a Device's terminal will open a dialog box. The dialog box prompts the user for a value for the terminal clicked upon. Whatever one types as a value will be applied at that terminal in the system. If the terminal is wired to other terminals (see Wires section), the value will go to those terminals as well.

One can enter anything one wants as a value, but only values understood by the terminal clicked upon or terminals wired to that terminal will do anything. If a terminal or net of terminals receive a value from a dialog box, and they understand it, they will do whatever the value tells them to do.

By clicking on terminals and entering values, one can create values for terminals that are looking for values, or create commands for terminals that respond to commands. Using this technique, one can control every terminal in the system.

As mentioned, terminals only understand a particular set of values. These values are discussed in more detail in the following section.

Terminal (and Device) Values

Terminals only understand particular kinds of values. The values differ from one terminal to the next, but the values fall into one of 4 value types. These value types are: numbers, true/false/nil, double quoted strings, and commands. Any other kind of values will be ignored. One may notice that this section is similar to the Script Parameters section on the Scripts page. That is not a coincidence. The Script interpreter and the interpreter for terminals (and the interpreter for Devices) by design expect the same kinds of values. This is so because it makes it easier to use the system. It's easier to know what kinds of values to use when everything uses the same value types.

Number Values

Number values are unquoted strings of numbers. 1, 1.0, -1, and -1.0 are all valid numbers. Decimal numbers must have at least one leading digit before the decimal point (0.1 is valid, but .1 is not). If a decimal number is less than one, it must start with a zero, but only one zero before the decimal point (0.001 is valid but 00.001 is not).

Integer numbers can also be written in hexadecimal. 0xabc, 0x21, 0xA2b are all valid hex numbers.

true, false, and nil Values

true, false, and nil values are just what they appear to be. In a way they are similar to numbers - they aren't commands, they are just values which are acceptable to terminals. True, False, and Nil are not the same and are not acceptable terminal values.

Double Quoted Strings

A string with double quotes surrounding it is an acceptable terminal value. "string", and "another string" are both acceptable terminal values. If one needs double quotes inside a string, one needs to backslash the quote. "this is ok \" ".

Like numbers and true / false / nil, double quoted strings are viewed as values by the system - they don't tell terminals to do anything. They are commonly used for generating messages for humans or for encapsulating messages from humans (perhaps for later interpretation).

Double quoted strings are also used as parameters for commands (see next section). Sometimes one needs a string parameter or a parameter with a set of strings. A double quoted string with a string or set of strings is how string parameters are passed to commands.

Never use single quoted strings - they are not understood by the system.

Command Values

Command values are different from the 3 previous value types, because commands tell the system to do something. A command is a function call (or more accurately, a method call) telling a Device, through a terminal, to run a method.

Command values look like unquoted single words. They must start with a small letter. on, off, go_doIt are all valid commands. On and Off are not valid commands. As one can see, they are case sensitive.

Terminals will attempt to execute any command they see. If they don't have a method with the same name as a command, they will usually ignore the command ("Usually" means they almost always will ignore it. However, since Devices are software entities, no behavior can be guaranteed).

Just like any function or method, commands can also take parameters. Parameters are lists of values, where values are number values, true/false/nil, or double quoted strings. A parameter list is one or more parameters separated by commas. Parameters can be encapsulated in parenthesis or unencapsulated and separated from the command by one or more spaces. The following are all valid commands with parameters:

on 1
off("light")
go "home"
do(1,2,"3", true)
run "this", "that, and, another"

Summary

This completes the Explorer page description. For more information on Devices, their terminals, and the values their terminals understand, see the Devices section.