Schema - SENSOR.BASIC UPDATE - XPLProject

Contents

sensor.basic Message Specification

  • Class = sensor
  • Type = basic

This schema provides encapsulation of basic telemetry. This is the companion to control.basic, which can be used to set the value of these devices. In short, any input device, such as a switch, a temperature sensor, a light level sensor, should use the sensor.basic schema.

The schema assumes most xpl-devices to support multiple sensors, and as such every message must contain a 'device=<sensor id>' key. When reading this document for sensor.basic it is important to realize that the 'device' referenced in this case is NOT the xpl-device, but one of possibly many sensors that the xpl-device supports.

XPL-CMND Structure

sensor.request
{
request=current|<item>
device=<sensor id>
}

sensor.request allows you to query a device for information. 'device=...' is used to select which sensor the device is requested to report the status/value of. When a device receives this message, it should immediatley send an xpl-stat message with schema sensor.basic containing the requested (current or <item>) value in it (formatted as described in the section on xpl-stat).

For the 'request=...' key, every device that allows sensor.request command messages must at least implement 'request=current'. In addition to this current value request, devices may choose to allow additional information requests (for example, name of a sensor, location, min/max values, etc). Such additional request options would be described in the devices documentation and would take the form of "request=<item>" (i.e. 'request=name' or 'request=location'). The item name passed to the 'request=...' line should appear in the xpl-stat response message with a value. For example, if you send a request with 'request=name', the resultant xpl-stat message should have 'device=<sensor id>' and 'name=<sensor name>'. Note that each command message may only contain a single 'request=...' key, otherwise in a response the units reported would be ambiguous as to which reported value they would pertain.

'device=...' is required in every instance, even if a device only supports a single sensor (for compatibility reasons one might expect messages without the 'device=...' key, and devices should be capable of dealing with them). If a request for a value is received and there is no 'device=...' element, the receiver should ignore/drop the response (it should NOT try to "figure out" what the sender really wanted -- too open to interpretation -- explicity is where it's at).

Support for accepting sensor.request command messages is optional and some smaller devices cannot do it. But all device authors should make every effort they can to add support for the 'request=current' type.

XPL-TRIG Structure

sensor.basic
{
device=<sensor id>
current=<current value>
type=<sensor type>
units=<current units (inches, hours, volts, etc)>
}

trigger messages are sent anytime the value of a sensor changes - e.g. due to a switch being pressed, or a change in temperature or light level. They are meant to be asynchronous notifications of change and as such, they should be sent as soon as possible after the devices value actually changes.

Do not send trigger messages in response to any received command (unless that command alters a value and is causing the trigger indirectly) or if there is no actual change in the value for a device (i.e. do not send them out periodically even if there value is the same as the last time). Because of the nature of a trigger message the reported value is always 'current', and can never be any of the other 'request=...' items as specified for command messages.

For analog inputs, the amount of change required to generate a trigger message is device-specific, and may be configurable by the end-user.

'units=...' is optional, but developers are urged to make an effort in getting this key supported. Only if it makes no sense to report it it should be left out (also due to backward compatibility one should be prepared to receive messages without this key). Examples could be an input button reporting values 'ON', 'OFF' or 'PULSE', which has no sensible unit to specify. For supported values for 'units=...' see the list below.

'type=...' is optional, and denotes a generic type of sensor. For supported types see the list below.

XPL-STAT Structure

sensor.basic
{
device=<sensor id>
current=<current value>
type=<sensor type>
units=<current units (inches, hours, volts, etc)>
[other device specific values, per the request= in sensor.request]
}

Status messages are used to convey the state of values in a device and are generally sent in response to the device receiving a sensor.request command. Each sensor.request command message will indicate what it is requesting. In most cases, it will contain 'request=current', meanining it wants the current value for the device returned.

If some other attribute of the device, such as name ('request=name' specified the command message), was asked for, then the response status message would contain that item and value. For example, if the sensor.request command had 'request=name', then the xpl-stat message returned would have 'name=<name value>' instead of the 'current=<current value>' in its body. If a sensor.request command is requesting information the device doesn't understand, the sensor.request command should be dropped and ignored (i.e. don't send anything out). For example, if a temperature sensor received a sensor.request command with 'request=air-pressure', it should just discard the request as it doesn't know what "air-pressure" is.

The 'units=...' and 'type=...' should be used similar to the XPL-TRIG message.

Known device types

To inform the user properly the units must be reported using a strict set of rules, such that an user interface is capable of transforming the units to the user preferred settings. For example distance in centimeters or inches, temperature in Celsius, Kelvin or Fahrenheit. If a unit reported is not a standard unit that can be transformed, then consider using a unit that can be displayed by a user interface without confusing a user.

The following is a list with sensor types and their preferred usage and units of measure. Note that the units are case-sensitive!

  • current - a current value in Amps ('units=uA|mA|A')
  • distance - distance measurments ('units=mm|cm|m|km|in|ft|mi' with "mm" (millimeters), "cm" (centimeters), "m" (meters), "km" (kilometers), "in" (inches), "ft" (feet), "mi" (miles))
  • energy - consumption of energy over a period of time (units=Wh|kWh')
  • humidity - a relative humidity percentage ('units=%')
  • power - instantaneous energy consumption level ('units=W|kW')
  • pressure - a pressure value in Pascals ('units=kN/m2|N/m2')
  • speed - a generic speed ('units=<cm|m|km|in|ft|mi>/<s|m|h>', see 'distance' combined with s/m/h for second/minute/hour)
  • rotation - a rotating (eg. fan) speed ('units=rpm')
  • temp - a temperature value in degrees ('units=c|k|f', for Celsius, Kelvin or Fahrenheit)
  • voltage - a voltage value ('units=uV|mV|V')
  • volume - a volume ('units=<mm|cm|m>3')
  • weight - a weight ('units=g|kg|oz|lb' for; "g" (grams), "kg" (kilograms), "oz" (ounces) or "lb" (pounds).

Some more generic types;

  • percentage - a battery level in percent ('units=%')
  • count - a counter value (door openings, rain fall, etc.), ('units=count')
  • direction - direction, represented as degrees from north (0-360, 0=north, 180=south, etc) ('units=degrees', a userinterface can substitute this for the degree symbol)
  • input - a switch that can either be current=HIGH (on), current=LOW (off) or current=PULSE (representing a button press), no units
  • output - a change in an output state with values of LOW and HIGH, no units
  • uv - UV Index (with no units). See http://en.wikipedia.org/wiki/UV_index
  • range - a generic value in a range. Use a descriptive unit label; 'units=([min]-[max])'. For example a volume setting; 'units=(0-30)' which still makes a descriptive display in a user interface

Standard Schema Notes

Like all xPL devices, a device implementing the sensor schema must send periodic heartbeat messages (hbeat.app or hbeat.basic). Those messages should not contain any values for sensors -- just the basic heartbeat information described elsewhere in the xPL spec.

This page was last modified on 28 November 2011, at 23:04. This page has been accessed 2,598 times.