Differences

This shows you the differences between two versions of the page.

--- plugins:devicecollection [2013/06/25 20:32] – [Pseudo On/Off Devices] jay
+++ plugins:devicecollection [2025/04/14 20:10] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+====== Virtual Devices ======
+Indigo 6 Pro now provides a new Virtual Devices interface type that provides users with several new device types, each discussed below.
+===== Device Groups =====
+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 **''Device Collection''** from the **''Type''** menu, select **''Device Group''** from the model menu, and you'll see the configuration dialog:
+{{:plugins:device_group_config.png?nolink|Device Group Configuration Image}}
+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 parentheses 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.
+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. 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!
+===== Virtual On/Off Devices =====
+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:
+{{:plugins:pseudo_onoff_config.png?nolink|Pseudo On Off Configuration Image}}
+==== Execution Models ====
+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 6 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:
+{{:plugins:pseudo_onoff_config.png?nolink|Pseudo On Off Configuration Image}}
+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.
+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", we set the state of the virtual device to on. If the variable becomes "off", 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.
+<color blue>Note</color>: 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.
+So that's it - you can implement a very simple On/Off virtual device just by specifying a few action groups.