Sensors & Actuators (Platform)

Purpose

Provide a generic way of linking the BlueRange firmware to vendor-specific extensions supporting both the reporting of sensor values and the actioning of actuators. Following is the data format used by the firmware as well as the definitions required for interpretation.

The firmware implementation is part of the Node class as this represents a core functionality. The metadata definitions are used throughout the platform controlling the binary coding and value transport on gateways, historization on the server and details of visualizations.

Functionality

Reporting Of Sensors And Actual Values

BlueRange IoT devices may support multiple sensors, which could e.g. be part of multiple light heads. A vendor-specific firmware extension is expected to report measurements periodically to the BlueRange sensor module.

Some sensor values may be sent periodically to the BlueRange firmware, e.g. a temperature measurement could be reported every 10 minutes. Other sensor events, such as presence may need to be sent event-based. It is important to know that there is no guaranteed delivery across the system, so that a measurement may be lost in transmission. To cope with that, the following strategies exist:

  • Ideally the software at the source checks incoming measurement values for changes.

  • Typically changed values are reported immediately minimizing latency of updates.

  • Unchanged values are reported periodically to deal with lost messages.

  • To save bandwidth the transmission interval is increased over time.

  • Events like "Button was pressed" should be reported using an incrementing counter. Thereby, it can be considered as a state, e.g. button was pressed 130 times since node was started.

  • A state that needs to be reported once it changes, should be sent as soon as the change occurs but should also have an interval at which the current value is reported to account for lost messages. E.g. detecting if per person is present under a presence sensor or if the person went away.

  • A threshold must be used to not generate too many changes. Messages should not trigger too often. This can be achieved by using thresholds for the time and the value. A message should only be sent if the value changes in a meaningful way and depending on the sensor, a follow-up time should be used. E.g. a movement sensor should only send an inactive value after some time because a person standing below it will not be registered if it is not moving.

Using these techniques it is possible to calculate the number of messages sent in a system and to balance the load. Later, the system will also generate acknowledgements for event based messages. This further reduces the load in the mesh network.

Since this data may be represented in histograms or a heatmap, meaningful values should be chosen. E.g. a movement sensor should send a 0 when there is no movement and a 1 when movement is detected.

Reporting Of Sensor Measurements

A tiny bit of glue code added to the beacon firmware receives sensor measurement values in a vendor-specific binary message format. In its simplest implementation the data is not interpreted by this firmware extension. The data is packaged in a low-level message for transport to the gateway over the mesh. Here, a message is formed that comprises a device and register number and the original binary message payload.

Upon reception, the gateway interprets the binary payload using a sensor definition provided and maintained by the 3rd party vendor. The definition describes interpretation of data and reassembly of values in messages reported via the MQTT broker. For correct interpretation, the device and register numbers are matched. For each sensor, the definition specifies the expected value of the device and the register, and provides offset and length of the binary data to allow extraction. Also, data type and endianness is given as part of the definition to support the technical interpretation of the raw sensor values.

Next, these raw values are scaled by a specified factor. The gateway now filters incoming values such that only changing data are reported. Finally, the up-to-date values are inserted into a sensor data JSON message published by the MQTT broker.

Consumption Of Sensor Measurements

Applications and middleware requiring sensor measurements subscribe to sensor data messages at the MQTT broker. Not all software needs all measurements. Therefore, the sensor definition includes sensor type and index. These values are encoded in the message topic for filtering the required measurements.

The gateway minimizes broker load by publishing only changes to the data. Newly connecting clients need to explicitly request the last known sensor values. Note that the gateway reports all sensor values automatically in case its broker connection gets lost and restored. This keeps all connected clients up to date at any time.

Sensor Measurement History

The BlueRange server persists sensor data to be able to provide historic values. For this purpose the server is subscribed at all times. Past data reported by known devices can be queried using the BlueRange REST API.

Actuators And Reference Values

Devices may support altering reference settings or actioning of actuators. For interaction, data is passed from the outside into the vendor-specific firmware extension. Depending on the actionType, an acknowledgement is generated. The acknowledgement contains the current data of the register as if a read command had been issued.

