Luup/UPnP State Variables Tutorial

State variables in Luup are (loosely) based on UPnP. They are used to persistently store some information about the device, such as whether a light is currently on or off, or a thermostat's setpoints or operating modes, etc.

State variables live in service. A service is a collection of states and actions that a device might have. For example, any device that can be turned on or off might implement the urn:upnp-org:serviceId:SwitchPower1 service, which includes the state variables for tracking the device's commanded state (Target) and its current actual state (Status), as well as the action to change the state (SetTarget). The device could be a light switch, or it could be an A/V receiver, space heater, or the latest Z-Wave bar blender.

Services are layered. If the device happened to be an in-wall light dimmer, it would implement, in addition to SwitchPower1, the urn:upnp-org:serviceId:Dimming1 service, which provides the states and actions necessary to allow control over the brightness level. So the fact that the device implements both SwitchPower1 and Dimming1 services means that you can turn it on and off like any type of switch, but also that you can control the brightness. Other services could also be added for other features and capabilities the device has.

For Z-Wave devices, a major part of Luup's work is making sure that the state variables always reflect the actual state of the device. When the device sends Luup a message that its state has changed (e.g. a switch says it has been turned on or off), Luup updates its state variables to match. The same would be true of Bluetooth and ZigBee. Plugins may or may not be associated with a physical device: the Hue plugin, for example, is associated with a Hue hub and its connected devices, but the Day/Night plugin is not associated with any devices, it just looks at time and sets state variables according to its logic.

You refer to state variables to identify the state of a device. In order to test device state, you need to know which state variable is going to give you the information you need, and this is one of the big learning curves in doing automation on Vera using Reactor, Lua, or any other plugin. The Vera Community Forums are a great place to get this information. There is also an old-but-still-relevant page on Vera's wiki that describes the "core" services Luup uses and the state variables and actions of these services.

Service IDs are Important

A common mistake when trying to access a state variable is to use the wrong service Id, or assume that the service Id doesn't matter. State variable names are not unique by themselves, and so the variable name alone does not sufficiently identify the variable or state. To properly identify a state variable, you must know both its name and the service ID to which it belongs--it is the combination of service ID and variable name that is unique.

Therefore, if you want to test that a switch is on, you must not only know that the variable name is Status, but also that the service ID is urn:upnp-org:serviceId:SwitchPower1. If you use a different service ID or omit it, you will not get the on/off state of the device--you'll get nothing, or some other status that isn't necessarily on/off. Reactor simplifies this somewhat on its list of state variables in Device State conditions by hiding the service names when a variable name is unique on that device. If the variable name is not unique on the device, however, Reactor will show the abbreviated service Id with the variable name, so you can differentiate them. Basically, Reactor tries to make it as simple for you as possible.

Determining the Service ID of a Variable

In the Vera UI (UI7), you can easily see the service ID that a variable belongs to by hovering over the variable name in the device's Advanced tab (in its control panel) under the Variables sub-tab.

Modifying State Variables

Device state variables are generally used for two purposes: storage of the current operating status of the device, and storage of a device's persistent configuration data (device state variables are saved across reboots/reloads/power cycles).

State variables that are used to reflect the dynamic operating state of a device (such as the on/off state of a Z-Wave switch) generally do not modify the device when changed. For example, if you go to a light switch device's variables in the Vera UI and change its Target or Status state variables, that has no effect on the actual physical device whatsoever. If you want the dynamic state of a device to change, you usually need to use a device action, which communicates with commands to and queries of the device, and then itself sets the device's state variable values accordingly. When you click the "On" or "Off" buttons on a light switch's dashboard card in the Vera UI, that's what it is doing--it's invoking a device action on the device, and it is the device action that does all the work, including changing the state variables.

When used to store configuration data, there are some cases where it may be necessary to modify them directly in order to change the device configuration. This is relatively simple: go into the device's control panel from its web UI dashboard card, then click the Advanced tab, then click the Variables tab. You'll see all the variables listed there, with some recent values (beware: these may not accurately reflect that actual current value on the Vera--it's a long-standing Vera bug). To modify the value (and see it's actual current value on the Vera), click the "Edit" link. Enter the new value and hit "Save", or click "Cancel" if you're just looking.