Helper Methods¶

applicationWithBundleIdentifier()¶

What's returned is a scripting bridge SBApplication instance. See the Scripting Bridge documentation for more information.

Method

Method Name
`applicationWithBundleIdentifier(self, bundleID)`

Return Value:

Type	Description
SBApplication	A Scripting Bridge application instance.

Parameters

Parameter	Description
`bundleID`	the bundle identifier for the app (usually a fully qualified string like `com.apple.iTunes`)

Exceptions Raised

Type	Description

Command Syntax Examples

app = self.applicationWithBundleIdentifier("com.apple.iTunes")
if app:
    app.playpause()

browserOpen()¶

This method will open the specified URL in the default browser. Note it does so on the server machine and not on any remotely connected clients.

Method

Method Name
`browserOpen(self, url)`

Return Value:

Type	Description
None	This method does not return a value.

Parameters

Parameter	Description
`url`	the URL to open in the browser

Exceptions Raised

Type	Description

Command Syntax Examples

self.browserOpen("https://www.indigodomo.com")

debugLog()¶

Deprecated

(See Logging below) If, at any point in your plugin, you set self.debug = True, then any time debugLog is called the string will get inserted into Indigo's event log. If self.debug = False (the default) any call to debugLog does nothing.

Method

Method Name
`debugLog(self, msg)`

Return Value:

Type	Description
None	This method does not return a value.

Parameters

Parameter	Description
`msg`	the string to insert into the event log

Exceptions Raised

Type	Description

Command Syntax Examples

self.debugLog("This is a debug message")  # deprecated; use self.logger.debug() instead

errorLog()¶

Deprecated

See Logging below If you want an error to show up in the event log (in red text), use this log method rather than indigo.server.log().

Method

Method Name
`errorLog(self, msg)`

Return Value:

Type	Description
None	This method does not return a value.

Parameters

Parameter	Description
`msg`	the string to insert into the event log

Exceptions Raised

Type	Description

Command Syntax Examples

self.errorLog("An error occurred")  # deprecated; use self.logger.error() instead

openSerial()¶

This method is identical to creating a new pySerial Serial object except that it never throws an exception. If the serial connection cannot be opened then None is returned and an error will be automatically logged to the Indigo Server event log.

Method

Method Name
`openSerial(self, ownerName, portUrl, baudrate, bytesize, parity, stopbits, timeout, xonxoff, rtscts, writeTimeout, dsrdtr, interCharTimeout)`

Return Value:

Type	Description
serial.Serial	The opened serial port object, or None if the connection failed.

Parameters

Parameter	Description
`ownerName`	the name of the device or plugin that owns this serial port (used for error logging); must be ASCII text with no Unicode characters
`all other args`	passed directly to pySerial's Serial constructor

Exceptions Raised

Type	Description

Command Syntax Examples

self.serial_port = self.openSerial(
    dev.name, dev.pluginProps["portUrl"],
    baudrate=9600, bytesize=8, parity="N",
    stopbits=1, timeout=1.0, xonxoff=False,
    rtscts=False, writeTimeout=1.0, dsrdtr=False,
    interCharTimeout=None
)
if self.serial_port is None:
    self.logger.error(f"Unable to open serial port for \"{dev.name}\"")

sleep()¶

This method should be called from within your plugin's runConcurrentThread() defined method, if it is defined. It will automatically raise the StopThread exception when the Indigo Server is trying to shut down or restart the plugin. See runConcurrentThread documentation above for more details.

Method

Method Name
`sleep(self, seconds)`

Return Value:

Type	Description
None	This method does not return a value.

Parameters

Parameter	Description
`seconds`	the sleep duration as a real number

Exceptions Raised

Type	Description

Command Syntax Examples

self.sleep(60)  # sleep for 60 seconds; raises StopThread on plugin shutdown

substituteVariable()¶

This method will allow any string with the following markup to have a variable value substituted: %%v:VARID%% where VARID is the unique variable ID as found in the UI. It's recommended that you call this method twice: first during validation to check syntax and confirm the variable exists, and again at action execution time to perform the substitution. Errors will show up in the event log if the variable doesn't exist (or if there's a formatting problem) at action execution time.

Method

Method Name
`substituteVariable(self, inString, validateOnly=False)`

Return Value:

Type	Description
str	The substituted string (when `validateOnly` is False).
(bool, str)	A `(isValid, errorString)` tuple (when `validateOnly` is True).

Parameters

Parameter	Description
`inString`	the string which contains a valid variable ID
`validateOnly`	if False (default), returns the substituted string; if True, returns a `(bool, errStr)` tuple indicating whether the syntax is valid and the variable exists

Exceptions Raised

Type	Description

Command Syntax Examples

# Validate during UI validation, then substitute at execution time
is_valid, err_msg = self.substituteVariable(action.props["varString"], validateOnly=True)
if is_valid:
    result = self.substituteVariable(action.props["varString"])

substituteDeviceState()¶

This method will allow any string with the following markup to have a device state value substituted: %%d:DEVICEID:STATEKEY%% where DEVICEID is the unique device ID and STATEKEY is the identifier for the state. It's recommended that you call this method twice: first during validation, and again at action execution time. Errors will show up in the event log if the device doesn't exist (or if there's a formatting problem) at action execution time.

Method

Method Name
`substituteDeviceState(self, inString, validateOnly=False)`

Return Value:

Type	Description
str	The substituted string (when `validateOnly` is False).
(bool, str)	A `(isValid, errorString)` tuple (when `validateOnly` is True).

Parameters

Parameter	Description
`inString`	the string which contains a valid device ID and state key
`validateOnly`	if False (default), returns the substituted string; if True, returns a `(bool, errStr)` tuple indicating whether the syntax is valid and the device exists

Exceptions Raised

Type	Description

Command Syntax Examples

# Validate during UI validation, then substitute at execution time
is_valid, err_msg = self.substituteDeviceState(action.props["devString"], validateOnly=True)
if is_valid:
    result = self.substituteDeviceState(action.props["devString"])

substitute()¶

Validation works the same and should be called when your dialog validates user input. This method calls substituteVariable() first followed by substituteDeviceState(). The ordering was carefully chosen such that the variable substitution could, in fact, add more device markup to the string before the device substitution happens. So the user can even more dynamically generate content by inserting device markup into a variable value. However, only device markup will be honored in variable values - we don't recursively call variable markup on variable values.

Method

Method Name
`substitute(self, inString, validateOnly=False)`

Return Value:

Type	Description
str	The substituted string (when `validateOnly` is False).
(bool, str)	A `(isValid, errorString)` tuple (when `validateOnly` is True).

Parameters

Parameter	Description
`inString` and `validateOnly` as described in `substituteVariable()` and `substituteDeviceState()`

Exceptions Raised

Type	Description

Command Syntax Examples

# Validate during UI validation, then substitute at execution time
is_valid, err_msg = self.substitute(action.props["inputString"], validateOnly=True)
if is_valid:
    result = self.substitute(action.props["inputString"])