====== 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')''// ===== Device Base Class ===== 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. ==== Device Base Class Properties ==== ^Property ^ Type ^ Writable ^Description ^ |//''address''//| string | No |the address for the device | |//''batteryLevel''//| integer | No |battery level for the device - //''None''// if the device doesn't support battery operation - shortcut for //''dev.states['batteryLevel']''// | |//''buttonGroupCount''//| integer | No |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 |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 |a description of the device as specified by the user| |//''deviceTypeId''//| string | No |the typeId specified in the Devices.xml (or it’s documentation) - only used for plugin defined devices| |//''displayStateId''//| string | No |API v1.15+ only: main display stateId key which can be used as a key into states[] property below| |//''displayStateValRaw''//| boolean integer string or none | No |API v1.15+ only: raw value of main display state (ex: 72.0)| |//''displayStateValUi''//| string | No |API v1.15+ only: UI value (string) of main display state (ex: '72.0°F' )| |//''displayStateImageSel''//| ''//[[#state_image_sel_enumeration|kStateImageSel]]//'' | No |API v1.18+ only: 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 |is the device enabled - set using the //''indigo.device.enable()''// method| |//''energyCurLevel''//| float | No |API v1.11+ only: current Wattage energy being used by the device (None if not supported)| |//''energyAccumTotal''//| float | No |API v1.11+ only: current accumulated energy used since last base time specified in //''energyAccumBaseTime''// (None if not supported)| |//''energyAccumBaseTime''//| datetime | No |API v1.11+ only: the base time from which to calculate the energy total (//''energyAccumTotal''//) (None if not supported)| |//''energyAccumTimeDelta''//| integer | No |API v1.11+ only: the time delta in seconds since the last base time (None if not supported)| |//''folderId''//| integer | No |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 |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|About Plugin Properties]] below for details| |//''id''//| integer | No |id or instance of the device, assigned on creation by IndigoServer| |//''lastChanged''//| datetime | No |the last date/time that the device was changed - populated by IndigoServer| |//''model''//| string | No |the model name of the device - defined either by Indigo based on type or by the plugin's device definition| |//''name''//| string | Yes |the unique name of the device - no two devices can have the same name| |//''ownerProps''//| dictionary | No |API v1.20+ only: 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 |if protocol is //''Plugin''//, the string ID for the plugin| |//''pluginProps''//| dictionary | No |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|About Plugin Properties]] below for details - use //''replacePluginPropsOnServer()''// method to change| |//''protocol''//| ''//[[#protocol_enumeration|kProtocol]]//'' | No |an enumeration specifying the kProtocol of the device - see protocol enumeration below for possible values| |//''remoteDisplay''//| boolean | Yes |should this device be displayed in remote clients (IWS, Indigo Touch, etc) - may also be set with //''indigo.device.displayInRemoteUI()''//| |//''states''//| dictionary | No |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 |indicates that this device should react to all lights On and all lights Off commands - always False for plugin defined devices| |//''supportsAllOff''//| boolean | No |indicates that this device should react to all Off commands - always False for plugin defined devices| |//''supportsStatusRequest''//| boolean | No |indicates if the device supports querying the status - always False for plugin defined 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: note Indigo Touch and Indigo client UI do not currently have icons for every image selector listed below. ^ 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)| |//''None''// |overrides to show no device image icon| |//''Error''// |overrides to show an error device image icon| |//''Custom''// |overrides to show a plugin defined custom image icon (not yet implemented)| |//''PowerOff''// |overrides to show a power off icon| |//''PowerOn''// |overrides to show a power on icon| |//''DimmerOff''// |overrides to show a dimmer or bulb off icon| |//''DimmerOn''// |overrides to show a dimmer or bulb on icon| |//''FanOff''// |overrides to show a fan off icon| |//''FanLow''// |overrides to show a fan on (low) icon| |//''FanMedium''// |overrides to show a fan on (medium) icon| |//''FanHigh''// |overrides to show a fan on (high) icon| |//''SprinklerOff''// |overrides to show a sprinkler off icon| |//''SprinklerOn''// |overrides to show a sprinkler off icon| |//''HvacOff''// |overrides to show a thermostat off icon| |//''HvacCoolMode''// |overrides to show a thermostat in cool mode icon| |//''HvacHeatMode''// |overrides to show a thermostat in heat mode icon| |//''HvacAutoMode''// |overrides to show a thermostat in auto mode icon| |//''HvacFanOn''// |overrides to show a thermostat with fan blower on only icon| |//''HvacCooling''// |overrides to show a thermostat that is cooling icon| |//''HvacHeating''// |overrides to show a thermostat that is heating 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)| |//''EnergyMeterOff''// |overrides to show an energy meter off icon| |//''EnergyMeterOn''// |overrides to show an energy meter on icon| |//''LightSensor''// |overrides to show a light meter off icon| |//''LightSensorOn''// |overrides to show a light meter on icon| |//''MotionSensor''// |overrides to show a motion sensor icon| |//''MotionSensorTripped''// |overrides to show a motion sensor tripped/activated icon| |//''DoorSensorClosed''// |overrides to show a door sensor closed icon| |//''DoorSensorOpened''// |overrides to show a door sensor opened icon| |//''WindowSensorClosed''// |overrides to show a window sensor closed icon| |//''WindowSensorOpened''// |overrides to show a window sensor opened icon| |//''TemperatureSensor''// |overrides to show a temperature sensor icon| |//''TemperatureSensorOn''// |overrides to show a temperature sensor on icon| |//''HumiditySensor''// |overrides to show a humidity sensor icon| |//''HumidifierOn''// |overrides to show a humidity sensor on icon| |//''DehumidifierOn''// |overrides to show a dehumidifier icon| |//''WindSpeedSensor''// |overrides to show a wind speed sensor icon| |//''WindSpeedSensorLow''// |overrides to show a wind speed sensor (low) icon| |//''WindSpeedSensorMedium''// |overrides to show a wind speed sensor (medium) icon| |//''WindSpeedSensorHigh''// |overrides to show a wind speed sensor (high) icon| |//''WindDirectionSensor''// |overrides to show a wind direction sensor icon| |//''WindDirectionSensorNorth''// |overrides to show a wind direction sensor (N) icon| |//''WindDirectionSensorNorthEast''// |overrides to show a wind direction sensor (NE) icon| |//''WindDirectionSensorEast''// |overrides to show a wind direction sensor (E) icon| |//''WindDirectionSensorSouthEast''// |overrides to show a wind direction sensor (SE) icon| |//''WindDirectionSensorSouth''// |overrides to show a wind direction sensor (S) icon| |//''WindDirectionSensorSouthWest''// |overrides to show a wind direction sensor (SW) icon| |//''WindDirectionSensorWest''// |overrides to show a wind direction sensor (W) icon| |//''WindDirectionSensorNorthWest''// |overrides to show a wind direction sensor (NW) icon| |//''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| |//''BatteryLevelLow''// |overrides to show a battery level (low) 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| |//''TimerOff''// |overrides to show a timer off icon| |//''TimerOn''// |overrides to show a timer on icon| |//''AvStopped''// |overrides to show a A/V stopped icon| |//''AvPaused''// |overrides to show a A/V paused icon| |//''AvPlaying''// |overrides to show a A/V playing 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 ^ API Version ^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. | |//''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. | |//''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 [[#state_image_sel_enumeration|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. | ==== 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 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 //''''// 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. ==== About Custom Device States ==== 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: Player Status Changed Player Status is Current Player Status Player Status is Separator String Current Playlist Name Current Playlist Name String Current Album Current Album String Current Artist Current Artist String Current Track Current Track Integer Current Volume Current Volume Boolean Shuffling Shuffling playStatus You'll recall from the [[plugin_guide#custom_device_type|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 //''''// 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 //''''// 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 | //''[[#all_device_selector_enumeration|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 (API v1.11+ only) === 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 (FIXME you can't currently add INSTEON devices because they need to perform some action to actually make the device function). You 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 FIXME link here| |//''name''//| Yes | string |the name of the device| |''//pluginId//''| No | string |the plugin ID - defaults to your plugin's id if in a [[#indigo_server_plugins|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 | ''//[[#protocol_enumeration|kProtocol]]//'' |the protocol for the device (//''indigo.kProtocol.Plugin''// or //''indigo.kProtocol.X10''//)| |''//folder//''| No | integer |id or instance of the folder in which to put the newly created device| === 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) === 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) === 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| ==== Examples ==== Here’s a side by site comparison of using various device properties in Python and AppleScript: ^ Python ^ AppleScript ^ |# 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")|-- Creating a device set myDevice to make new device with properties {type:x10,¬ name:"Office Lamp",¬ description:"X10 Lamp module",¬ address:"F7",¬ model:"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 an X10 device if type of mydevice is "x10" then log "device is an X10 device" end if| |# Logging a message if it’s showing in Indigo Touch if (myDevice.remoteDisplay): indigo.server.log("device is showing in Indigo Touch") |-- Logging a message if it’s showing in Indigo Touch if display in remote ui of myDevice then log "device is showing in Indigo Touch" end if| |# Setting the folder ID that the device is in indigo.device.setFolder(myDevice, 987)|-- Folder ID is not available in AppleScript | |# 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 -- Turning off all devices in X10 house code A all lights off "A" -- Turning off all INSTEON devices is not available in -- AppleScript| ===== DimmerDevice ===== 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. ==== Class Properties ==== ^ 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']''// | ==== Device States ==== 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''//. | ==== Commands (indigo.dimmer.*) ==== === 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 |''//[[#all_device_selector_enumeration|kAllDeviceSel]]//''|enumerated value to indicate which devices to turn off, all if no parameter is passed - see the [[#all_device_selector_enumeration|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 | ''//[[#all_device_selector_enumeration|kAllDeviceSel]]//'' |enumerated value to indicate which lights to turn on, all if no parameter is passed - see the [[#all_device_selector_enumeration|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 On State === Use the Turn On, Turn Off, and Toggle methods to turn on/off a dimmer device. ==== Examples ==== Here’s a side by site comparison of dimmer properties in Python and AppleScript: ^ Python ^ AppleScript^ |# Getting a device myDevice = indigo.devices[123]|-- Getting a device set myDevice to device "Office Lamp"| |# 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)|-- Set a device’s brightness to 75 if it’s currently -- less than that, but only if it’s turned on if ((brightness of device "Office Lamp" < 75) and ¬ (on state of device "Office Lamp")) then set brightness of device "Office Lamp" to 75 end if| |# Brighten a light by 25% after 10 minutes indigo.dimmer.brighten(123, by=25, delay=600) |-- Brighten a light by 25% after 10 minutes brighten "Office Lamp" by 25 in 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")|-- Logging a message if it’s showing in Indigo Touch if display in remote ui of device "Office Lamp" then log "device is showing in Indigo Touch" end if| |# Getting the folder ID that the device is in myDevice = indigo.devices[123] myDevice.folderId # OR indigo.devices[123].folderId # see comments below|-- Folder ID is not available in AppleScript| You might look at the second Python 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. ===== InputOutputDevice ===== 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. ==== Class Properties ==== 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 | ==== Device States ==== 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''//. | ==== Commands (indigo.iodevice.*) ==== === 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| ==== Examples ==== ^ Python ^ AppleScript ^ |# 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)|-- If binary input 3 is false, set binary output 1 -- to false set theBinaryInputs to binary inputs ¬ of device "EZIO8SA" if not item 3 of theBinaryInputs then set theBinaryOutputs to binary outputs ¬ of device "EZIO8SA" set item 1 of theBinaryOutputs to false set binary outputs of device ¬ "EZIO8SA" to theBinaryOutputs end if| ===== SensorDevice ===== 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 ==== Class Properties ==== ^ Property ^ Type ^ Writable ^ Description ^ |//''allowOnStateChange''//| boolean | No |API v1.6+ only: True if UI controls should be shown or enabled to change the onState| |//''allowSensorValueChange''//| boolean | No |API v1.6+ only: True if UI controls should be shown or enabled to change the sensorValue| |//''onState''//| boolean | No |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 |API v1.6+ only: the numerical value of a sensor, such as temperature (None if sensor doesn't support sensor values)| ==== Commands (indigo.sensor.*) ==== === 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| ==== Examples ==== -- none -- ===== RelayDevice ===== 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. ==== Class Properties ==== ^ 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']''// | ==== Device States ==== 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 | ==== Commands (indigo.relay.*) ==== Use the [[#turn_on|Turn On]], [[#turn_off|Turn Off]], and [[#toggle|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)| ==== Examples ==== ^ Python ^ AppleScript ^ |# Toggle the device indigo.device.toggle(123)|-- Toggle the device toggle device “Office Lamp”| ===== SpeedControlDevice ===== 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. ==== Class Properties ==== ^ 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//''| boolean | No |indicates the level the device is set to (0-100) - shortcut to //''dev.states['speedLevel']''// | ==== Device States ==== 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''// | boolean | n/a |a more user friendly name for the current index (e.g. high, medium, low, off) | | //''speedLevel''// | boolean | //''speedLevel''// |indicates the level the device is set to (0-100) - use //''dev.speedLevel''// property as a shortcut | ==== Commands (indigo.speedcontrol.*) ==== === 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. | ===== SprinklerDevice ===== Sprinkler devices generally have some number of sprinkler zones. ==== Class Properties ==== ^ Property ^ Type ^ Writable ^ [[:api_version_chart|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). As of API v1.12 (Indigo 6.0.3) the property is final and stable. | |//''zoneCount''//| integer | No | 1.0 |the number of zones available for this sprinkler| |//''zoneEnableList''//| list of string | No | 1.13 |API v1.13+ only: 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 reals | 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 reals | 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 |API v1.16+ only: the 1-based index of the paused sprinkler zone index (None=schedule not paused, 1=zone 1 paused, 2=zone 2 paused, ...).| |//''pausedScheduleRemainingZoneDuration''//| real | No | 1.16 |API v1.16+ only: the paused sprinkler zone duration in minutes (None if schedule not paused)| ==== Device States ==== 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) | |//''zone#''// | boolean | N/A |replace the # with the zone number (up to //''dev.zoneCount''//) to return whether the zone is running or not | ==== Commands (indigo.sprinkler.*) ==== === 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| ==== Examples ==== ^ Python ^ AppleScript ^ | # run schedule indigo.sprinkler.run(123, schedule=[10,15,8, 0, 0, 0, 0, 0]) |-- AppleScript doesn't support directly running a schedule, so -- we have to create an action group with the right schedule -- then execute that. -- run schedule set actionGroupName to "My Sprinkler Schedule" if not (exists action group actionGroupName) then make new action group with properties {name:actionGroupName} make new action step of action group actionGroupName ¬ with properties ¬ {action type:controlSprinkler, device name:"Sprinklers"} end if set zone durations of ¬ (action step 1 of action group actionGroupName) ¬ to [10, 15, 8, 0, 0, 0, 0, 0] execute group actionGroupName| ===== ThermostatDevice ===== 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, they generally 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. ==== Class Properties ==== ^ Property ^ Type ^ Writable ^ [[:api_version_chart|Min API]] ^ Description ^ |//''coolIsOn''//| boolean | No | 1.0 |is the cooling system (compressor) currently running - shortcut for //''dev.states['hvacCoolerIsOn']''// | |//''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''//| ''//[[#fan_mode_enumeration|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']''//| |//''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''//| ''//[[#hvac_mode_enumeration|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| == Fan Mode Enumeration == ^ ''//indigo.kFanMode//'' ^^ ^ Value ^ Description ^ |//''AlwaysOn''//|signal the fan that it should be running continuously| |//''Auto''//|signal the fan that it should only run when the HVAC system needs it to be running| == HVAC Mode Enumeration == ^ ''//indigo.kHvacMode//'' ^^ ^ Value ^ Description ^ |//''Cool''//|the hvac system is only reacting to cool setpoints| |//''HeatCool''//|the hvac system is reacting to both cool and heat setpoints| |//''Heat''//|the hvac system is only reacting to and heat setpoints| |//''Off''//|the hvac system is turned off| |//''ProgramHeatCool''//|the hvac system is executing it’s built-in automatic program, which usually responds to both heat and cool setpoints| |//''ProgramCool''//|the hvac system is executing it’s built-in cooling program| |//''ProgramHeat''//|the hvac system is executing it’s built-in heating program| ==== Device States ==== 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''// | ''//[[#fan_mode_enumeration|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''// | ''//[[#hvac_mode_enumeration|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 | ==== Commands (indigo.thermostat.*) ==== === Decrease Cool Setpoint === Decrease the cool setpoint by a delta value. ^ Command Syntax Examples ^ |indigo.thermostat.decreaseCoolSetpoint(123, delta=5)| ^ Parameters ^^^^ ^ Parameter ^ Required ^ Type ^ Description ^ |direct parameter| Yes | integer |id or instance of the device| |value| Yes | integer |number of degrees to decrease the cool setpoint| === Decrease Heat Setpoint === Decrease the heat setpoint by a delta value. ^ Command Syntax Examples ^ |indigo.thermostat.decreaseHeatSetpoint(123, delta=5)| ^ Parameters ^^^^ ^ Parameter ^ Required ^ Type ^ Description ^ |direct parameter| Yes | integer |id or instance of the device| |''//value//''| Yes | integer |number of degrees to decrease the heat setpoint| === Increase Cool Setpoint === Increase the cool setpoint by a delta value. ^ Command Syntax Examples ^ |indigo.thermostat.increaseCoolSetpoint(123, delta=5)| ^ Parameters ^^^^ ^ Parameter ^ Required ^ Type ^ Description ^ |direct parameter| Yes | integer |id or instance of the device| |''//value//''| Yes | integer |number of degrees to increase the cool setpoint| === Increase Heat Setpoint === Increase the heat setpoint by a delta value. ^ Command Syntax Examples ^ |indigo.thermostat.increaseHeatSetpoint(123, delta=5)| ^ Parameters ^^^^ ^ Parameter ^ Required ^ Type ^ Description ^ |direct parameter| Yes | integer |id or instance of the device| |''//value//''| Yes | integer |number of degrees to increase the heat setpoint| === 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 | ''//[[#fan_mode_enumeration|kFanMode]]//'' |the absolute temperature of the setpoint| === 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 | ''//[[#hvac_mode_enumeration|kHvacMode]]//'' |HVAC mode identifier| ==== Examples ==== ^ Python ^ AppleScript ^ |# 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)|-- increase the cool setpoint by 5 degrees set cool setpoint of device "Thermostat" to ¬ (cool setpoint of device "Thermostat") + 5 -- set the thermostat mode to auto set hvac mode of device "Thermostat" to heatCoolOn -- set the heat setpoint to 78 set heat setpoint of device "Thermostat" to 78|