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:

or as an entry from a fixed set of keywords.

At a minimum, three properties must be present in all devices:

In addition, there are a few optional properties that might be supported by any device:

Measurement Properties

Certain properties are termed measurement properties in that model a physical characteristic that:

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:

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:

In addition, depending on the capabilities of the device, additional properties may be present:

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:

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:

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:

At a minimum, two tasks must be available:

Any of these properties may be present, which are set with the on task:

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:

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:

At a minimum, these tasks must be available:

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:

At a minimum, one task must be present:

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:

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:

For devices that control power, at a minimum, two tasks must be available:

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