Device Variable Conventions

Every device exposes its state and control points through the use of variables.

There are three different types of variables:

Read-write - variables that provide both state and control of some device facet
Read-only - variables that provide only state about some device facet
Write-only - variables that facilitate only control of some device facet

Variable Naming

What variables a device exposes define the device's capabilities and ultimately how clients will perceive and interact with that device. Therefore, it is important that variable naming remain consistent for functions that are common across different devices.

The below list defines commonly used variable names:

Variable Name	Type	Description	Example Device
color	read-write string	The color in one of two possible formats: HSB (hue/saturation/brightness):`hub(0-360,0-100,0-100)` KB (kelvin/brightness): `kb(2500-9000,0-100)` It is recommended to stick with HSB format for setting colors and KB format for setting variations of white. Some typical Kelvin values are 2700 (incandescent), 3000 (warm white), 3500 (neutral), 4100 (cool white), 5000 (daylight), 6500 (bright daylight).	Color bulb
ecw	read-only number	The current energy consumption in watts	Energy Reporting Outlet
firmwareVersion	read-only string	The firmware version of a device	Energy Reporting Outlet
imageStatusUrl	read-only string	An URL or JSON URL (see below) to an image providing device status information	Camera
level	read-write number	Identifies a multi-level device's current state (0-100 percentage). For a light bulb, this would be brightness.	Light dimmer
on	read-write boolean	Identifies a switchable device's current state	Light switch
tstatMode	read-write string	OFF \| AUTO \| COOL \| HEAT	Thermostat
tstatFanMode	read-write string	AUTO \| ON	Thermostat
targetTempC	read-write number	The target temperature in Celsius	Thermostat
targetTempF	read-write number	The target temperature in Fahrenheit	Thermostat
tempC	read-only number	The current temperature in Celsius	Weather station
tempF	read-only number	The current temperature in Fahrenheit	Thermostat, Weather station
videoStatusUrl	read-only string	A URL or JSON URL (see below) to a video feed providing device status information	Camera

Image & Video Status URLs

There are two variables the Hobson runtime treats differently than the others – imageStatusUrl and videoStatusUrl. As indicated in the table above, the value a device provides for these variables is a URL or JSON URL (which we'll refer to as the source URL) which can include user credentials. However, those variable values are not returned directly via the REST API. Instead, the value returned by the REST API is a generic proxy URL that provides the image or video stream data from the source URL. It is therefore safe for devices to include user credentials in the value they provide for imageStatusUrl and videoStatusUrl because they will not be exposed.

JSON URL

As of Hobson 0.3.1 and higher, some variables support a value referred to as a JSON URL. This is a JSON object that contains an URL string and associated metadata. The JSON URL object should have the following pairs:

Name

Value

url

The URL including query parameters

headers

A JSON Object containing any request header key/value pairs

auth

A JSON Object containing:

Name	Value
type	The authentication type (currently only "basic" is supported)
username	The username credential
password	The password credential

Here's an example:

{
"url": "http://www.foo.com",
"headers": {
"Accept": "text/xml"
},
"auth": {
"username": "username",
"password": "password",
"type": "basic"
}
}