Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
indigo_2024.1_documentation:virtual_devices_interface [2024/08/11 20:51] – davel17indigo_2024.1_documentation:virtual_devices_interface [2025/04/14 20:10] (current) – external edit 127.0.0.1
Line 20: Line 20:
 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: 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:
  
-{{device_group_config.png?nolink}}+{{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 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.+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. 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: Next, you specify how the plugin will manage the ON state of the device group. The two choices are:
Line 45: Line 45:
 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: 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:
  
-{{sprinkler_group_config.png?nolink}}+{{sprinkler_group_config.png?nolink|Sprinkler Group Configuration Image}}
  
 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. 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.
  
 ===== Virtual On/Off Devices ===== ===== 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. 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.
  
Line 56: Line 57:
 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: 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:
  
-{{pseudo_onoff_config.png?nolink}}+{{pseudo_onoff_config.png?nolink|Pseudo On Off Configuration Image}}
  
 === Execution Models === === Execution Models ===
Line 70: Line 71:
 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: 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:
  
-{{pseudo_onoff_config.png?nolink}}+{{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. 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.
Line 77: Line 78:
  
 == Automatic State Maintenance == == 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. + 
 +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). 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).
Line 99: Line 101:
  
 ===== Virtual Sensors ===== ===== Virtual Sensors =====
-New to Indigo 2024.1 are Virtual Sensors. These plugin devices are controlled by external Python scripts that send instructions to the Virtual Device so it can track a desired status. For example, you could use an external script to send a value to the Virtual Device and then fire a trigger on the result. 
  
-{{:indigo_2024.1_documentation:virtual_sensor_config_dialog.png?nolink}}+New to Indigo 2024.1 are Virtual Sensors. These plugin devices are linked to external Python scripts that send instructions to the Virtual Device so it can be used to track a desired status. The device also sends information back to the external script for further processing if needed. 
 + 
 +Say you want to use an external script to send a value to the Virtual Device based on some logic in your script and then fire an Indigo Trigger based on the result. You would create a Virtual Sensor, link it to your external script, and set up an update Action to tell the Virtual Sensor to request a status update from your script. 
 + 
 +{{:indigo_2024.1_documentation:virtual_sensor_config_dialog.png?nolink|Virtual Sensor Configuration Dialog Image}}
  
 == Supported States == == Supported States ==
-Virtual Devices support three states and **must** support at least one of the following: + 
 +Virtual Devices support two states and **must** support at least one of the following:
   * On State - your device will have an on/off state.   * On State - your device will have an on/off state.
   * Sensor Value - your device will have a sensor value.   * Sensor Value - your device will have a sensor value.
-  * Status Request - your device will respond to status requests. 
  
 == Script Locations == == Script Locations ==
-You can add scripts directly to the //''/Library/Application Support/Perceptive Automation/Scripts''// folder, or you can point to a script in any location that Indigo has the authority to access. Python scripts that are saved to the above folder will be available in the Script File dropdown menu. Alternatively, you can check the Custom Location checkbox and a field will open for you to enter the full path to the script file.+ 
 +You can add scripts directly to the //''/Library/Application Support/Perceptive Automation/Python3-includes''// folder, or you can point to a script in any location that Indigo has the authority to access. Python scripts that are saved to the above folder will be available in the Script File dropdown menu. Alternatively, you can check the Custom Location checkbox and a field will open for you to enter the full path to the script file.
  
 == Controlling Scripts == == Controlling Scripts ==
-You control the state of Virtual Devices with Python scripts (the Virtual Device executes the controlling scripts directly). The controlling script must have a //''virtual_sensor_status()''// method which the Virtual Device will call, and **must** return a valid dictionary with the following possible keys (types shown in brackets):+ 
 +You control the state of Virtual Sensor Devices with Python scripts (the device executes the controlling scripts directly). The controlling script must have a //''virtual_sensor_status()''// method which the Virtual Sensor Device will call, and **must** return a valid dictionary with the following possible keys (types shown in brackets):
  
 <code> <code>
-def virtual_sensor_status():+# If you want to pass something to the Indigo Event Log, you will need to import the 
 +# logging module and access the parent plugin's logging instance. 
 +import logging 
 +logger = logging.getLogger("Plugin")
  
-    payload = {}+def virtual_sensor_status(device: indigo.Device, action_props: dict) -> dict: 
 +    """ 
 +    This is the only method that the virtual sensor will call, unless you make calls to 
 +    other parts of your script from here. 
 + 
 +    :device: a copy of the virtual sensor device object [indigo.Device] 
 +    :action_props: any action object properties provided [dict] 
 +    :returns: updated sensor values [dict] 
 +    """ 
 +    payload = dict()
     payload['onState'] = True  # must be a bool [True/False]     payload['onState'] = True  # must be a bool [True/False]
-    payload['onStateValue'] = "Closed" # [string] +    payload['onStateUiValue'] = "Closed" # Can essentially be any valid string [string] 
-    payload['valueType'] = int  # the class type of the value [various] +    payload['sensorValue'] = 32  # note that Indigo always stores this as a float [int or float] 
-    payload['value'] = 32  # the value must be of type listed in `valueType` above. [various] +    payload['sensorValueUiValue'] = "32º"  # the value in Indigo's UI. [string] 
-    payload['uiValue'] = f"{payload['value']}º"  # the value in Indigo's UI. [string] +    payload['icon'] = "indigo.kStateImageSel.TemperatureSensor"  # i.e., [indigo.kStateImageSel] 
-    payload['icon'] = "indigo.kStateImageSel.TemperatureSensor"  # i.e., 'sensorOn' [indigo.kStateImageSel] + 
-    payload['error_value'] = ""  # the error value if needed; otherwise, empty string. [string] +    logger.info("Linked script executed.")
-    +
     return payload     return payload
 </code> </code>
 +''//device//'' -- in this context, the ''//device//'' parameter will contain a copy of the Virtual Sensor device that is linked to the script.
 +''//action_props//'' -- in this context, the ''//action_props//'' parameter will contain any props passed from the Indigo Action that caused the Virtual Sensor device to update. If the device was updated by a //''Send Status Request''// or a "generic" Indigo Action refresh call, //''action_props''// will be an empty dictionary.
  
-The Virtual Device will adjust its states based on the values returned from the //''virtual_sensor_status''// method. When that method is executed, you can make calls to other parts of your script in order to determine what the payload values should be.+The Virtual Sensor will adjust its states based on the values returned from the //''virtual_sensor_status''// method. When that method is executed, you can make calls to other parts of your script in order to determine what the payload values should be. If the update is completed successfully, the Virtual Sensor will provide a copy of the //''device''// object and an //''action_props''// dict when it requests an update from your script.
  
 == Triggers and Actions == == Triggers and Actions ==
-Virtual Devices will respond to an Indigo Action call. When the Update Virtual Sensor Action is called, the Virtual Device will reach out to your script and update its states accordingly.+ 
 +Virtual Devices will respond to an Indigo Action call. When the Update Virtual Sensor Action is called, the Virtual Device will reach out to your script and update its states accordingly. You can also refresh the Virtual Sensor device by making a call to Indigo's API. 
 + 
 +The ''//indigo.actionGroup.execute//'' API command message doesn't include action props, so the ''//action_props//'' property above will be an empty dict. You can execute this command message from both the Websocket and HTTP APIs. 
 + 
 +<code> 
 +{ 
 +  "id": "optional-custom-user-message", 
 +  "message": "indigo.actionGroup.execute", 
 +  "objectId": 123456789 
 +} 
 +</code> 
 + 
 +The ''//plugin.executeAction//'' API command message can include optional props, and is currently only available in the HTTP API command space. 
 +<code> 
 +{ 
 +    "id": some-optional-message-ID, 
 +    "message": "plugin.executeAction", 
 +    "pluginId": "com.some.indigo.plugin",   # the plugin's bundle identifier 
 +    "actionId": "some_plugin_action",  # the ID of the plugin action found in the plugin's Actions.xml file 
 +    "deviceId": 12345678,  # the device ID targeted by the plugin action (not all actions will require a device ID. 
 +    "props": {"prop1": "foo", "prop2": "bar"}, 
 +    "waitUntilDone": True 
 +} 
 +</code>
  
  • /www/perceptive/wiki/data/attic/indigo_2024.1_documentation/virtual_devices_interface.1723409494.txt.gz
  • Last modified: 2024/08/11 20:51
  • by davel17