MQTT API

The reference documentation for all topics and message payloads is served at /asyncapi.html. The metadata is formulated as an AsyncAPI resource at /asyncapi.json. However, at the time of writing no suitable code-generator exists yet.

In BlueRange all MQTT message body payloads are JSON data. Most clients are interested in topics starting with rltn-iot/{organizationUuid}/{siteUuid}. Usually, a single subscription capturing all messages below this topic path suffices.

The MQTT topics below have to be prefixed with the above-mentioned topic prefix. You can get the organization UUID using the REST endpoint /gofer/system/security/currentAuthorization. UUIDs of network, Gateway and other devices can be easily requested from the appropriate endpoints as well. You can also use the web portal, navigate to your site and copy the UUID from your web browser’s address field. It is also displayed as part of your MQTT access token when you create one.

Asset Tracking

.../{estimatorUuid}/indoor/{assetUuid}/positionEstimate

When tracking asset positions the estimating gateway(s) continuously publish PositionEstimate messages. For reception a subscription is required only. The estimatorUuid is from the device that generated the estimation, usually a Gateway.

Notice, an asset tag may be tracked by multiple gateways. However, for ease of interpretation the BlueRange system ensures only one estimator publishes tracking data at any time. In particular, this is relevant for multi-floor environments.

Geofencing

.../{estimatorUuid}/indoor/{assetUuid}/{geofenceUuid}/geofenceEvent

Based on Asset Tracking, BlueRange emits GeofenceEvent messages as assets enter or leave geofences. These events do not flow constantly but are published only if the state actually changes. That is when the asset crosses the border of the geofence. As a result, the data does not reflect an absolute state of the system but a change relative to the last known one.

It may happen that estimation is not possible so that the state changes from last recent ENTERED or LEFT to UNKNOWN and vice versa. This may happen because of inaccurate reception, for example. Depending on use case clients may choose ignoring this third state.

RWIO Api

rltn-iot/{organizationUuid}/{networkUuid}/{deviceUuid}/rwio/{module}/{componentRegister}/{actionReqType}

The RWIO API can be used to send arbitrary component_act messages to any device in the network.

Sensors

.../{beaconUuid}/sensor/{sensorType}/{sensorIndex}/sensorData

Data of individual sensors is published in the form of a SensorData message whenever the measurement value(s) actually change. Depending on sensor type this may happen more or less frequently.

Newly connecting clients may request the last recent measurement data explicitly by publishing a SensorRequest message themselves. Upon reception all mesh gateways republish the SensorData values. This feature can be used for getting an initial state when dealing with less frequently changing sensors.

The data type of sensor measurement values depends on the sensor in question. Some sensors publish integral numbers while others may use fractions reporting values like luminance in deci-lux. Also, string values are possible. In the future the system may support publication of array data for sensors offering more than one concrete value. In short, clients should be prepared to handle any type of value.

Customizing Sensors

When integrating new sensors to the system a new definition file may be uploaded to the Mesh Gateway using the web interface under settings. The file defines a mapping of raw CLC (Connected Lighting Controller) data messages to MQTT SensorData payloads. It takes the following form:

{
	// C-style commentary is allowed for documentation purposes.
	"clcModule": [

		// CLC Sensor Definitions
		{
			"device": 22,			// device number as encoded in CLC message
			"hrAddress": "1304",	// register address as encoded in CLC message
			"numHr": 1,				// number of consecutive registers
			"type": "clc_presence",	// published as type in MQTT message
			"index": 0,				// published as index in MQTT message
			"dataType": "uint16",	// data type to decode value of CLC
			"endianness": "le",		// byte order to decode value of CLC
			"scale": 1				// scale factor for numeric values
		},
		// further definitions

	]
}

Here device and hwAddress match up the corresponding fields of the CLC message. Since the CLC message also states the number of registers required for holding the value, the numHr value serves validation purposes only and may be omitted. When given, the software ignores matching CLC messages stating an incorrect numHr value entirely. The type and index information is used as is for filling the MQTT message.

The remaining information dataType, endianness and scale is used for value extraction and conversion. The CLC message contains sensor measurement raw data in the form of an arbitrary byte array. The actual sensor value gets extracted by interpreting the given dataType using the endianness byte order given. Optionally, the resulting value is multipied by the scale, e.g. 0.1 would indicate deci-values. Notice, the scale may be omitted and is not applied to string values.

Currently, the data types supported are:

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.

Environment Profiles

…​/env/{profileType}/…​

There are a number of different profile types. Currently, supported profiles are:

Profile Type Description

t4l

Touch4Light Development

The linked documentation should be consulted for the specifics regarding the profile type.

Necessary metadata for a profile type can be queried from the REST API under:

GET /relution/api/v1/iot/sites/{siteUuid}/environmentProfiles/{profileType}