Firmware Messages

The firmware messages are documented as part of the open source documentation under Sensors and Actuators.

Directly Accessing The Mesh

For device interaction, software such as configuration apps may set up a mesh access connection to the target device. This link allows sending arbitrary data messages directly to the vendor firmware by wrapping them in BlueRange packets.

In this mode of interaction the target device is protected only by the ability of the sender establishing the mesh access link. The BlueRange system does not interpret the messages being sent and therefore is not able to implement further access restrictions. Also, the sender is responsible for knowing the exact capabilities of the target device such as variations in firmware versions.

Middleware Access Via Broker

Higher level logic for observing and controlling multiple devices is implemented in the middleware software. For actioning a device, the software publishes an environment profile act message. The BlueRange system translates the message into a number of data packets, which are sent to the devices. For translation, an environment profile must be installed on the BlueRange server.

Typically, installation of the environment profile is done using a vendor-specific administration software that also securely configures the target device. The profile describes the actions that can be performed on the target device. It prevents the middleware logic from having to know concrete details of the target device at byte level such as messaging.

This is currently only implemented for touch4light but should be done in a generic way using configurations, same as with the sensors.json.

Sensor Definition

Sensors are defined by settings. A device may contain several sensors, e.g. a temperature sensor, a brightness sensor, etc. One configuration is created for each device type. These configurations are then applied to the respective devices. JSON format is used for sensor settings. An example setting for a device containing a brightness and a temperature sensor is given below.

We have added a number of comments to explain the order and relation between the different parameters.

Example

{
  "sensorModule": [
    {
      //Input Filter & Selection
      "module": "vs", //Core Module ID 151
      "component": 0,
      "register": 64257,
      "offset": 2,
      "length": 4,
      "dataType": "UINT32",
      "endianness": "LE",

      //Data transformation
      "scale": 2,
      "min": 0,
      "max": 7500,

      //Output
      "type": "BRIGHTNESS",
      "index": 0,
      "unit": "LUX",

      //Metadata
      "influenceArea": 5,
      "showInAnalytics": true,
      "sensorDataFlow": "AGGREGATE"
    },
    {
      "moduleId": 38601200, //0x024D01F0 is a VendorModuleId
      "component": 1,
      "register": 1,
      "offset": 0,
      "length": 4,
      "dataType": "FLOAT",
      "endianness": "BE",

      "formula": "VAR - 2.0",
      "scale": 1,
      "min": 15,
      "max": 30,

      "type": "TEMPERATURE",
      "index": 0,
      "unit": "CELSIUS",

      "influenceArea": 5,
      "showInAnalytics": true,
      "sensorDataFlow": "AGGREGATE"
    }
  ]
}

The above code describes the measurements of a brightness sensor in Lux and a temperature in degrees Celsius with an offset of 2 degrees. The metadata section describes how statistical evaluations can be made with that sensor. It can be shown in a heatmap where min and max will be used to calculate the intensity and the influenceArea is the radius around the device that the heatpoint occupies.

Values received from the sensors are first processed by the "formula" if present (default: no formula, i.e. the value remains unchanged). The result is then scaled with the "scale" value if present (default: no scaling). The result is the capped by the "min" and "max" values:

result = formula(value) * scale, but not larger than max and not smaller than min.

If various devices contain similar sensors that are to be lumped together, their sensor settings need to use the same "type", "index" and "unit" values for the same sensor types. If the "unit" doesn’t match for all sensors with identical "type" and "index" values, it will be discarded for all sensors and not reported.

For a better understanding, we have provided a drawing on how the extraction takes place based on the above json example:

component sense sensor processing

It is possible to extract more than one sensor from a component_sense message through the length and offset parameters which makes it possible to batch data into one message to minimize overhead and reduce the traffic.

Specification

Property Type Description

moduleId

number

Numeric identifier of module that is responsible for handling this data.

module

string

Module name such as bacnet, knx, vs, regent or 9fe01cc.

component

number

Identifies source of measurements, matched against sensor values binary message

register

number

