Virtual Devices Interface

Indigo 7 provides a Virtual Devices Interface type that provides users with several new device types, each discussed below. If you want to use Virtual Devices, make sure to enable them by selecting the Interfaces→Virtual Devices→Enable menu item.

To add a virtual device to Indigo, follow these steps:

  1. Select DEVICES in the Main Window outline view or select one of the sub-folders.
  2. Click the New… button. You'll see the Create New Device dialog.
  3. Select Virtual Devices from the Type popup menu.
  4. Select the model of virtual device you want to create (described below).

With the addition of Z-Wave (and various plugins that define dimmer and relay devices) it has become apparent that we need to provide some way to create technology agnostic groups of devices. You can, of course, control groups of devices through Action Groups, and for most cases that's good enough.

However, there are some cases where you want a group to track the state of the devices it contains. So not only do you want to turn on/off a group, you want to know when any of the devices in the group “leave” the definition of the group by changing. So we've created a new “Device Group” device to help you with that.

We've also added a twist to this device. When we create the device (and anytime later), we save off the current state of each device in the group. It's like taking a snapshot of each device. When you turn ON the group, we'll use the value that the device was when you last saved the device states. We think you'll really love this feature since you can set all the devices how you want them, then save the device states.

To create a device group, you just create a new device, select Virtual Devices from the Type menu, select Device Group from the model menu, and you'll see the configuration dialog:

Select the devices you want to be in the group (only dimmer devices, relay (on/off) devices, and sensor devices that support an on/off state are available). To select multiple, hold down the command key and click the device in the list. Notice that the devices all have something in parenthesis after the name - that's the current value of the device that will be saved. If it's a dimmer device, it shows the brightness and if it's a relay (On/Off) device, it shows whether it's on or off. When you save, that's the value that will be saved. These values will be used when the group is turned on.

Next, you specify how the plugin will manage the ON state of the device group. The two choices are:

  • All devices are ON - the group state will be set to ON when all devices in the group are ON
  • Any device is ON - the group state will be set to ON when any of the devices in the group are ON

Finally, you need to specify how Indigo will determine if a device is ON or OFF. For dimmer devices, you have the following options:

  • Brightness >= saved value - by selecting this option, the device will be considered ON when the brightness is greater than or equal to the value of the brightness saved for that device. Note that you can have a brightness set to 0 when the group was saved, in which case when the group is turned on the brightness will be set to 0.
  • Brightness > 0 (On) - by selecting this option, the device will be considered ON when the brightness is greater than 0. So it will be considered on even at very dim settings.

For relay (on/off) and sensor devices, you have the following options:

  • Equal to saved value - by selecting this option, the device will be considered ON when it is equal to how it was set when you saved the state for that device. This way, you can add a device when it's off and turning on the group will in fact turn off the device.
  • On - this is the most obvious option - if the device is really ON, then it's considered ON.

To use a device group, just use the standard Control Light/Appliance action to turn it ON/OFF, and create triggers on the group's ON and OFF state via the Device State Changed trigger type. Turning a device group on will set all the devices to their respective saved state. You can also update the states of the devices in the group at any time by using the Update Device Group States action or menu item. That's it!

We've regularly heard that users have multiple sprinkler controllers and would like to treat them as a single controller. This Virtual Device does just that. You can specify up to 4 different physical sprinkler devices:

Indigo will treat the resulting group as a single sprinkler. You can create standard sprinkler schedules for it and never have to worry that there might be multiple sprinkler controllers running at the same time.

One of the things that we often see are people who want to create a device that can be turned ON and OFF, but don't have the knowledge or expertise to build a full-on plugin. And sometimes a full plugin would be overkill, particularly if the device is so custom that it really wouldn't be useful to anyone else.

That's where the Virtual ON/OFF Device comes in. This device type will allow users create custom devices without the need to build an entire plugin. In fact, the first iteration of this device doesn't even require any programming at all! Virtual devices can be shown in the Indigo UI, the Indigo Web UI, and the Indigo Touch UI as on/off style devices and can be controlled using the normal on/off UI controls.

To create a virtual device, you just create a new device, select Device Collection from the Type menu, select Virtual On/Off Device from the model menu, and you'll see the configuration dialog:

We intend to support several different ways that users can have virtual devices accomplish their tasks:

  • Action Groups - where the functions are carried out by Action Groups (with a little assist from Variables if you want)

For the Indigo 7 GM release, we've only implemented Action Groups, but in future releases we may add other execution models.

Action Groups

In order to make virtual devices simple enough for non-technical users to use them, we started with the Action Groups execution model. This means that you specify an action group to execute for each of the major tasks that a ON/OFF Device can perform: turn on, turn off, toggle, and get status. Here's the config dialog for Action Groups:

The first thing you'll select are the action groups to execute when the device is turned on and off. So if you click the Turn On button or select the Turn Off action in the Control Light/Appliance action, for example, the appropriate action group will be executed. These two are the minimum requirements for this type of virtual device.

Next, you can specify an action group that will toggle a device - so if there's some way for your action group to determine at runtime how a toggle should work then you can specify it. If not, just leave the checkbox unchecked.

Automatic State Maintenance

Finally, your virtual device can maintain a state if you like. But, Action Groups can't directly manipulate state you say, right? Well, that's true. However, Action Groups can modify a variable. So, we've allowed you to select a variable and we'll monitor that variable for any change. If the value of the variable becomes “on” (or “true”, “open”, “1”, “yes”, “enabled”), we set the state of the virtual device to on. If the variable becomes “off” (or “false”, “closed”, “0”, “no”, “disabled”), then we set the state to off.

If you set the value of the variable to anything else, we'll set the state of the device to whatever you entered for the variable value AND we'll mark it as having an error. This will cause the device to turn red in the device list to help show you that there's a problem. (Z-Wave devices will do this as well and eventually INSTEON devices will too).

So your device's state will mirror the value in the variable. You can also specify an action group that will be called when you request a status update via the UI or via an action.

Note: if you don't enable Supports Status, your virtual device will always show as being “off” in the UI and triggers that watch for state change will never fire. That may be fine for your particular needs so we made it optional.

Scripting State Maintenance

You can also set the on state of a virtual device:

virtual_devices_interface = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.devicecollection")
if virtual_devices_interface.isEnabled():
    virtual_devices_interface.executeAction('setVirtualDeviceState', deviceId=DEVICEIDHERE, props={'newValue': 'on'})

Use on or off to set the state, anything else will be interpreted as an error and will show accordingly in the UI.

So that's it - you can implement a very simple On/Off virtual device just by specifying a few action groups.

  • /www/perceptive/wiki/data/pages/indigo_2021.1_documentation/virtual_devices_interface.txt
  • Last modified: 2024/06/27 00:08
  • by 127.0.0.1