Devices

In the IOM, all devices are derived from a common Device base class. This base class provides for all the common properties of a device (including devices defined by Server plugins) and each subclass also inherits all the commands in the device command namespace (indigo.device.*) - there are a few exceptions that will be noted below. Check out the examples for each section to see how you use each device type.

Like other high-level objects in Indigo, there are rules for modifying devices. For Scripters and Plugin Developers:

  • To create, duplicate, delete, and send commands to a device, use the appropriate command namespace as defined below
  • To modify an device's definition get a copy of the device, make the necessary changes, then call myDevice.replaceOnServer()

For Plugin Developers:

  • To update a plugin's props on a device on the server, call myDevice.replacePluginPropsOnServer(newPropsDict) rather than try to update them on the local device
  • To change a device's state on the server, use myDevice.updateStateOnServer(key='keyName', value='Value')
  • To change multiple device states on the server at one time, use myDevice.updateStatesOnServer(update_list) passing a dictionary that looks like this:
  # New code equivalent that is much more efficient:
  key_value_list = [
      {'key':'someKey1', 'value':True},
      {'key':'someKey2', 'value':456},
      {'key':'someKey3', 'value':789.123, 'uiValue':"789.12 lbs", 'decimalPlaces':2}
  ]
  dev.updateStatesOnServer(key_value_list)

Note: all API descriptions apply to all API versions unless otherwise specified.

Sometimes, it's useful to get a python dictionary that has all properties and states of a device, perhaps for conversion to JSON to send to some other system. This can easily be done for any device regardless of type:

>>> my_device = indigo.devices[854505717] # "017 - Door/Window Sensor"
>>> python_dict = dict(my_device)
>>> print(json.dumps(python_dict, indent=4, cls=indigo.utils.IndigoJSONEncoder))
{
	"allowOnStateChange": false,
	"protocol": "ZWave",
	"configured": true,
	"states": {
		"onOffState": true,
		"batteryLevel.ui": "100%",
		"batteryLevel": 100
	},
	"subType": "",
	"globalProps": {
		"com.perceptiveautomation.indigoplugin.zwave": {
			"zwEncryptClassCmdMapStr": "- none -",
			"zwConfigVals": {},
			"zwClassInstanceCountMap": {},
			"zwFeatureListStr": "routing, battery, beaming, waking",
			"zwShowWakeIntervalUI": true,
			"zwModelId": 0,
			"zwClassIds": [
				4,
				7,
				1
			],
			"zwModelName": "Notification Sensor",
			"zwShowDumpDevToLog": false,
			"zwEndpointClassMapStr": "- none -",
			"zwLibType": 3,
			"SupportsBatteryLevel": true,
			"zwShowSubmitModelInfoUI": true,
			"zwEncryptionStatusStr": "Not Supported",
			"zwProtoVersMajor": 4,
			"zwEndpointDevTypeMap": {},
			"userWakeInterval": 60,
			"indigoObjVersion": 10,
			"zwClassInstanceCountMapStr": "- none -",
			"version": "5.01",
			"zwClassCmdMap": {
				"c134": 1,
				"c90": 1,
				"c133": 1,
				"c132": 2,
				"c89": 1,
				"c94": 1,
				"c128": 1,
				"c122": 1,
				"c115": 1,
				"c114": 1,
				"c113": 1,
				"c32": 1
			},
			"SupportsOnState": true,
			"zwClassCmdMapStr": "20v1 80v1 84v2 85v1 86v1 71v1 72v1 73v1 59v1 5Av1 7Av1 5Ev1",
			"userEnergyPollingEnabled": false,
			"zwShowMainUI": true,
			"zwAppVersMinor": 1,
			"userPollInterval": 0,
			"zwDevSubIndex": 0,
			"zwShowManualModifyConfigParmUI": true,
			"zwManufactureName": "Unknown",
			"zwEncryptClassCmdMap": {},
			"address": 17,
			"zwEndpointClassMap": {},
			"zwConfigValsStr": "- none -",
			"zwClassName": "Notification Sensor",
			"zwEndpointDevTypeMapStr": "- none -",
			"zwNodeNeighborsStr": "1, 15, 16",
			"zwModelDefnVers": 0,
			"zwManufactureId": 0,
			"SupportsSensorValue": false,
			"zwAssociationsMap": {
				"g1": [
					1
				]
			},
			"zwShowPollingUI": false,
			"zwAssociationsMapStr": "1:[1]",
			"zwShowEnergyPollingUI": false,
			"zwWakeInterval": 60,
			"userPollAfterActivity": true,
			"zwClassCmdBase": 0,
			"zwAppVersMajor": 5,
			"zwProtoVersMinor": 5,
			"zwNodeNeighbors": [
				1,
				15,
				16
			],
			"userPollingEnabled": true
		}
	},
	"pluginProps": {},
	"lastSuccessfulComm": "2021-11-18T10:56:35",
	"buttonGroupCount": 0,
	"id": 854505717,
	"supportsAllOff": false,
	"errorState": "",
	"remoteDisplay": true,
	"energyAccumBaseTime": null,
	"displayStateValUi": "on",
	"subModel": "",
	"allowSensorValueChange": false,
	"version": "5.01",
	"energyAccumTimeDelta": null,
	"displayStateId": "onOffState",
	"batteryLevel": 100,
	"supportsStatusRequest": true,
	"supportsSensorValue": false,
	"ownerProps": {
		"zwEncryptClassCmdMapStr": "- none -",
		"zwConfigVals": {},
		"zwClassInstanceCountMap": {},
		"zwFeatureListStr": "routing, battery, beaming, waking",
		"zwShowWakeIntervalUI": true,
		"zwModelId": 0,
		"zwClassIds": [
			4,
			7,
			1
		],
		"zwModelName": "Notification Sensor",
		"zwShowDumpDevToLog": false,
		"zwEndpointClassMapStr": "- none -",
		"zwLibType": 3,
		"SupportsBatteryLevel": true,
		"zwShowSubmitModelInfoUI": true,
		"zwEncryptionStatusStr": "Not Supported",
		"zwProtoVersMajor": 4,
		"zwEndpointDevTypeMap": {},
		"userWakeInterval": 60,
		"indigoObjVersion": 10,
		"zwClassInstanceCountMapStr": "- none -",
		"version": "5.01",
		"zwClassCmdMap": {
			"c134": 1,
			"c90": 1,
			"c133": 1,
			"c132": 2,
			"c89": 1,
			"c94": 1,
			"c128": 1,
			"c122": 1,
			"c115": 1,
			"c114": 1,
			"c113": 1,
			"c32": 1
		},
		"SupportsOnState": true,
		"zwClassCmdMapStr": "20v1 80v1 84v2 85v1 86v1 71v1 72v1 73v1 59v1 5Av1 7Av1 5Ev1",
		"userEnergyPollingEnabled": false,
		"zwShowMainUI": true,
		"zwAppVersMinor": 1,
		"userPollInterval": 0,
		"zwDevSubIndex": 0,
		"zwShowManualModifyConfigParmUI": true,
		"zwManufactureName": "Unknown",
		"zwEncryptClassCmdMap": {},
		"address": 17,
		"zwEndpointClassMap": {},
		"zwConfigValsStr": "- none -",
		"zwClassName": "Notification Sensor",
		"zwEndpointDevTypeMapStr": "- none -",
		"zwNodeNeighborsStr": "1, 15, 16",
		"zwModelDefnVers": 0,
		"zwManufactureId": 0,
		"SupportsSensorValue": false,
		"zwAssociationsMap": {
			"g1": [
				1
			]
		},
		"zwShowPollingUI": false,
		"zwAssociationsMapStr": "1:[1]",
		"zwShowEnergyPollingUI": false,
		"zwWakeInterval": 60,
		"userPollAfterActivity": true,
		"zwClassCmdBase": 0,
		"zwAppVersMajor": 5,
		"zwProtoVersMinor": 5,
		"zwNodeNeighbors": [
			1,
			15,
			16
		],
		"userPollingEnabled": true
	},
	"description": "",
	"onState": true,
	"energyAccumTotal": null,
	"address": "17",
	"sharedProps": {},
	"folderId": 1145028206,
	"supportsOnState": true,
	"sensorValue": null,
	"energyCurLevel": null,
	"name": "017 - Door/Window Sensor",
	"lastChanged": "2021-11-18T10:56:35",
	"enabled": true,
	"pluginId": "com.perceptiveautomation.indigoplugin.zwave",
	"deviceTypeId": "zwOnOffSensorType",
	"supportsAllLightsOnOff": false,
	"displayStateImageSel": "SensorOn",
	"displayStateValRaw": true,
	"model": "Notification Sensor"
}
>>>

