devices

Device Type

The plugin presently supports two types of data devices--String Type and Real Type. As you might expect, selecting the String Type device will save all device states as strings. The Real Type will try to coerce device states into booleans, floats, strings, etc. Choose the proper feed type using the dropdown list when defining the device.

Note that the plugin supports changing back and forth between device types. In other words, a device initially established as a String Type can be changed to a Real Type without recreating the device.

Feed Type

The plugin presently supports two types of data sources--JSON and XML. Choose the proper feed type using the dropdown list.

Refresh Frequency

The refresh frequency controls how often you would like to have the data updated. It is recommended that you set this value to the longest useful time. Some data sources may only need to be updated once per day.

Timeout

The timeout frequency controls how long the plugin will wait for your data source to respond. If the data source hasn't responded within the set time, the process call will be killed. The device will try again at regular intervals. You will receive a log message if the plugin has found a need to kill a process call.

Max Retries

The Max Retries feature controls how many times the plugin will attempt to connect to the data service before automatically disabling itself. If the limit is exceeded, the plugin will disable the device and (if configured) fire a trigger that can be used to notify the user that the device has been disabled.

Disable SQL Logging

This feature will keep Indigo from logging the state changes of the subject device. New devices have this feature turned on by default. Unchecking this box will result in all state changes being picked up in SQL logging.

URL/Path

This is the full URL to the JSON or XML data source. It can be an online resource or a local file. The path should be constructed like this:

Online Resource
http://www.website.com/filename.json
http://www.website.com/filename.xml

Local File
file:///Users/username/filename.json
file:///Users/username/filename.xml

These links can't contain spaces, so you'll need to format the resource locator like this:
http://www.website.com/filename%20with%20spaces.json
file:///Users/username/filename%20with%20spaces.xml

Note that it's best if you're linking to a static resource. This is especially important if you're linking to a local IP address. Targets with dynamic IP addresses are discouraged since the IP of the target source could change at any time. If linking to If the location of the target changes, the plugin will report an IOError to the log and register an error state for the device (with a corresponding red icon).

Authentication

The plugin supports resources that require different types of authentication--such as when a site requires a username and password--as long as the resource supports basic, digest, or token authentication. If authentication is required for your resource, select the appropriate method and enter the required credentials. It is up to you to determine whether basic, digest or token authentication is appropriate for your resource.

Note

Older versions of the plugin also required users to tick a 'Use Authentication' box. This is no longer required.

Basic

Basic authentication uses a simple username/password scheme. Use this type of authentication only when basic authentication is required by the target server.

Caution

Use caution with basic authentication as your username and password are sent (by definition) as clear text. Anyone that can intercept the call will be able to see your username and password.

Basic authentication should generally only be used when another layer of security is available (like using https:// or for traffic limited to your local LAN.)

Bearer

Bearer authentication uses a token to confirm authority. Use this type of authentication only when bearer authentication is required by the target server.

Caution

Use caution with bearer authentication as your token is sent as clear text. Anyone that can intercept the call will be able to see your token.

Digest

Digest authentication uses a higher level of security than basic authentication. With digest authentication, your username and password are encrypted before transmission, making it more difficult for someone to be able to intercept your credentials.

Token

Token authentication: Supports a limited token authentication scheme in which:

1. the token is requested in an HTML POST request is sent to the URL provided in Link URL in the form "pwd": "{{<PASSWORD>}}}" and
2. The token can be added at the end of each request in the form: ?access_token=<TOKEN>

This has been demonstrated to work with the RainMachine irrigation controller. Other services might also work. Should you find yourself unable to make it work, post questions to the Indigo forum.

Raw Curl

It is recommended that only advanced users use raw curl commands, which require a very specific (and picky) formatting of commands. To use a raw curl command, enter the base url information in the URL/Path field. Then add individual curl commands within the Curl Commands field. Each command should be entered on its own line (or as one continuous string with no quotes), and the commands should not contain any stray spaces or returns within the Curl Commands field. To advance to a new line within the Curl Commands field, hold down the OPTION key while hitting enter. Note that each line (with the notable exception of the last line) is followed by a space and a backslash (without quotes): " \" to escape the linebreak.

The following is an example a curl command string (this formatting is for a particular API and is known to work):

-H "Authorization: Bearer [API KEY VALUE]" \
-H "Content-Type: application/json" \
-X POST \
-d '{ "query": "{viewer {homes {consumption(resolution: HOURLY, last: 1) {nodes {from to totalCost unitCost unitPrice unitPriceVAT consumption consumptionUnit }} meteringPointData {estimatedAnnualConsumption } currentSubscription {priceInfo {current {total energy tax startsAt }}}}}}" }'

Given the advanced nature of raw curl commands, the source-specific natures of the commands required, and the complexities of proper formatting, it is not possible to guarantee support in order to make this feature work for your application. Should you find yourself unable to make it work, post questions to the Indigo forums.

Enable Substitutions

The plugin supports variable substitutions for customizing the resource feed even more.

First, create the Indigo variable that will contain the custom setting. Second, within the GhostXML device configuration dialog box, tick the "Enable Substitutions" box (if it's not already ticked). Enter the variable ID into the appropriate box and add the substitution to the URL by including it in brackets like so [A] and [B] (see the image below).