Taxonomy
The steward's taxonomy consists of a hierarchical system for device prototypes along with a flat namespace for properties. Although the naming for device prototypes is hierarchical, based on primary function, a given property may appear in any device prototype in which "it makes sense".
Properties are expressed in a consistent set of units:
- percentage - [0 .. 100]
- degrees - [0 .. 360)
- mireds - [154 .. 500] (MK^-1, reciprocal mega-kelvins)
- meters/second - [0 .. N]
- coordinates - [latitude, longitude] -or- [latitude, longitude, elevation] -or- [latitude, longitude, elevation, accuracy]
- meters - [0 .. N]
- kilometers - [0 .. N]
- milliseconds - [0 .. N]
- id - [1 .. N]
- u8 - [0 .. 255]
- s8 - [-127 .. 128]
- fraction - [0 .. 1]
- timestamp - 2013-03-28T15:52:49.680Z
- celsius
- ppm
- decibels
- millibars
- sigmas
or as an entry from a fixed set of keywords.
At a minimum, three properties must be present in all devices:
name - a string
status - a keyword:
waiting - indicates that the steward is waiting for the device to communicate
busy - indicates that the device is busy "doing something"
ready - indicates that all is well between the steward and the device
error - indicates something else
reset - indicates that the device, sadly, requires intervention
on or off - for lighting and switches
motion or quiet - for motion sensors
idle, playing, or paused - for media players
present, absent, or recent - for presence and sensors
green, blue, orange, or red - for reporting steward health
updated - a timestamp
In addition, there are a few optional properties that might be supported by any device:
location - a coordinates array
placement - a string (e.g., "front yard")
batteryLevel - a percentage
lqi - an s8 value indicating proximity (higher is closer)
nextSample - a timestamp
text - a string
Measurement Properties
Certain properties are termed measurement properties in that model a physical characteristic that:
is measured in a particular set of units (e.g., 'celsius');
that may be related to the SI system; and,
and often expressed using a symbol (e.g., 'C').
If you wish for a measurement property to be automatically archived, then examine the file
steward/devices/device-sensor.js
to see which measurement properties are currently defined in the measures object, e.g.,
var measures = { temperature: { symbol: 'C', units: 'celsius', type: 'derivedSI' }
...
};
Add to this object as appropriate. The valid values for the type field are:
baseSI - one of the seven SI base units;
derivedSI - formed by the juxtaposition of two or more base units;
derivedUnits - a unit derived not derived from the SI, but frequently used in conjunction with the SI; and,
contextDependentUnits - anything else.
Now let's look at the ten categories of devices.
Climate
These are devices that monitor or control the "breathable environment". The naming pattern is:
/device/climate/XYZ/QUALITY
depending on whether control functions are available.
At a minimum, two properties must be present:
lastSample - a timestamp
temperature - in degrees centigrade (celsius)
In addition, depending on the capabilities of the device, additional properties may be present:
humidity - a percentage
co2 - in parts-per-million
noise - in decibels
pressure - in millibars
airQuality - in sigmas
smoke - in sigmas
co - in sigmas
no2 - in sigmas
hcho - in sigmas
needs* - true or false
advise* - a string (e.g., "front yard")
Please note that the updated and lastSample properties report different things: lastSample indicates when the climate properties where last measured, whilst updated indicates the last change in state for the device (i.e., it is possible for updated to change regardless of whether lastSample changes; however, whenever lastSample changes to reflect a more recent measurement, updated will also change to the current time).
Finally, control devices may have additional properties:
away - either off or on
hvac - either off, cool, heat, or fan
fan - either on, auto, or the number of milliseconds that it should run
goalTemperature - the desired temperature
leaf - either off or on
Gateway
These are devices that interface to non-IP devices, or devices that talk to a cloud-based service to get information about a device in the home. Accordingly, there are two naming patterns, i.e.,
/device/gateway/TECHNOLOGY/MODEL
/device/gateway/TECHNOLOGY/cloud
For example:
/device/gateway/insteon/hub
/device/gateway/netatmo/cloud
The status property may be the only property present:
- status - waiting, ready, error, or reset
Note that gateways to cloud-based services require authentication information, which is typically set using either the
/manage/api/v1/device/create/uuid
or
/manage/api/v1/device/perform/id
APIs.
Indicator
These are devices that provide an indication to the user that is related to neither the "lighting environment" or the "media environment". The naming pattern is:
/dev/indicator/XYZ/MEDIA
where MEDIA is usually text.
The status property may be the only property present:
- status - waiting, ready, or error
As with gateway devices for cloud-based services, once initialized, these devices are almost entirely uninteresting to the user.
Lighting
These are devices that control the "lighting environment". The naming pattern is:
/device/lighting/XYZ/bulb
/device/lighting/XYZ/cfl
/device/lighting/XYZ/downlight
/device/lighting/XYZ/led
/device/lighting/XYZ/lightstrip
/device/lighting/XYZ/uplight
Given the range of physical properties, it is challenging to provide an abstraction which preserves the fidelity of the device-specific color model.
The status property indicates the current state of the bulb:
- status - waiting, on, or off
At a minimum, two tasks must be available:
on - turns the light on
off - turns the light off
Any of these properties may be present, which are set with the on task:
color.model - defines the model and parameters, any combination of:
color.rgb - with parameters r, g, and b, each a integer-value between 0 and 255
color.rgb16 - with parameters r, g, and b, each a integer-value between 0 and 65535
color.rgbow - with parameters r, g, b, o, and w, each a integer-value between 0 and 255
color.hue - with parameters hue (in degrees) and saturation (as a percentage)
color.temperature - with parameter temperature expressed in mireds
color.cie1931 - with parameters x and y expressed as a real-value between 0 and 1
With respect to the color model, the list above is presented starting at the least-desirable (rgb) to the most-desirable (cie1931). Clueful clients that manage the lighting environment should take note of which models are supported by a device and use the most desirable.
In addition, there are some optional properties:
brightness - an integer-value percentage of the bulb's possible output
color.fixed - true or false (if true, the color may not be changed)
pps - u16 the number of pixels in a pixel strip
Media
These are devices that control the "media environment". The naming pattern is:
/device/media/XYZ/audio
/device/media/XYZ/netcam
/device/media/XYZ/video
At a minimum, these properties must be present:
status - one of idle, playing, paused, or busy
track - defines the track information:
title, artist, and album - strings
albumArtURI - a URI
position - an integer-value indicating the number of milliseconds
volume - an integer-value percentage of the device's possible output
muted - either on or off
At a minimum, these tasks must be available:
play - plays the url parameter (or resumes playback if the url isn't present)
stop - stops playback
pause - pauses playback
seek - to the position parameter
set - set any of these parameters: position, volume, and/or muted
Motive
These are devices that have some movement capability: either rotational or mobile. The naming pattern is:
/device/motive/XYZ/2d
/device/motive/XYZ/3d
/device/motive/XYZ/ptz
/device/motive/XYZ/automobile
under review
Presence
These are devices that report presence. The naming pattern is:
/device/presence/XYZ/fob
/device/presence/XYZ/mobile
At a minimum, two properties must be present:
status
present - the device is currently detected
absent - the device is no longer detected
recent - the device was recently detected (to save device power, the steward does not continuously probe the device)
lqi - an integer-value between -127 and 128 indicating proximity (higher is closer)
At a minimum, one task must be present:
alert - causes the presence device to emit a visual and/or audio signal
- level parameter: one of none, mild, or high
Sensor
These are devices that measure one physical quality (such as motion). The naming pattern is:
/device/sensor/XYZ/QUALITY
At a minimum, one property must be present:
- lastSample - a timestamp
Switch
These are devices that control power either in binary (onoff), contiguously (dimmer), or as a group (strip). In addition, this category also includes devices that monitor power (meter). The naming pattern is:
/device/switch/XYZ/dimmer
/device/switch/XYZ/meter
/device/switch/XYZ/onoff
/device/switch/XYZ/strip
The status property may be the only property present:
- status - on, off, busy, or waiting
For devices that control power, at a minimum, two tasks must be available:
on - turns the power on
- level (dimmer only) - an integer-value percentage of the switch's possible output
off - turns the power off
Wearable
These are devices that are similar to fob devices, but meant to be more personal. The naming pattern is:
/device/wearable/XYZ/watch
Please consult the section on Presence devices for further details. (In the future, it is likely that this device prototype will have additional features.)