This will be a python dictionary with all details about a device. One other feature to note here: by default, Python datetime objects are not serializable by the json module (odd oversight we believe). We have included a JSON encoder class that will solve this problem: indigo.utils.IndigoJSONEncoder. Just specify that as the cls parameter to a json dump call and any datetime class that's encountered during JSON encoding will be correctly converted to a string in the resulting json string:

  json.dumps(python_dict_with_datetime, cls=indigo.utils.JSONDateEncoder)

The Device class is generally used as a base class - your script will use objects that are instances of one of it’s subclasses - we'll discuss each of the subclasses later in this section. First, a quick refresher on a fundamental aspect of devices: some devices can only be controlled (i.e. old-style ApplianceLincs, most X10 devices, etc.), called responders in Indigo terminology, other devices are only controllers (i.e. RemoteLincs, PalmPads, etc.), and some devices are both responders and controllers (i.e. KeypadLincs).

This terminology was really invented for INSTEON devices, but we think it applies to other technologies as well but perhaps in a slightly different way. In any event, controller devices can support a number of buttons and/or a number of groups from which commands are sent, all of which Indigo can use to trigger actions. From a technical and practical standpoint, they are in fact the same thing so a single number, indexed based on how the device supports them, is how this property should be used.

The base class supports getting the number of buttons or groups as a single property (buttonGroupCount) for the device. Use that count as a guide to what you can pass in the various trigger classes. For any device that doesn’t support local physical buttons or sending group commands and/or status commands, the number returned should be 0.

If you’re writing a plugin that defines devices, they will automatically inherit all of the following properties.

