Devices

Devices (a "thing") represent deployed hardware in the field capable of connecting to the internet via a supported Connectivity. Devices send data via Uplinks and optionally receive commands via Downlinks. Devices can be managed in the Asset inventory.

Identifiers

Devices are uniquely identified by both the device id, which can be set during device creation and the akenza device ID which is generated by the system.

Usually, the device ID maps to the physical ID of the device (for LoRaWAN devices the devEUI, for HTTP and MQTT devices any suitable identifier). The device ID can be changed during the lifetime of a device (e.g. when a sensor is replaced), whereas the akenza device ID remains the same.

Data is sent using the device ID and all REST API operations require the akenza device id.

Configuration

A device has different fields based on the assigned data flow (i.e. LoRaWAN connectivity parameters).

Data

Devices send data to the cloud using uplinks. Usually, devices send data either interval or event-based. Uplinks trigger the data processing pipeline specified by a data flow.

Data can be partitioned into Topics based on its purpose or schema. This helps to retain the structure of the data.

One data point is referred to as a Sample, it is uniquely identifiable by the akenza device id, topic and timestamp.

It is only possible to access historical device data when an akenzaDB output connector is used.

Custom Fields

It is possible to assign custom fields to a device which can be used to store additional metadata.

Uplink Metrics

Uplink metrics are recorded and updated each time a device sends an uplink. They contain information about the payload size, signal strength, spreading factor and more.

Different metrics are recorded depending on connectivity and provider

Example HTTP, MQTT, CoAP Uplink Metrics

{
    "uplinkSize": 478,
    "timestamp": "2021-09-17T07:10:16Z",
}

Example LoRa Uplink Metrics

{
    "uplinkSize": 301,
    "timestamp": "2021-09-17T07:01:17Z",
    "port": 85,
    "frameCountUp": 113,
    "frameCountDown": 115,
    "rssi": -95,
    "snr": 1.25,
    "sf": 7,
    "txPower": 2,
    "numberOfGateways": 1,
    "esp": -97.43,
    "sqi": 3,
    "batteryLevel": 80.3
}

Battery Level

The battery level is extracted from the sample once the script has been processed. The sample has to contain either the property batteryLevel or batteryPercent in order for the uplink metric to be set.

If multiple samples, containing one of the battery level properties, are emitted in the same uplink, the lowest value will be stored.

For passthrough data flows the battery level is directly extracted from the uplink payload, if it contains the above mentioned properties.

Signal Quality Indicator (SQI)

LoRa uplinks usually provide the necessary information to calculate the SQI. It is calculated based on snr (signal to noise ratio) and rssi (receive signal strength indicator) and indicates the signal quality on a scale of 1 (weak signal) to 3 (strong signal).

The Signal Quality Indicator is also extraced from the sample once the script has been processed. The sample has to contain one of the following properties: sqi, signalQuality or signalQualityIndicator. If more than one of these properties are specified, the above order will take precedence. The values must range from 1 to 3, floating numbers will be rounded down. If the values are outside of this range, the value will be ignored.

If multiple samples, containing one of the SQI properties, are emitted in the same uplink, the lowest value will be stored.

For passthrough data flows the signal quality indicator is directly extracted from the uplink payload, if it contains the above mentioned properties.