Address of data, matched against sensor values binary message

offset

number

Index of first byte relevant in payload data of sensor values message

length

number

Count of consecutive bytes in payload data of sensor values binary message

type

string

Label such as TEMPERATURE, HUMIDITY in capital letters. Reported as is in SensorData JSON response message

index

number

Identifies the concrete sensor, such as a light head index 1…​4, reported as is to SensorData JSON message

dataType

string

Interpreted from extracted byte range, see below

endianness

string

Of values in extracted byte range: LE, BE (upper case).

formula

string

An arbitrary formula that is applied to the sensor value. VAR is the unmodified sensor value. For a full description of all possible functions, cf. mXparser documentation. (Optional, defaults to identity function)

scale

number

Floating point scale factor multiplied forming sensor value. (Optional, defaults to 1)

Metadata

min

number

Minimum value that the sensor value can have after formula and scale. Values below the minimum will be set to the minimum. (Optional, defaults to minimum range of the scaled datatype)

max

number

Maximum value that the sensor value can have after formula and scale. Values above the maximum will be set to the maximum. (Optional, defaults to maximum range of the scaled datatype)

inactiveValue

any

Sensor value to report when device inactivity was noticed. (Optional, undefined to not send any value on inactivity, other values incl. null are sent)

influenceArea

number

Radius around the device (in meters) that is measured by this sensor. Used for calculating the size of the heatmap datapoint. (Optional, defaults to 10)

showInAnalytics

boolean

Specifies whether the value is displayed in e.g. a heatmap or a graph. (Optional, defaults to false)

sensorDataFlow

enum

Specifies how far a sensor value flows, from the originating device to the persistence layer in the server. (Optional, defaults to "AGGREGATE". Allowed values see below.)

The following data types are supported (all types need to be specified in capital letters as indicated):

Data type Description

INT8

signed byte of 8 bit length

INT16

signed short of 16 bit length

INT32

signed int of 32 bit length

INT64

signed long of 64 bit length

UINT8

unsigned byte of 8 bit length

UINT16

unsigned short of 16 bit length

UINT32

unsigned int of 32 bit length

FLOAT

single-precision floating point

DOUBLE

double-precision floating point

ASCII

zero-terminated ASCII string

UTF8

zero-terminated UTF-8 string

Byte order is specified as endianness either as LE for little endian or BE for big endian.

These options are supported as sensorDataFlow:

Option Description

DISABLE

the sensor is completely disabled (not all devices support these yet)

LIMIT_TO_NETWORK

the sensor is only available within a BlueRange network itself

PUBLISH

the sensor will be published to the MQTT Broker

CACHE

the sensor will be cached in the server (not yet supported)

PERSIST

the sensor will be persisted in a database

AGGREGATE

the sensor will be aggregated by the building structure (default)

The moduleId (and module name) is used when matching data to individual firmware modules. The platform has a set of well-known modules where the module name is an easy-to-read name such as node or dfu. Alternatively, 3rd party firmware may introduce vendor-specific module identifiers that are represented as hexadecimal numbers. For further information such as the exact format used see Firmware ModuleIds.

The platform validates firmware module names and identifiers to match the specification and will reject improper values.

MQTT Messages

The sensor events are published by the Gateway using MQTT. Actuator events can be triggered by publishing to the MQTT broker. For the exact contents, refer to the MQTT specification. The sensor events are published by the Gateway using MQTT.

component_sense

SUBSCRIBE:
rltn-iot/{organizationUuid}/{siteUuid}/{beaconUuid}/sensor/{sensorType}/{sensorIndex}/sensorData

Vendor specific data is processed into a generic format using the sensors.json and then published.

component_act

PUBLISH:
rltn-iot/{organizationUuid}/{siteUuid}/{beaconUuid}/rwio/{module}/{componentRegister}/{actionReqType}

The component and register are vendor specific. A transformation method will be available in the future.

Environment Profile

The configuration is managed per site using the BlueRange REST API endpoints
/relution/api/v1/sites/{siteUuid}/environmentProfiles.

Cf. above note for generalizing the environmentProfiles.