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 NameTypeDescriptionExample Device
colorread-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
ecwread-only numberThe current energy consumption in wattsEnergy Reporting Outlet
firmwareVersionread-only stringThe firmware version of a deviceEnergy Reporting Outlet
imageStatusUrlread-only stringAn URL or JSON URL (see below) to an image providing device status informationCamera
levelread-write numberIdentifies a multi-level device's current state (0-100 percentage). For a light bulb, this would be brightness.Light dimmer
onread-write booleanIdentifies a switchable device's current stateLight switch
tstatModeread-write stringOFF | AUTO | COOL | HEATThermostat
tstatFanModeread-write stringAUTO | ONThermostat
targetTempCread-write numberThe target temperature in CelsiusThermostat
targetTempFread-write numberThe target temperature in FahrenheitThermostat
tempCread-only numberThe current temperature in CelsiusWeather station
tempFread-only numberThe current temperature in FahrenheitThermostat, Weather station
videoStatusUrlread-only stringA URL or JSON URL (see below) to a video feed providing device status informationCamera

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.


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:

urlThe URL including query parameters
headersA JSON Object containing any request header key/value pairs

A JSON Object containing:

typeThe authentication type (currently only "basic" is supported)
usernameThe username credential
passwordThe password credential


Here's an example:

"url": "",
"headers": {
"Accept": "text/xml"
"auth": {
"username": "username",
"password": "password",
"type": "basic"