Device Specific Methods¶
deviceCreated()¶
This method will get called whenever a new device defined by your plugin is created. In many circumstances you won't need to implement this method since the default behavior — which is to call the deviceStartComm() method if the device belongs to your plugin and is enabled — is what you want anyway (see deviceStartComm() above for details). However, if you need to know when a device is created but before your plugin is asked to start communicating with it, this method provides that hook. If you implement this method you'll need to call deviceStartComm() yourself or duplicate the functionality here.
You can also have this method called for devices that don't belong to your plugin. If you want to know when all devices are created (and updated/deleted), call indigo.devices.subscribeToChanges() to have the IndigoServer send all device creation/update/deletion notifications. As with other change subscriptions, this should be used very sparingly since it's a lot of overhead both for your plugin and, more importantly, for the IndigoServer.
Method
| Method Name | Required |
|---|---|
deviceCreated(self, dev) |
No |
Parameters
| Parameter | Description |
|---|---|
dev |
an indigo.Device object representing the device that was created |
Return Value:
| Type | Description |
|---|---|
| None | This method does not return a value. |
Exceptions Raised
| Type | Description |
|---|---|
Command Syntax Examples
def deviceCreated(self, dev):
# Perform any tasks necessary to make sure the new device is fully configured, and optionally, perform an initial refresh.
deviceDeleted()¶
Complementary to the deviceCreated() method described above, but signals device deletes. The default implementation just checks to see if the device belongs to your plugin and -- if so -- calls the deviceStopComm() method. If you implement this method you'll need to call deviceStopComm() yourself or duplicate the functionality here.
Method
| Method Name | Required |
|---|---|
deviceDeleted(self, dev) |
No |
Parameters
| Parameter | Description |
|---|---|
dev |
an indigo.Device object representing the device that was deleted |
Return Value:
| Type | Description |
|---|---|
| None | This method does not return a value. |
Exceptions Raised
| Type | Description |
|---|---|
Command Syntax Examples
deviceStartComm()¶
If your plugin defines devices, this is likely the place where you'll want to do the work of starting your device up. For instance, let's say that you have a device somewhere out on the network - the easiest way to "start" your device is to implement this method. You would open the network address:port (that's defined in dev.pluginProps), get it's current state(s) and tell the IndigoServer to set those states (using the dev.updateStateOnServer() method).
Method
| Method Name | Required |
|---|---|
deviceStartComm(self, dev) |
No |
Parameters
| Parameter | Description |
|---|---|
dev |
an indigo.Device object representing the device |
Return Value:
| Type | Description |
|---|---|
| None | This method does not return a value. |
Exceptions Raised
| Type | Description |
|---|---|
Command Syntax Examples
def deviceStartComm(self, dev):
# Perform any clean up tasks after communication with a plugin device is (re)established.
deviceStopComm()¶
This is the complementary method to deviceStartComm() - it gets called when the device should no longer be active/enabled. For instance, when the user disables or deletes a device, this method gets called.
Method
| Method Name | Required |
|---|---|
deviceStopComm(self, dev) |
No |
Parameters
| Parameter | Description |
|---|---|
dev |
an indigo.Device object representing the device |
Return Value:
| Type | Description |
|---|---|
| None | This method does not return a value. |
Exceptions Raised
| Type | Description |
|---|---|
Command Syntax Examples
def deviceStopComm(self, dev):
# Perform any clean up tasks after communication with a plugin device is disabled.
deviceUpdated()¶
Complementary to the deviceCreated() method described above, but signals device updates. You'll get a copy of the old device object as well as the new device object. The default implementation of this method will do a few things for you: if either the old or new device are devices defined by you, and if the device type changed OR the communication-related properties have changed (as defined by the didDeviceCommPropertyChange() method - see above for details) then deviceStopComm() and deviceStartComm() methods will be called as necessary (stop only if the device changed to a type that isn't your device, start only if the device changed to a type that belongs to you, or both if the props/type changed and they both belong to you).
Method
| Method Name | Required |
|---|---|
deviceUpdated(self, origDev, newDev) |
No |
Parameters
| Parameter | Description |
|---|---|
origDev |
an indigo.Device object representing the device before the change |
newDev |
an indigo.Device object representing the device after the change |
Return Value:
| Type | Description |
|---|---|
| None | This method does not return a value. |
Exceptions Raised
| Type | Description |
|---|---|
Command Syntax Examples
def deviceUpdated(self, origDev, newDev):
# You are responsible for isolating the te difference(s) between the old and new device objects as needed.
didDeviceCommPropertyChange()¶
This method gets called by the default implementation of deviceUpdated() to determine if any of the properties needed for device communication (or any other change requires a device to be stopped and restarted). The default implementation checks for any changes to properties. You can implement your own to provide more granular results. For instance, if your device requires 4 parameters, but only 2 of those parameters requires that you restart the device, then you can check to see if either of those changed. If they didn't then you can just return False and your device won't be restarted (via deviceStopComm()/deviceStartComm() calls).
Method
| Method Name | Required |
|---|---|
didDeviceCommPropertyChange(self, origDev, newDev) |
No |
Parameters
| Parameter | Description |
|---|---|
origDev |
an indigo.Device object representing the device before the change |
newDev |
an indigo.Device object representing the device after the change |
Return Value:
| Type | Description |
|---|---|
| bool | True if communication-relevant device properties changed; False otherwise. |
Exceptions Raised
| Type | Description |
|---|---|
Command Syntax Examples
def didDeviceCommPropertyChange(self, origDev, newDev):
# You are responsible for isolating the te difference(s) between the old and new device objects as needed.
getDeviceConfigUiValues()¶
This method will get called whenever a Device configuration is opened. Indigo will look for this method and, if it exists, will pre-populate the configuration dialog with the information created/modified in the method. This method is particularly helpful when you want a Device's configuration to be different from the default (set in the Device configuration XML file). A simple example is provided below.
Method
| Method Name | Required |
|---|---|
getDeviceConfigUiValues(self, pluginProps, typeId, devId) |
No |
Parameters
| Parameter | Description |
|---|---|
pluginProps |
a dictionary of the device's current plugin properties |
typeId |
the device type ID string as defined in Devices.xml |
devId |
the integer ID of the device being configured |
Return Value:
| Type | Description |
|---|---|
| tuple | A (valuesDict, errorMsgDict) tuple to pre-populate the config dialog. |
Exceptions Raised
| Type | Description |
|---|---|
Command Syntax Examples
def getDeviceConfigUiValues(self, pluginProps, typeId, devId):
valuesDict = pluginProps
errorMsgDict = indigo.Dict()
if not valuesDict.get("someProp"):
valuesDict["someProp"] = "default value"
return valuesDict, errorMsgDict
getDeviceDisplayStateId()¶
If your plugin defines custom devices, this method will be called by the server to determine which device state ID to display in the device list UI state column. The default implementation just returns the <UiDisplayStateId> element in your Devices.xml file. You can, however, implement the method the plugin needs to dynamically determine the which state ID to display.
Method
| Method Name | Required |
|---|---|
getDeviceDisplayStateId(self, dev) |
No |
Parameters
| Parameter | Description |
|---|---|
dev |
an indigo.Device object representing the device |
Return Value:
| Type | Description |
|---|---|
| str | The state ID to display in the device list UI state column. |
Exceptions Raised
| Type | Description |
|---|---|
Command Syntax Examples
getDeviceStateList()¶
If your plugin defines custom devices, this method will be called by the server when it tries to build the state list for your device. The default implementation just returns the <States> element (reformatted as an indigo.List() that's available to your plugin via devicesTypeDict["yourCustomTypeIdHere"]) in your Devices.xml file. You can, however, implement the method yourself to return a custom set of states. For instance, you may want to allow the user to create custom labels for the various inputs on your device rather than use generic "Input 1", "Input 2", etc., labels. Check out the EasyDAQ plugin which uses this approach.
Most plugins will not need to subclass get_device_state_list() because -- by default -- it returns the <States> list as defined in Devices.xml. So only subclass this method if you dynamically need to change the device states list provided based on specific device instance data (not just device types).
Method
| Method Name | Required |
|---|---|
getDeviceStateList(self, dev) |
No |
Parameters
| Parameter | Description |
|---|---|
dev |
an indigo.Device object representing the device |
Return Value:
| Type | Description |
|---|---|
| indigo.List | The list of device states for this device. |
Exceptions Raised
| Type | Description |
|---|---|
Command Syntax Examples