Property Type Writable Min API Description
address string No* 1.0 the address for the device. *Plugin developers can change this value for their plugin's devices.
batteryLevel integer No 1.0 battery level for the device - None if the device doesn't support battery operation - shortcut for dev.states['batteryLevel']
buttonGroupCount integer No 1.0 the number of groups (or buttons in the case of the RemoteLinc and ControLinc) that the controller supports - currently used only for INSTEON devices - 0 for other devices
configured boolean No 1.0 true if the device has been fully configured - if it's a plugin device use this to make sure that the device's config dialog has been run at least once.
description string Yes 1.0 a description of the device as specified by the user
deviceTypeId string No 1.0 the typeId specified in the Devices.xml (or it’s documentation) - only used for plugin defined devices
displayStateId string No 1.15 main display stateId key which can be used as a key into states[] property below
displayStateValRaw boolean integer string or none No 1.15 raw value of main display state (ex: 72.0)
displayStateValUi string No 1.15 UI value (string) of main display state (ex: '72.0°F' )
displayStateImageSel kStateImageSel No 1.18 an enumeration specifying which state image icon is shown in Indigo Touch and Indigo client UI - see state image sel enumeration below for possible values
enabled boolean No 1.0 is the device enabled - set using the indigo.device.enable() method
energyCurLevel float No 1.11 current Wattage energy being used by the device (None if not supported)
energyAccumTotal float No 1.11 current accumulated energy used since last base time specified in energyAccumBaseTime (None if not supported)
energyAccumBaseTime datetime No 1.11 the base time from which to calculate the energy total (energyAccumTotal) (None if not supported)
energyAccumTimeDelta integer No 1.11 the time delta in seconds since the last base time (None if not supported)
errorState string No 1.0 the string that represents the current error for the device, empty string if there is no error
folderId integer No 1.0 the unique ID of the folder this device is in (0 if it's not in a folder) - use moveToFolder() method to change
globalProps dictionary No 1.0 an indigo.Dict() representing all name/value pairs associated with this device - each plugin will have it's own dictionary (globalProps[pluginId]) - see About Plugin Properties below for details
id integer No 1.0 id or instance of the device, assigned on creation by IndigoServer
lastChanged datetime No 1.0 the last date/time that the device was changed - populated by IndigoServer
model string No 1.0 the model name of the device - defined either by Indigo based on type or by the plugin's device definition
name string Yes 1.0 the unique name of the device - no two devices can have the same name
ownerProps dictionary No 1.20 an indigo.Dict() representing the name/value pairs defined by the plugin that created the device - this is a shortcut into the owner plugin's globalProps data
pluginId string No 1.0 if protocol is Plugin, the string ID for the plugin
pluginProps dictionary No 1.0 an indigo.Dict() representing the name/value pairs defined by your plugin for the device - plugin developers should publish this information if you want other plugins/scripts to create devices of this type - see About Plugin Properties below for details - use replacePluginPropsOnServer() method to change
protocol kProtocol No All an enumeration specifying the kProtocol of the device - see protocol enumeration below for possible values
remoteDisplay boolean Yes 1.0 should this device be displayed in remote clients (IWS, Indigo Touch, etc) - may also be set with indigo.device.displayInRemoteUI()
sharedProps dictionary No 2.3 an indigo.Dict() representing the name/value pairs that are shared by all plugins. This is the property dictionary that you can edit via the Global Properties plugin, and your plugin may manage properties in this dictionary as well to add metadata to devices that your plugin can use for other purposes. Use dev.replaceSharedPropsOnServer() to update them (as with pluginProps, you should get copy first, update the copy, then set them back to that copy so you don't accidentally remove some other plugin's props).
states dictionary No 1.0 returns an indigo.Dict() of device states - the key is the state id and the value is the value. Note that enumerated states will have not only the state, but also each option for the state. So, for instance, if I had a state called status and it had 3 options (online, offline, error), then you'd not only have status as a key, but also status.online, status.offline, and status.error as keys in the dictionary. This is so that you can test each state enumeration independently in trigger actions (e.g. status.online is true).
supportsAllLightsOnOff boolean No All indicates that this device should react to all lights On and all lights Off commands - always False for plugin defined devices
supportsAllOff boolean No 1.0 indicates that this device should react to all Off commands - always False for plugin defined devices
supportsOnState boolean No 2.2 indicates that the device has an on state
supportsStatusRequest boolean No 1.0 indicates if the device supports querying the status - always False for plugin defined devices
version boolean No* 1.0 indicates the device's version as appropriate. *Plugin developers can change this value for their plugin's devices.
Protocol Enumeration
indigo.kProtocol
Value Description
Insteon identifies the device as an INSTEON device
X10 identifies the device as an X10 device
ZWave identifies the device as an Z-Wave device
Plugin identifies the device as a being defined by a plugin
State Image Sel Enumeration

API v1.18+ only:

indigo.kStateImageSel
Value Description
Auto specifies Indigo Server to pick a device image icon that best represents this device class and/or state<html><br></html> value (default for all devices)
AvPaused overrides to show a A/V paused icon
AvPlaying overrides to show a A/V playing icon
AvStopped overrides to show a A/V stopped icon
Closed overrides to show a generic sensor off icon (grey circle)
DehumidifierOff overrides to show a dehumidifier turned off icon
DehumidifierOn overrides to show a dehumidifier turned on icon
DimmerOff overrides to show a dimmer or bulb off icon
DimmerOn overrides to show a dimmer or bulb on icon
DoorSensorClosed overrides to show a door sensor closed icon (grey circle)
DoorSensorOpened overrides to show a door sensor opened icon (green circle)
EnergyMeterOff overrides to show an energy meter off icon
EnergyMeterOn overrides to show an energy meter on icon
FanHigh overrides to show a fan on (high) icon
FanLow overrides to show a fan on (low) icon
FanMedium overrides to show a fan on (medium) icon
FanOff overrides to show a fan off icon
HumidifierOff overrides to show a humidifier turned off icon
HumidifierOn overrides to show a humidifier turned on icon
HumiditySensor overrides to show a humidity sensor icon
HumiditySensorOn overrides to show a humidity sensor on icon
HvacAutoMode overrides to show a thermostat in auto mode icon
HvacCooling overrides to show a thermostat that is cooling icon
HvacCoolMode overrides to show a thermostat in cool mode icon
HvacFanOn overrides to show a thermostat with fan blower on only icon
HvacHeating overrides to show a thermostat that is heating icon
HvacHeatMode overrides to show a thermostat in heat mode icon
HvacOff overrides to show a thermostat off icon
LightSensor overrides to show a light meter off icon
LightSensorOn overrides to show a light meter on icon
Locked overrides to show a green lock icon
MotionSensor overrides to show a motion sensor icon
MotionSensorTripped overrides to show a motion sensor tripped/activated icon
NoImage overrides to show no device image icon (was None in previous API versions)
Opened overrides to show a generic sensor off icon (green circle)
PowerOff overrides to show a power off icon
PowerOn overrides to show a power on icon
SensorOff overrides to show a generic sensor off icon (gray circle)
SensorOn overrides to show a generic sensor on icon (green circle)
SensorTripped overrides to show a generic sensor tripped icon (red circle)
SprinklerOff overrides to show a sprinkler off icon
SprinklerOn overrides to show a sprinkler off icon
TemperatureSensor overrides to show a temperature sensor icon
TemperatureSensorOn overrides to show a temperature sensor on icon
TimerOff overrides to show a timer off icon
TimerOn overrides to show a timer on icon
Unlocked overrides to show a red lock icon
WindowSensorClosed overrides to show a window sensor closed icon (grey circle)
WindowSensorOpened overrides to show a window sensor opened icon (green circle)

The following image selectors are available but do not yet have function-specific icons in Indigo Touch and Indigo client UI. Developers are encouraged to use them for automatic future compatibility when the icons are added.

indigo.kStateImageSel
Value Description
BatteryCharger overrides to show a battery charger icon
BatteryChargerOn overrides to show a battery charger on icon
BatteryLevel overrides to show a battery level icon
BatteryLevel25 overrides to show a battery level (25%) icon
BatteryLevel50 overrides to show a battery level (50%) icon
BatteryLevel75 overrides to show a battery level (75%) icon
BatteryLevelHigh overrides to show a battery level (full) icon
BatteryLevelLow overrides to show a battery level (low) icon
Custom overrides to show a plugin defined custom image icon (not yet implemented; shows NoImage)
Error overrides to show an error device image icon
WindDirectionSensor overrides to show a wind direction sensor icon
WindDirectionSensorEast overrides to show a wind direction sensor (E) icon
WindDirectionSensorNorth overrides to show a wind direction sensor (N) icon
WindDirectionSensorNorthEast overrides to show a wind direction sensor (NE) icon
WindDirectionSensorNorthWest overrides to show a wind direction sensor (NW) icon
WindDirectionSensorSouth overrides to show a wind direction sensor (S) icon
WindDirectionSensorSouthEast overrides to show a wind direction sensor (SE) icon
WindDirectionSensorSouthWest overrides to show a wind direction sensor (SW) icon
WindDirectionSensorWest overrides to show a wind direction sensor (W) icon
WindSpeedSensor overrides to show a wind speed sensor icon
WindSpeedSensorHigh overrides to show a wind speed sensor (high) icon
WindSpeedSensorLow overrides to show a wind speed sensor (low) icon
WindSpeedSensorMedium overrides to show a wind speed sensor (medium) icon

The following instance methods can be called on device objects. Most are restricted and can only be called from a plugin on a device that the plugin owns. See the Restricted column below for those that are restricted in this way.

Method Restricted Min API Description
replaceOnServer() No 1.0 Because you can't directly modify a device's properties on the server, you have to get a local instance of the device and modify the writable properties as necessary. You then call this method and the device will be updated on the server and changes will be sent out to all connected clients. A few examples appear below this table.
replacePluginPropsOnServer(newPropsdict) Yes 1.0 If you need to make a change to your plugin's property dictionary that's stored as part of the device (see About Plugin Properties below) you just use this method to replace the entire dict with a new one. A typical usage will be to get the property dictionary from the device, make changes to the dict, then use this method to store the new dict. A few examples appear below this table.
stateListOrDisplayStateIdChanged() Yes 1.0 Plugins can subclass the method getDeviceStateList() to provide dynamic state list definition information. The default implementation provides a static solution by retrieving the device state list definition from the Devices.xml file. Likewise, the method getDeviceDisplayStateId() can be used to dynamically determine which device state should be displayed in the State column of the main device table UI. The problem is that the Indigo Server only calls getDeviceStateList() and getDeviceDisplayStateId() at very specific times, like when a plugin device dialog is dismissed. So, call stateListOrDisplayStateIdChanged() on the device instance you need refreshed at any time and Indigo will then automatically call your plugin's getDeviceStateList() and getDeviceDisplayStateId() methods (or use the base implementation of looking up the list from Devices.xml) and update the Indigo Server (and all clients). This is particularly useful for plugin updates that need to add new device states to existing device instances created by older versions. In this case, the plugin will need to update the device instances by calling stateListOrDisplayStateIdChanged(). A likely place to do this type of instance level upgrading is inside your plugin's deviceStartComm() method.
setErrorStateOnServer('error string') Yes 1.0 The supplied string will show in the state column and turn it red. Passing None will clear it.
updateStateOnServer(key='keyName', value='Value', clearErrorState=True) Yes 1.0 Use this method to update the value of one of your device's states on the server. The server will propagate the change out to any connected clients and fire any triggers that are defined on that state. Pass “true” (default) or “false” on the clearErrorState parameter (not required) to have the error state of the device (set with setErrorStateOnServer above) cleared.
updateStateImageOnServer(stateImageSel) Yes 1.18 Use this method to override which device state image icon is shown for this device on Indigo Touch and the Indgo client UI. The default behavior is for Indigo Server to automatically determine which icon should be shown based on the device class and state value. Only call this method if overriding the default behavior is needed.

Updating Device Properties Examples

Certain device properties are writeable for all Indigo devices, including a device's name, description, enabled/disabled state and remote display. You can't do this directly because device instances are read only. You must first get a copy of the device, make changes to the copy, and then send the copy back to the server. For example,

# Updating a device's description (the Indigo UI Notes field value.)
dev = indigo.devices[123456789]
dev.description = "My new description."
dev.replaceOnServer()

dev = indigo.devices[987654321]
dev.name = "My New Name"
dev.replaceOnServer()

Properties like Comm Enabled and Remote Display can also be updated using a different approach.

# Set Enabled/Disabled state
indigo.device.enable(12345678, True)

# Set Remote Display Flag
indigo.device.displayInRemoteUI(987654321, False)

Updating Plugin Device Properties Examples

Some device base class properties need to be updated differently than the examples above because they can only be updated by the plugin that owns them. Properties like address and version can be updated by their own plugins. For example,

# Updating a plugin device's properties
dev = indigo.devices[641471711]
new_props = dev.pluginProps
new_props['address'] = "abc"
new_props['version'] = "123"  # Indigo UI Firmware field
dev.replacePluginPropsOnServer(new_props)

Note that you can't update these in the same way as name and description. Instead you change them as pluginProps and Indigo migrates these values to the base class props for you.

Devices have properties - some are class properties, defined by the class itself. One of the biggest requests we've gotten in the past is some way to add arbitrary properties to a device - so that you could store your own data with the device in the database. And with plugin defined devices, we needed a place to store the properties that you need to operate the device. That's what the pluginProps and globalProps represent - the additional properties that are not defined by the class. globalProps is a dictionary of every additional property defined for the device - each plugin has it's own dictionary of props in here which are readable by anyone. pluginProps is a shortcut to get to your plugin's props and are only writable by your plugin once the plugin has been created - a script can create a device supplied by your plugin along with the necessary properties, which are passed in on the create() method. You should publish the properties necessary to make your device work so that scripters can create your devices.

We mentioned before that devices were read-only, and that's true, and that you'd need to use commands in a different command name space. That's mostly true. Here's one exception to that rule: to change a device's pluginProps (it must be “owned” by your plugin - that is, the pluginId must be set to your id), you use a method that's in the device's class: replacePluginPropsOnServer(). Here's an example:

dev=indigo.devices[123]
localPropsCopy = dev.pluginProps
localPropsCopy['pollInterval'] = 10
dev.replacePluginPropsOnServer(localPropsCopy)

You would use this technique if you wanted to just change some of the properties that are already defined. Because this method replaces ALL of the properties for your plugin in the device, you can just set them all in one call:

dev=indigo.devices[123]
dev.replacePluginPropsOnServer({'pollInterval':10,'checkForUpdates':True})

Note, though, that if you have a <ConfigUI> defined for the device, those properties are also stored here - so in order to make sure your device works correctly you must include those properties as well. If you need to update several properties in your props dict, you can use the update() method:

dev=indigo.devices[123]
localPropsCopy = dev.pluginProps
localPropsCopy.update({'pollInterval':10, 'checkForUpdates':True})
dev.replacePluginPropsOnServer(localPropsCopy)

The update() method will change the properties specified, and add the property if it doesn't exist. Now, you might be wondering - why do the extra localPropsCopy = dev.pluginProps rather than just modify the props in place:

dev=indigo.devices[123]
dev.pluginProps.update({'pollInterval':10, 'checkForUpdates':True})
dev.replacePluginPropsOnServer(dev.pluginProps)

Because the dev object is read-only - when you reference dev.pluginProps, it returns a copy rather than returning a reference to the read-only object. So, in effect, you'd be modifying a copy. But, because you aren't saving a reference to that copy, it goes away since the next time you reference dev.pluginProps another copy is made.

If you need to just dump all the properties for a device, you can just:

dev=indigo.devices[123]
dev.replacePluginPropsOnServer(None)

That will completely remove your properties from the device.

If you are a Developer and your plugin defines custom devices, then those devices will also need to define a collection of states. For instance, let's look at the states defined in a custom device's Devices.xml:

<States>
    <State id="playStatus">
        <ValueType>
            <List>
                <Option value="playing">Playing</Option>
                <Option value="paused">Paused</Option>
                <Option value="stopped">Stopped</Option>
                <Option value="unavailable">Unavailable</Option>
            </List>
        </ValueType>
        <TriggerLabel>Player Status Changed</TriggerLabel>
        <TriggerLabelPrefix>Player Status is</TriggerLabelPrefix>
        <ControlPageLabel>Current Player Status</ControlPageLabel>
        <ControlPageLabelPrefix>Player Status is</ControlPageLabelPrefix>
    </State>
    <State id="sep1">
        <ValueType>Separator</ValueType>
    </State>
    <State id="playlist">
        <ValueType>String</ValueType>
        <TriggerLabel>Current Playlist Name</TriggerLabel>
        <ControlPageLabel>Current Playlist Name</ControlPageLabel>
    </State>
    <State id="album">
        <ValueType>String</ValueType>
        <TriggerLabel>Current Album</TriggerLabel>
        <ControlPageLabel>Current Album</ControlPageLabel>
    </State>
    <State id="artist">
        <ValueType>String</ValueType>
        <TriggerLabel>Current Artist</TriggerLabel>
        <ControlPageLabel>Current Artist</ControlPageLabel>
    </State>
    <State id="track">
        <ValueType>String</ValueType>
        <TriggerLabel>Current Track</TriggerLabel>
        <ControlPageLabel>Current Track</ControlPageLabel>
    </State>
    <State id="volume">
        <ValueType>Integer</ValueType>
        <TriggerLabel>Current Volume</TriggerLabel>
        <ControlPageLabel>Current Volume</ControlPageLabel>
    </State>
    <State id="shuffle">
        <ValueType boolType="YesNo">Boolean</ValueType>
        <TriggerLabel>Shuffling</TriggerLabel>
        <ControlPageLabel>Shuffling</ControlPageLabel>
    </State>
</States>
<UiDisplayStateId>playStatus</UiDisplayStateId>

You'll recall from the Custom Device Type section of the developers guide, these define the states that are used in various places in the UI and by other objects (triggers, control pages, etc). So, the question is now that the server understands the structure of your devices' states, how do you change them?

It's actually pretty simple. When your plugin detects a change in one of the states, you just call the updateStateOnServer('id', value='value') method. Here are some examples for setting the state based on the above state definitions:

# assume that someMusicServer represents a device with the above states
# to update the volume state
someMusicServer.updateStateOnServer('volume', value=50)

# to update the track name
someMusicServer.updateStateOnServer('track', value='Cluster One')

# to update the album name
someMusicServer.updateStateOnServer('album', value='The Division Bell')

# to update the artist name
someMusicServer.updateStateOnServer('artist', value='Pink Floyd')

# to update the playStatus
someMusicServer.updateStateOnServer('playStatus', value='playing')

# to update the playStatus
someMusicServer.updateStateOnServer('shuffle', value=True)

Note - for states that have a <ValueType> of Number, you pass an integer or float; for states that are Boolean, you pass Python True or False; all others pass a string.

It's just that simple. This will cause any triggers on the server that are set on your device's states to be fired. It will update any visible control pages. It will show the state that's defined in the <UiDisplayStateId> element in the Mac device table's State column.

The updateStateOnServer method has 3 optional parameters: decimalPlaces (integer), triggerEvents (boolean), and uiValue (string, API v1.6+ only).

When updating floating point state values use the decimalPlaces parameter to specify the number of fractional digits to store and display. For example:

someThermmostateDevice.updateStateOnServer('mainTemp' value=76.1234, decimalPlaces=2)

instructs the Indigo Server to store and display the value as 76.12.

The triggerEvents parameter can be set to False (defaults to True) to have the Indigo Server update the state but ignore any Device State Changed triggers that should be processed as a result of the state change.

And the optional uiValue parameter is used to set UI only display string of the value which is not used in triggers or conditional logic. This is useful for adding units, percent signs, etc:

dev.updateStateOnServer('sensorValue', 72.3, uiValue=u'72.3 °F')

All Off

Turns off all devices for all protocols unless a direct parameter is specified. The direct parameter, if specified, will determine which devices will be turned off. In the context of this command, devices are defined as all dimmable (light) and relay (appliance) devices and does not include other device types that may have an on/off state. This command doesn’t work for plugin defined devices regardless of type.

Command Syntax Examples
indigo.device.allOff()
indigo.device.allOff(indigo.kAllDeviceSel.HouseCodeA)
indigo.device.allOff(indigo.kAllDeviceSel.Insteon)
Parameters
Parameter Required Type Description
direct parameter Yes kAllDeviceSel enumerated value to indicate which devices to turn off, all if no parameter is passed - see the kAllDeviceSel enumeration for a full description
All Device Selector Enumeration
indigo.kAllDeviceSel
Enumerated Type Description
Insteonspecify all INSTEON devices that support ON/OFF
X10specify all X10 devices that support ON/OFF
ZWavespecify all Z-Wave devices that support ON/OFF
HouseCodeAspecify all X10 devices in house code A
HouseCodeBspecify all X10 devices in house code B
HouseCodeCspecify all X10 devices in house code C
HouseCodeDspecify all X10 devices in house code D
HouseCodeEspecify all X10 devices in house code E
HouseCodeFspecify all X10 devices in house code F
HouseCodeGspecify all X10 devices in house code G
HouseCodeHspecify all X10 devices in house code H
HouseCodeIspecify all X10 devices in house code I
HouseCodeJspecify all X10 devices in house code J
HouseCodeKspecify all X10 devices in house code K
HouseCodeLspecify all X10 devices in house code L
HouseCodeMspecify all X10 devices in house code M
HouseCodeNspecify all X10 devices in house code N
HouseCodeOspecify all X10 devices in house code O
HouseCodePspecify all X10 devices in house code P

Beep

API v1.11+ only: Requests that the device make an audible beep or buzz. Only supported by some hardware.

Command Syntax Examples
indigo.device.beep(123)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device

Create

Create a device. You can create devices that are defined by your plugin, in other plugins, and X10 devices. You can't currently create devices that use the Insteon or Z-Wave protocol because of the complex synchronization needed during definition. Use this method to create ALL device types - it will return a device of the correct class to you based on the arguments. It can be considered the “device” factory method.

This method returns a copy of the newly created device.

Command Syntax Examples
indigo.device.create(protocol=indigo.kProtocol.Plugin,
    address='F8',
    name='Device Name Here', 
    description='Description Here', 
    pluginId='com.mycompany.pluginId',
    deviceTypeId='myDeviceTypeId',
    props={'propA':'value', 'propB':'value'},
    folder=1234)
Parameters
Parameter Required Type Description
address No string the address of the X10 device - plugins must set an address property in their property dictionary
description No string the description of the device
deviceTypeId Yes string the id of the device type – defined by the plugin or one of the defined X10 devices.
folder No integer id or instance of the folder in which to put the newly created device
name Yes string the name of the device
pluginId No string the plugin ID - defaults to your plugin's id if in a Server Plugin
props No dictionary this is the properties for the device - they will be inserted in to the pluginId's property space as supplied above. If you are creating a device of a type defined in a different plugin, it's that plugin's id and properties.
protocol Yes kProtocol the protocol for the device (indigo.kProtocol.Plugin or indigo.kProtocol.X10)

Delete

Delete the specified device regardless of it’s type.

Command Syntax Examples
indigo.device.delete(123)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device to delete

Duplicate

Duplicate the specified device regardless of the type. This method returns a copy of the new device.

Command Syntax Examples
indigo.device.duplicate(123, duplicateName='New Name')
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device to duplicate
duplicateName No string name for the newly duplicated device

Enable/Disable

Enable/Disable the specified device regardless of the type.

Command Syntax Examples
indigo.device.enable(123, value=True) # enable
indigo.device.enable(123, value=False) # disable
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device to enable/disable
value No boolean True to enable, False to disable

Get Group List

API v1.14+ only: Return an indigo.List with all device IDs in a device group.

Command Syntax Examples
groupList = indigo.device.getGroupList(123)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of any device that belongs to a device group.

getGroupList() is useful to get the main/root device of a device group. Some properties, such as batteryLevel, only exist on the main/root device. In this example we log the batteryLevel for a module given any devices that belong to its group:

groupList = indigo.device.getGroupList(devIdOrInstance)
rootDevice = indigo.devices[groupList[0]]
indigo.server.log('battery level is: ' + str(rootDevice.batteryLevel))

Get Dependencies

Return an indigo.Dict with all the dependencies on this device.

Command Syntax Examples
depDict = indigo.device.getDependencies(123)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device to get the dependencies for.

The dictionary will look something like this:

>>> print indigo.device.getDependencies(91776575)
Data : (dict)
     actionGroups : (list)
          Data : (dict)
               ID : 1280166770 (integer)
               Name : Set var to device state (string)
     controlPages : (list)
     devices : (list)
     schedules : (list)
     triggers : (list)
          Data : (dict)
               ID : 106487666 (integer)
               Name : Thermostat condition test (string)
     variables : (list)

So, the dictionary will have 5 top-level keys: “actionGroups”, “controlPages”, “devices”, “schedules”, “triggers”, and “variables”. Each one of those keys will return a list object. Inside that list object will be multiple dicts, one for each dependency (or an empty list if there are none). Each dependency dictionary has two keys: “ID” which is the unique id and “Name” which is the name of the object.

Move To Folder

Use this command to move the device to a different folder.

Command Syntax Examples
indigo.device.moveToFolder(123, value=987)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
value Yes integer id or instance of the folder to move the device to

Ping Device

API v1.16+ only: Sends the Z-Wave or INSTEON module a ping command and measures the round trip ACK time. Returns a dict containing the Success and TimeDelta (milliseconds) result.

Command Syntax Examples
result = indigo.device.ping(123, suppressLogging=True)
if result["Success"]:
    indigo.server.log("%.3f seconds ping for %s" % (result["TimeDelta"]/1000.0, dev.name))
else:
    indigo.server.log("ping failed for %s" % (dev.name), isError=True)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
suppressLogging No boolean True to keep the request from being logged into the event log window (default is False)

Remove Delayed Actions

This command will remove delayed actions for the specified device.

Command Syntax Examples
indigo.device.removeDelayedActions(123)
Parameters
Parameter Required Type Description
direct parameter No integer id or instance of the device

Reset Accumulated Energy Total

API v1.11+ only: Resets the energyAccumTotal and energyAccumTimeDelta values and changes the energyAccumBaseTime to the server's current datetime.

Command Syntax Examples
indigo.device.resetEnergyAccumTotal(123)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device

Set Remote Display

Use this command to set the remote display flag for the folder.

Command Syntax Examples
indigo.device.displayInRemoteUI(123, value=True)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
value Yes boolean True to display the device on remote user interfaces or False to hide it

Status Request

This tells IndigoServer to send a status request command to the specified device and refresh it’s status.

Command Syntax Examples
indigo.device.statusRequest(123)
indigo.device.statusRequest(123, suppressLogging=True)
Parameters
Parameter Required Type Description
direct parameter Yes integer the id of the device
suppressLogging No boolean True to keep the request from being logged into the event log window (default is False)

Toggle

This tells IndigoServer to toggle a device from on to off or vice versa depending on it’s current state. This command only works for device types that can be turned on and off.

Command Syntax Examples
indigo.device.toggle(123)
indigo.device.toggle(123, delay=10, duration=300)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
delay No integer number of seconds to delay before toggling the device
duration No integer number of seconds delay before the device toggles back to it’s original state

Turn Off

This tells IndigoServer to turn off a device. This command only works for device types that can be turned on and off.

Command Syntax Examples
indigo.device.turnOff(123)
indigo.device.turnOff(123, delay=10, duration=300)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
delay No integer number of seconds to delay before turning off the device
duration No integer number of seconds delay before the device turns back on

Turn On

This tells IndigoServer to turn on a device. This command only works for device types that can be turned on and off.

Command Syntax Examples
indigo.device.turnOn(123)
indigo.device.turnOn(123, delay=10, duration=300)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
delay No integer number of seconds to delay before turning on the device
duration No integer number of seconds delay before the device turns back off

Unlock

API v2.0+ only: This tells IndigoServer to unlock a device. This command only works for relay device types that have pluginProps[“IsLockSubType”] set to True.

Command Syntax Examples
indigo.device.unlock(123)
indigo.device.unlock(123, delay=10, duration=300)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
delay No integer number of seconds to delay before unlocking the device
duration No integer number of seconds delay before the device automatically locks

Lock

API v2.0+ only: This tells IndigoServer to lock a device. This command only works for relay device types that have the property pluginProps[“IsLockSubType”] set to True.

Command Syntax Examples
indigo.device.lock(123)
indigo.device.lock(123, delay=10, duration=300)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
delay No integer number of seconds to delay before locking the device
duration No integer number of seconds delay before the device automatically unlocks
# Creating a device
myDevice = indigo.device.create(protocol=indigo.kProtocol.X10,
    name="Office Lamp",
    description="X10 Lamp module",
    address="F7",
    deviceTypeId="LampLinc Plus Plug-In Dimmer")
# Getting a device
myDevice = indigo.devices[123]
# Getting a device
set myDevice to device "Office Lamp"
# Logging a message if it’s an X10 device
if (myDevice.protocol == indigo.kProtocol.X10):
    indigo.server.log("device is an X10 device")   
# Logging a message if it’s showing in Indigo Touch
if (myDevice.remoteDisplay):
    indigo.server.log("device is showing in Indigo Touch")
# Setting the folder ID that the device is in
indigo.device.setFolder(myDevice, 987)
# Turning off all devices (dimmer and relay)
indigo.device.allOff()

# Turning off all devices in X10 house code A
indigo.device.allOff(indigo.kAllDeviceSel.HouseCodeA)

# Turning off all INSTEON devices
indigo.device.allOff(indigo.kAllDeviceSel.Insteon)
# Turning off all devices (dimmer and relay)
all off

Dimmer devices are dimmable light modules. They can be turned on and off and their brightness may be set. Your script may manipulate any dimmer device. You may specify that devices defined by your plugin are of this type. The standard dimmer UI in the various clients will be presented to users attempting to control your device.

Property Type Writable Description
brightness integer No an integer from 0-100 indicating the brightness of the device - plugin developers may decide if their device may be on but have a brightness of 0 (non-standard) - set using commands below
ledStates list No this is a list of booleans that represent the state of LEDs on the device. So, to check to see if LED 3 is on you'd check dev.ledStates[2] (Python arrays are 0-based so the first element is element 0). Currently, only KeypadLinc devices use this array - however, future devices may use it as well so you should probably check the length first to make sure that the LED you're looking for is actually there. Use the len(dev.ledStates) method to see how many entries there are before you access a specific index.
onState boolean No indicates whether the device is on - shortcut for dev.states['onOffState']

These are the states provided by this device type and accessible through the dev.states dictionary. They are read-only, but if you're a plugin developer you can use the updateStateOnServer() class method to update the value for devices owned by your plugin.

State ID Type Property Name Notes
brightnessLevel integer brightness brightness of the device - value is in the range of 0 to 100. Can be accessed by dev.brightness
onOffState boolean onState indicates whether the device is on - can be accessed by dev.onState.

All Lights Off

Turns off all lights for all protocols unless a direct parameter is specified. The direct parameter, if specified, will determine which lights will be turned off. Lights are defined as all dimmable devices. This command doesn’t work for plugin defined devices regardless of type.

Command Syntax Examples
indigo.dimmer.allLightsOff()
indigo.dimmer.allLightsOff(indigo.kAllDeviceSel.HouseCodeA)
indigo.dimmer.allLightsOff(indigo.kAllDeviceSel.Insteon)
Parameters
Parameter Required Type Description
direct parameter No kAllDeviceSelenumerated value to indicate which devices to turn off, all if no parameter is passed - see the kAllDeviceSel enumeration for a full description

All Lights On

Turns on all lights for all protocols unless a direct parameter is specified. The direct parameter, if specified, will determine which lights will be turned on. Lights are defined as all dimmable devices. This command doesn’t work for plugin defined devices regardless of type.

Command Syntax Examples
indigo.dimmer.allLightsOn()
indigo.dimmer.allLightsOn(indigo.kAllDeviceSel.HouseCodeA)
indigo.dimmer.allLightsOn(indigo.kAllDeviceSel.Insteon)
Parameters
Parameter Required Type Description
direct parameter No kAllDeviceSel enumerated value to indicate which lights to turn on, all if no parameter is passed - see the kAllDeviceSel enumeration for a full description

Brighten

Changes the brightness of the specified light relative to the current brightness.

Command Syntax Examples
indigo.dimmer.brighten('Office Lamp')
indigo.dimmer.brighten(123)
indigo.dimmer.brighten('Office Lamp', by=50, delay=4)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
by No integer relative amount to brighten by where brightness is 0-100
delay No integer number of seconds to delay before executing the brighten command

Dim

Dim the brightness of the specified light by some amount relative to the current brightness.

Command Syntax Examples
indigo.dimmer.dim('Office Lamp')
indigo.dimmer.dim(123)
indigo.dimmer.dim('Office Lamp', by=50, delay=4)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
by No integer relative amount to dim by where dimness is 0-100
delay No integer number of seconds to delay before executing the dim command

Set Brightness

Changes the brightness of the specified light to a specific value.

Command Syntax Examples
indigo.dimmer.setBrightness(123, value=75)
indigo.dimmer.setBrightness(123, value=75, delay=360)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
value Yes integer absolute value to set the brightness to on a scale of 0-100
delay No integer number of seconds to delay before executing the dim command

Set LED State

Turns on/off the specified LED. Useful for KeypadLinc (and similar) devices. Note: you can't use this method to control the LED of the button(s) that control the direct load - use Turn ON/Turn OFF for those.

Command Syntax Examples
indigo.dimmer.setLedState(123, index=0, value=True)
indigo.dimmer.setLedState(123, index=0, value=True, suppressLogging=True)
indigo.dimmer.setLedState(123, index=0, value=True, updateStatesOnly=True)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
index Yes integer the index of the button. Recall that Python-based arrays are 0-based, so the index is also 0-based. That is, the first object in an array is object 0.
value Yes boolean True to turn on the LED, False to turn it off
suppressLogging No boolean True to suppress logging (defaults to False)
updateStatesOnly No boolean True to only update Indigo's internal state - no command will be sent to the KPL (defaults to False)

Set Color Levels

Sets the color levels for the dimmer device. The levels are the same as brightness, so 0 to 100, except for whiteTemperature which ranges from 1200-15000. Real number precision is allowed and the actions UI will display precision up to the hundredths digit, allowing for relatively good precision if a plugin needs to convert between RGB and HSB.

Some RGBW devices (Aeotec bulb) support 2 different white channels with unique white temperatures: warm and cool. In those cases both whiteLevel and whiteLevel2 can be used. Other white color devices allow for a specific temperature value to be specified (in Kelvin). For those devices you would use both the whiteLevel parameter in combination with the whiteTemperature parameter. Note for specifying white color temperature devices should support either the 2 white level technique, or the single white level + white temperature technique. That is, if the whiteLevel2 parameter is used then whiteTemperature will be ignored.

Command Syntax Examples
indigo.dimmer.setColorLevels(device,
               redLevel,
               greenLevel,
               blueLevel,
               whiteLevel,
               whiteLevel2,
               whiteTemperature,
               delay,
               suppressLogging,
               updateStatesOnly
)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
redLevel No integer 0 - 100
greenLevel No integer 0 - 100
blueLevel No integer 0 - 100
whiteLevel No integer 0 - 100
whiteLevel2 No integer 0 - 100
whiteTemperature No integer 1200 - 15000
delay No integer Defaults to 0.
suppressLogging No integer Defaults to False
updateStatesOnly No integer is an argument that exists on several device instance APIs that has Indigo update its device state/UI but does not have the corresponding action sent out to physical module. The use cases for this are pretty few, but sometimes you just want the internal state to update and can skip the actual command to the module. Defaults to False

A note about setting color levels: RGB values are expressed as values from 0 to 255, however, Indigo stores those values from 0 to 100. This requires the RGB values to be converted which is very easy.

# RGB value / 255 * 100
redLevel = 128 
newRedLevel = redLevel / 255 * 100

Set On State

Use the Turn On, Turn Off, and Toggle methods to turn on/off a dimmer device.

Here are examples of device properties:

# Getting a device
myDevice = indigo.devices[123]
# Set a device’s brightness to 75 if it’s currently
# less than that, but only if it’s turned on
myDevice = indigo.devices[123]
if ((myDevice.brightness < 75) and 
    (myDevice.onState)):
	indigo.dimmer.setBrightness(myDevice, 75)
# Brighten a light by 25% after 10 minutes
indigo.dimmer.brighten(123, by=25, delay=600)
# Logging a message if it’s showing in Indigo Touch
myDevice = indigo.devices[123] 
if (myDevice.remoteDisplay):
	indigo.server.log("device is showing in Indigo Touch")
# Getting the folder ID that the device is in
myDevice = indigo.devices[123]
myDevice.folderId
# OR
indigo.devices[123].folderId # see comments below

You might look at the second example above, and wonder why we didn’t do something like this:

# Set a device’s brightness to 75 if it’s currently
# less than that, but only if it’s turned on
myDevice = indigo.devices[123] 
if ((indigo.devices[123].brightness < 75) and 
    (indigo.devices[123].onState)):
	indigo.dimmer.setBrightness(indigo.devices[123], 75)

That code works correctly, but is very inefficient. The Python to C++ bridge will cause a copy of the object to be made every time indigo.devices[123] is used since the devices list is a C++ object, but the object returned from it using the id subscript is bridged to a Python object, and all bridged objects are copies. So, the code directly above will create 3 copies of the device object - very inefficient. The code in the example above gets a single copy of the object and uses that in all the rest of the code. A good rule of thumb is to get an explicit copy of an object if you need to use it more than once.

I/O devices have a wide variety of capabilities that we’ve tried to boil down to some specifics. The I/O devices that Indigo supports generally have some combination of three types of inputs: analog, binary, and sensor. They may also support some number of binary outputs.

All outputs are modified using commands below.

Property Type Writable Description
analogInputs list of integer No a list of the current analog input values, one per input, in a python list - can be accessed individually using the states below
analogInputCount integer No number of analog inputs this device supports
binaryInputs list of boolean No a list of the current binary input values, one per input - can be accessed individually using the states below
binaryInputCount integer No number of binary inputs this device supports
binaryOutputs list of boolean No a list of the current binary output values, on per output (max 12 total outputs) - can be accessed individually using the states below
binaryOutputCount integer No number of binary outputs this device supports
sensorInputCount integer No number of sensor inputs this device supports
sensorInputs list of integer No a list of the current sensor input values, one per input - can be accessed individually using the states below

These are the states provided by this device type and accessible through the dev.states dictionary. They are read-only.

State ID Type Property Name Notes
analogInput# integer N/A value of input number represented by the # sign (input 1 would be analogInput1) - there will only be dev.analogInputCount inputs available
analogInputsAll string N/A a comma separated list of all analog input values. Can be accessed as a Python list of integers by using dev.analogInputs.
binaryInput# boolean N/A value of input number represented by the # sign (input 1 would be binaryInput1) - there will only be dev.binaryInputCount inputs available
binaryInputsAll string N/A a comma separated list of all binary input values. Can be accessed as a Python list of booleans by using dev.binaryInputs.
binaryOutput# boolean N/A value of output number represented by the # sign (output 1 would be binaryOutput1) - there will only be dev.binaryOutputCount outputs available
binaryOutputsAll string N/A a comma separated list of all binary output values. Can be accessed as a Python list of booleans by using dev.binaryOutputs.
sensorInput# integer N/A value of input number represented by the # sign (input 1 would be sensorInput1) - there will only be dev.sensorInputCount inputs available
sensorInputsAll string N/A a comma separated list of all binary input values. Can be accessed as a Python list of booleans by using dev.sensorInputs.

Set Binary Output

Set the state of the specified binary output.

Command Syntax Examples
indigo.iodevice.setBinaryOutput(123, index=2, value=True)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
index Yes integer 0-based index of the output to change - should be less than the binaryOutputCount property of the device
value Yes boolean True to turn the output on, False to turn it off
# If binary input 3 is true, set binary output 1
# to false (python arrays are 0-based)
myIODevice = indigo.devices[123]
if (!myIODevice.binaryInputs[2]):
	indigo.iodevice.setBinaryOutput(myIODevice, 
		index=1,
		value=False)

Some sensor devices, like motion sensors, are treated differently in Indigo. They don’t generally maintain state - so there’s no concept of a sensor being on/off: in the case of a motion sensor, detecting motion and not detecting motion.

They generally send a command of some type when they detect some condition and send another command when they stop detecting it. However, dealing with them in Indigo as if they maintain state is much more useful in many cases. So, Indigo will attempt to maintain a virtual state for each motion sensor if configured that way. Currently, the following devices fall under this category:

  • X10 Motion Sensors
  • the Wireless INSTEON Motion / Occupancy Sensor (2420M) from SmartLabs
  • the TriggerLinc from SmartLabs
  • the SynchroLinc from SmartLabs
Property Type Writable Min API Description
allowOnStateChange boolean No 1.6 True if UI controls should be shown or enabled to change the onState
allowSensorValueChange boolean No 1.6 True if UI controls should be shown or enabled to change the sensorValue
onState boolean No 1.0 indicates that the device is currently in a triggered or ON state (None if sensor doesn't support ON/OFF)
sensorValue integer or float No 1.6 the numerical value of a sensor, such as temperature (None if sensor doesn't support sensor values)

Set On State

Set the sensor onState property. Normally this is unnecessary since Indigo will maintain it for you so this method is provided mainly for testing and error recovery.

Command Syntax Examples
indigo.sensor.setOnState(123, value=True)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
value Yes boolean True to set Indigo’s state to on, False to set it to off

– none –

Relay devices are very simple devices, often times called appliance modules. They can be turned on and off only. Your script may manipulate any relay device. Your plugin may specify devices that are of this type and the standard relay UI in the various clients will be presented to users when controlling it.

Property Type Description
ledStates list No this is a list of booleans that represent the state of LEDs on the device. So, to check to see if LED 3 is on you'd check dev.ledStates[2] (Python arrays are 0-based so the first element is element 0). Currently, only KeypadLinc devices use this array - however, future devices may use it as well so you should probably check the length first to make sure that the LED you're looking for is actually there. Use the len(dev.ledStates) method to see how many entries there are before you access a specific index.
onState boolean No indicates whether the device is on - shortcut to dev.states['onOffState']

These are the states provided by this device type and accessible through the dev.states dictionary. They are read-only, but if you're a plugin developer you can use the updateStateOnServer() class method to update the value for devices owned by your plugin.

State ID Type Property Name Notes
onOffState boolean onState indicates whether the device is on - use dev.onState property as a shortcut

Use the Turn On, Turn Off, and Toggle methods in the indigo.device.* namespace to turn on/off a relay device.

Set LED State

Turns on/off the specified LED. Useful for KeypadLinc (and similar) devices. Note: you can't use this method to control the LED of the button(s) that control the direct load - use Turn ON/Turn OFF for those.

Command Syntax Examples
indigo.relay.setLedState(123, index=0, value=True)
indigo.relay.setLedState(123, index=0, value=True, suppressLogging=True)
indigo.relay.setLedState(123, index=0, value=True, updateStatesOnly=True)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
index Yes integer the index of the button. Recall that Python-based arrays are 0-based, so the index is also 0-based. That is, the first object in an array is object 0.
value Yes boolean True to turn on the LED, False to turn it off
suppressLogging No boolean True to suppress logging (defaults to False)
updateStatesOnly No boolean True to only update Indigo's internal state - no command will be sent to the KPL (defaults to False)
# Toggle the device
indigo.device.toggle(123)

Speed control devices are generally controllers for motors of some type. The first implementation was for the INSTEON FanLinc, which is a ceiling fan motor controller. This device type provides two different methods of setting the speed of the motor: by level, which ranges from 0 (off) to 100 (full on), and by index. With a device like a FanLinc, for instance, you can't set an arbitrary speed - you can only set it to some number of fixed speeds and this is what index is for. The FanLinc will in fact respond to setting the level, but we normalize the level to the appropriate speed. Other speed control devices may not choose to do so.

Property Type Writable Description
onState boolean No indicates whether the device is on - shortcut to dev.states['onOffState']
speedIndex integer No indicates the current speed index for devices that support some fixed # of speeds - shortcut to dev.states['speedIndex']
speedIndexCount integer No indicates the number of indexes available for this device (defaults to 4)
speedLevel integer No indicates the level the device is set to (0-100) - shortcut to dev.states['speedLevel']

These are the states provided by this device type and accessible through the dev.states dictionary. They are read-only, but if you're a plugin developer you can use the updateStateOnServer() class method to update the value for devices owned by your plugin.

State ID Type Property Name Notes
onOffState boolean onState indicates whether the device is on - use dev.onState property as a shortcut
speedIndex boolean speedIndex indicates the current speed index for devices that support some fixed # of speeds - use dev.speedIndex property as a shortcut
speedIndex.ui string n/a a more user friendly name for the current index (e.g. high, medium, low, off)
speedLevel integer speedLevel indicates the level the device is set to (0-100) - use dev.speedLevel property as a shortcut

Decrease Speed Index

Decreases the speed index.

Command Syntax Examples
indigo.speedcontrol.decreaseSpeedIndex(123)
indigo.speedcontrol.decreaseSpeedIndex(123, by=2)
indigo.speedcontrol.decreaseSpeedIndex(123, delay=10)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
by No integer the number of index positions to decrease by. Defaults to 1 if not specified.
delay No integer delays the command by the specified number of seconds. Defaults to no delay if not specified.

Increase Speed Index

Increases the speed index.

Command Syntax Examples
indigo.speedcontrol.increaseSpeedIndex(123)
indigo.speedcontrol.increaseSpeedIndex(123, by=2)
indigo.speedcontrol.increaseSpeedIndex(123, delay=10)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
by No integer the number of index positions to increase by. Defaults to 1 if not specified.
delay No integer delays the command by the specified number of seconds. Defaults to no delay if not specified.

Set Speed Index

Sets the speed index to the specified value.

Command Syntax Examples
indigo.speedcontrol.setSpeedIndex(123, value=2)
indigo.speedcontrol.increaseSpeedIndex(123, value=2, delay=10)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
value Yes integer index position to set the index to.
delay No integer delays the command by the specified number of seconds. Defaults to no delay if not specified.

Set Speed Level

Sets the speed index to the specified value.

Command Syntax Examples
indigo.speedcontrol.setSpeedLevel(123, value=50)
indigo.speedcontrol.setSpeedLevel(123, value=75, delay=10)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
value Yes integer level of the motor control, from 0-100.
delay No integer delays the command by the specified number of seconds. Defaults to no delay if not specified.

Sprinkler devices generally have some number of sprinkler zones.

Property Type Writable Min API Description
activeZone integer No 1.0 the 1-based index of the active zone (None=all zones off, 1=zone 1, 2=zone 2, …). Note this property has undergone changes in name (previously called activeZoneIndex) as well as semantics (previously the index being 0-based).
zoneCount integer No 1.0 the number of zones available for this sprinkler
zoneEnableList list of boolean No 1.13 list of booleans, starting at zone 1 through zone [zoneCount], that specify if a given zone is enabled (has a maximum zone duration > 0).
zoneNames list of string No 1.0 list of zone names, starting at zone 1 through zone [zoneCount]. You must include zoneCount strings in the list.
zoneMaxDurations list of floats No 1.0 list of zone durations in minutes, starting at zone 1 through zone [zoneCount]. You must include zoneCount integers in the list.
zoneScheduledDurations list of floats No 1.0 list of currently active zone durations in minutes if a schedule is running (empty list if no schedule is running), starts at zone 1 through zone [zoneCount]
pausedScheduleZone integer No 1.16 the 1-based index of the paused sprinkler zone index (None=schedule not paused, 1=zone 1 paused, 2=zone 2 paused, …).
pausedScheduleRemainingZoneDuration float No 1.16 the paused sprinkler zone duration in minutes (None if schedule not paused)

These are the states provided by this device type and accessible through the dev.states dictionary. They are read-only.

State ID Type Property Name Notes
activeZone integer activeZone the number of the active zone, 0 if off (1=zone 1, 2=zone 2, etc)
activeZone.ui string N/A the active zone as a human readable string
zone# boolean N/A replace the # with the zone number (up to dev.zoneCount) to return whether the zone is running or not

Next Zone

Set the sprinkler to the next zone, and turn off if it’s the last defined zone.

Command Syntax Examples
indigo.sprinkler.nextZone(123)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device

Pause Schedule

Pause the current sprinkler schedule but keep it active so it can be resumed.

Command Syntax Examples
indigo.sprinkler.pause(123)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device

Previous Zone

Set the sprinkler to the previous zone, and turn off if it’s the first defined zone.

Command Syntax Examples
indigo.sprinkler.previousZone(123)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device

Resume Schedule

Resume the current sprinkler schedule.

Command Syntax Examples
indigo.sprinkler.resume(123)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device

Run Schedule

Run a sprinkler schedule.

Command Syntax Examples
indigo.sprinkler.run(123, schedule=[10, 15, 8, 0, 0, 0, 0, 0])
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
schedule Yes list of reals list of reals representing the number of minutes to run for each zone - the list must have [zoneCount] elements, with 0 for any zone that shouldn’t run

Stop Schedule

Stop the current sprinkler schedule and clear it.

Command Syntax Examples
indigo.sprinkler.stop(123)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device

Set Active Zone

API v1.12+ only: Turn on a specific zone.

Command Syntax Examples
indigo.sprinkler.setActiveZone(123, index=2)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
index Yes integer 1-based index of the zone to turn on
# run schedule
indigo.sprinkler.run(123, 
    schedule=[10,15,8, 0, 0, 0, 0, 0])

Thermostats have a wide variety of capabilities that we’ve tried to boil down to some specifics. They can have multiple temperature and humidity sensors and–depending on the device capabilities and region–may have a fan mode, an HVAC mode (heating, cooling, etc) and associated setpoints. Note: some thermostats don’t support getting the equipment state values: coolIsOn, fanIsOn, heatIsOn, dehumidifierIsOn, and humidifierIsOn. For those thermostats those properties will always be False.

Property Type Writable Min API Description
coolIsOn boolean No 1.0 is the cooling system (compressor) currently running - shortcut for dev.states['hvacCoolerIsOn']. This property is always present and will be False if the corresponding state dev.states['hvacCoolerIsOn'] is not present.
coolSetpoint float No 1.0 current cool setpoint value - shortcut for dev.states['setpointCool']
dehumidifierIsOn boolean No 1.7 is the dehumidifier currently turned ON - shortcut for dev.states['hvacDehumidifierIsOn']
fanMode kFanMode No 1.0 the operating mode for the fan attached to the thermostat - shortcut for dev.states['hvacFanMode']
fanIsOn boolean No 1.0 is the fan currently running - shortcut for dev.states['hvacFanIsOn']
heatIsOn boolean No 1.0 is the heater currently running - shortcut for dev.states['hvacHeaterIsOn']. This property is always present and will be False if the corresponding state dev.states['hvacHeaterIsOn'] is not present.
heatSetpoint float No 1.0 current heat setpoint value - shortcut for dev.states['setpointHeat']
humidities list of float No 1.0 a list of floating point values representing the current values of all humidity sensors connected to the thermostat
humiditySensorCount integer No 1.0 number of humidity sensors this thermostat supports
humidifierIsOn boolean No 1.7 is the humidifier currently turned ON - shortcut for dev.states['hvacHumidifierIsOn']
hvacMode kHvacMode No 1.0 the operating mode for the HVAC system attached to the thermostat - shortcut for dev.states['hvacOperationMode']
temperatureSensorCount integer No 1.0 number of temperature sensors this thermostat supports
temperatures list of float No 1.0 a list of floating point values representing the current values of all temperature sensors connected to the thermostat

To check whether the thermostat device actually supports the coolIsOn and heatIsOn properties, one can check:

support_heat_and_cool = dev.pluginProps.get("ShowCoolHeatEquipmentStateUI", False)
Plugin Capabilities

These pluginProps can be updated by a plugin to describe the capabilities for a particular thermostat instance. Some of these are useful to provide a higher-level abstraction for accessing/changing thermostat properties or states.

Property Type Writeable Description
NumTemperatureInputs Integer Yes should range between 1 and 3
NumHumidityInputs Integer Yes should range between 0 and 3
SupportsHeatSetpoint Boolean Yes True or False
SupportsCoolSetpoint Boolean Yes True or False
SupportsHvacOperationMode Boolean Yes True or False
SupportsHvacFanMode Boolean Yes True or False
ShowCoolHeatEquipmentStateUI Boolean Yes True or False

Some of these are reflected as attributes in the device instance as well:

Attribute Read-Only
dev.hvacMode Yes
dev.fanMode Yes
dev.coolSetpoint Yes
dev.heatSetpoint Yes
dev.temperatureSensorCount Yes
dev.temperatures Yes
dev.humiditySensorCount Yes
dev.humidities Yes
dev.coolIsOn Yes
dev.heatIsOn Yes
dev.fanIsOn Yes
dev.dehumidifierIsOn Yes
dev.humidifierIsOn Yes
dev.supportsHvacFanMode Yes
dev.supportsHvacOperationMode Yes
dev.supportsCoolSetpoint Yes
dev.supportsHeatSetpoint Yes

More information on how to use these Thermostat properties and attributes can be found in the Example Device - Thermostat.indigoPlugin in the Indigo Plugin SDK.

Fan Mode Enumeration
indigo.kFanMode
Value Description
AlwaysOnsignal the fan that it should be running continuously
Autosignal the fan that it should only run when the HVAC system needs it to be running
HVAC Mode Enumeration
indigo.kHvacMode
Value Description
Coolthe hvac system is only reacting to cool setpoints
HeatCoolthe hvac system is reacting to both cool and heat setpoints
Heatthe hvac system is only reacting to and heat setpoints
Offthe hvac system is turned off
ProgramHeatCoolthe hvac system is executing it’s built-in automatic program, which usually responds to both heat and cool setpoints
ProgramCoolthe hvac system is executing it’s built-in cooling program
ProgramHeatthe hvac system is executing it’s built-in heating program

These are the states provided by this device type and accessible through the dev.states dictionary. They are read-only, but if you're a plugin developer you can use the updateStateOnServer() class method to update most of these states for devices owned by your plugin (exceptions are noted below).

State ID Type Property Name Notes
humidityInput# float N/A replace the # with the humidity sensor # (up to humiditySensorCount) to directly access the humidity value for that input
humidityInputsAll string N/A a comma separated list of all humidity values
hvacCoolerIsOn boolean coolIsOn True if the cooling system currently running
hvacDehumidifierIsOn boolean dehumidifierIsOn True if the dehumidifier is currently running
hvacFanIsOn boolean fanIsOn True if the fan currently running
hvacFanMode kFanMode fanMode operating mode for the fan attached to the thermostat
hvacFanIsAlwaysOn boolean N/A True if the fan mode is set to AlwaysOn. Note: this state can't be directly updated but rather will be updated automatically when you update hvacFanMode.
hvacFanIsAuto boolean N/A True if the fan mode is set to Auto. Note: this state can't be directly updated but rather will be updated automatically when you update hvacFanMode.
hvacHeaterIsOn boolean heatIsOn True if the heating system currently running
hvacHumidifierIsOn boolean humidifierIsOn True if the humidifier is currently running
hvacOperationMode kHvacMode hvacMode operating mode for the HVAC system attached to the thermostat
hvacOperationModeIsAuto boolean N/A True if the HVAC is set to HeatCool. Note: this state can't be directly updated but rather will be updated automatically when you update hvacOperationMode.
hvacOperationModeIsCool boolean N/A True if the HVAC is set to Cool. Note: this state can't be directly updated but rather will be updated automatically when you update hvacOperationMode.
hvacOperationModeIsHeat boolean N/A True if the HVAC is set to Heat. Note: this state can't be directly updated but rather will be updated automatically when you update hvacOperationMode.
hvacOperationModeIsOff boolean N/A True if the HVAC is set to Off. Note: this state can't be directly updated but rather will be updated automatically when you update hvacOperationMode.
hvacOperationModeIsProgramAuto boolean N/A True if the HVAC is set to ProgramHeatCool. Note: this state can't be directly updated but rather will be updated automatically when you update hvacOperationMode.
hvacOperationModeIsProgramCool boolean N/A True if the HVAC is set to ProgramCool. Note: this state can't be directly updated but rather will be updated automatically when you update hvacOperationMode.
hvacOperationModeIsProgramHeat boolean N/A True if the HVAC is set to ProgramHeat. Note: this state can't be directly updated but rather will be updated automatically when you update hvacOperationMode.
setpointCool float coolSetpoint the cool setpoint
setpointHeat float heatSetpoint the heat setpoint
temperatureInput# float N/A replace the # with the temperature sensor # (up to temperatureSensorCount) to directly access the humidity value for that input
temperatureInputsAll string N/A a comma separated list of all temperature values

Decrease Cool Setpoint

Decrease the cool setpoint by a delta value.

Command Syntax Examples
indigo.thermostat.decreaseCoolSetpoint(123)
indigo.thermostat.decreaseCoolSetpoint(123, delta=5)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
delta No integer Number of degrees to decrease the cool setpoint. If unspecified, the change will be equal to one degree.

Decrease Heat Setpoint

Decrease the heat setpoint by a delta value.

Command Syntax Examples
indigo.thermostat.decreaseHeatSetpoint(123)
indigo.thermostat.decreaseHeatSetpoint(123, delta=5)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
delta No integer Number of degrees to decrease the heat setpoint. If unspecified, the change will be equal to one degree.

Increase Cool Setpoint

Increase the cool setpoint by a delta value.

Command Syntax Examples
indigo.thermostat.increaseCoolSetpoint(123)
indigo.thermostat.increaseCoolSetpoint(123, delta=5)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
delta No integer Number of degrees to increase the cool setpoint. If unspecified, the change will be equal to one degree.

Increase Heat Setpoint

Increase the heat setpoint by a delta value.

Command Syntax Examples
indigo.thermostat.increaseHeatSetpoint(123)
indigo.thermostat.increaseHeatSetpoint(123, delta=5)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
delta No integer Number of degrees to increase the heat setpoint. If unspecified, the change will be equal to one degree.

Set Cool Setpoint

Set the cool setpoint to an absolute temperature.

Command Syntax Examples
indigo.thermostat.setCoolSetpoint(123, value=78)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
value Yes integer the absolute temperature of the setpoint

Set Fan Mode

Adjust the fan mode.

Command Syntax Examples
indigo.thermostat.setFanMode(123, value=indigo.kFanMode.AlwaysOn)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
value Yes kFanMode the operating mode for the fan

Set Heat Setpoint

Set the heat setpoint to an absolute temperature.

Command Syntax Examples
indigo.thermostat.setHeatSetpoint(123, value=78)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
value Yes integer the absolute temperature of the setpoint

Set HVAC Mode

Adjust the HVAC mode.

Command Syntax Examples
indigo.thermostat.setHvacMode(123, value=indigo.kHvacMode.HeatCool)
Parameters
Parameter Required Type Description
direct parameter Yes integer id or instance of the device
value Yes kHvacMode HVAC mode identifier
# increase the cool setpoint by 5 degrees
indigo.thermostat.decreaseCoolSetpoint(123, delta=5)


# set the thermostat mode to auto
indigo.thermostat.setHvacMode(123, 
    value=indigo.kHvacMode.HeatCool)

# set the heat setpoint to 78
indigo.thermostat.setHeatSetpoint(123, value=78)
  • /www/perceptive/wiki/data/pages/indigo_2023.2_documentation/device_class.txt
  • Last modified: 2024/09/02 21:03
  • by davel17