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.)