Device Base Class¶
The Device class is generally used as a base class - your script will use objects that are instances of one of its 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 the following properties.
Class 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 its 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¶
Note
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 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) |
Note
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 |
Device Base Class Instance Methods¶
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, value, clearErrorState) |
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 Indigo 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. |
Command Syntax 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)
Command Syntax 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.
About Plugin Properties¶
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 its 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 the properties for your plugin in the device, you can just set them all in one call:
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:
That will completely remove your properties from the device.
About Custom Device States¶
If your plugin defines custom devices, they will also need to define a collection of custom 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')
Commands (indigo.device.*)¶
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 |
Insteon |
specify all Insteon devices that support ON/OFF |
X10 |
specify all X10 devices that support ON/OFF |
ZWave |
specify all Z-Wave devices that support ON/OFF |
HouseCodeA |
specify all X10 devices in house code A |
HouseCodeB |
specify all X10 devices in house code B |
HouseCodeC |
specify all X10 devices in house code C |
HouseCodeD |
specify all X10 devices in house code D |
HouseCodeE |
specify all X10 devices in house code E |
HouseCodeF |
specify all X10 devices in house code F |
HouseCodeG |
specify all X10 devices in house code G |
HouseCodeH |
specify all X10 devices in house code H |
HouseCodeI |
specify all X10 devices in house code I |
HouseCodeJ |
specify all X10 devices in house code J |
HouseCodeK |
specify all X10 devices in house code K |
HouseCodeL |
specify all X10 devices in house code L |
HouseCodeM |
specify all X10 devices in house code M |
HouseCodeN |
specify all X10 devices in house code N |
HouseCodeO |
specify all X10 devices in house code O |
HouseCodeP |
specify all X10 devices in house code P |
Beep¶
Note
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 its 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
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 Dependencies¶
Return an indigo.Dict with all the dependencies on this device.
Command Syntax Examples
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 6 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.
Get Group List¶
Note
API v1.14+ only
Return an indigo.List with all device IDs in a device group.
Command Syntax Examples
Returns an indigo.List of all devices grouped with dev
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))
See also indigo.device.groupWithDevice() and indigo.device.ungroupDevice().
Group With Device¶
To group two or more devices together, use the indigo.device.groupWithDevice() command. The parameters are the Indigo Device object IDs of the devices to be grouped. Note if you have the device dialog UI open, it will not dynamically update, and you shouldn’t call either method if the device factory UI is open.
Command Syntax Examples
indigo.device.groupWithDevice(dev_1, dev_2)
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| direct parameter (dev_1) | Yes | integer | id, name or instance of a device that will belong to the group. |
| direct parameter (dev_2) | Yes | integer | id, name or instance of another device that will belong to the group. |
For example, if you want to group devices 123 and 456, you would use indigo.device.groupWithDevice(123, 456). There is no message printed to the events log if the devices grouped together successfully. If you want to add device 789 to the group, you would use indigo.device.groupWithDevice(456, 789). This is a great way to bring together different devices that have a common thread, but bear in mind that it's best not to try to group too many devices together. See also indigo.device.ungroupDevice() and indigo.device.getGroupList().
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¶
Note
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¶
Note
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 its 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 its 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 |
Ungroup With Device¶
If you want to remove a device from a group, use the indigo.device.ungroupDevice() command. Use this command with the ID of the device you want removed from the group.Note if you have the device dialog UI open, it will not dynamically update, and you shouldn’t call either method if the device factory UI is open.
Command Syntax Examples
indigo.device.ungroupDevice(dev)
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| direct parameter | Yes | integer | id, name or instance of the device to be removed from the group. |
If successful, nothing will be printed to the events log. See also indigo.device.groupWithDevice() and indigo.device.getGroupList().
Unlock¶
Note
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¶
Note
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 |
Command Syntax Examples
# 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 copy of a device
myDevice = indigo.devices[123]
# 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)