Telemetries

Telemetries are data points, usually associated to a timestamp, sent by a device. Telemetries can have different formats. Upon reception, they are decoded depending on the codec associated to the used channel, and dispatched on the message bus following defined routing rules. There are several output options for telemetries:

• InfluxDB, a time-series database;
• WebSocket Server, which allows the telemetries to be sent in real time to any client (front-end, mobile app, etc.);
• Redis, to store the latest value of each key.

New data storages can be added by using the proper abstraction layers.

Data connectors

Telemetry data connectors need to support two operations:

• Exposing an HTTP endpoint in order for the management API to request the telemetries.
• Storing telemetries on the storage upon reception on the message bus.

Requesting telemetries

To keep the telemetries requesting standard, and avoid having to reimplement authentication and authorization each time, all telemetries requests from the front-end go through the API. It validates the user's credentials and access rights, and requests the telemetries from the data connector with a standard format. The connectors then request the data storage with the specific requesting language, and return the telemetries to the API.

The requesting endpoint must accept POST methods. The body must respect this format:

{
    "deviceIds": ["id1","id2", "..."],
    "tenantId": "...",
    "page": 0,
    "limit": 20,
    "from": "ISO timestamp",
    "to": "ISO timestamp",
    "granularity": "30s", // optional, only supported on InfluxDB to retrieve 1 data every <granularity> value. Must respect the format /^[1-9][0-9]*[smhdw]$/g
    "fields": ["temperature", "humidity"]
}

The headers must contain x-api-key, which should contain the secret used to authenticate the API.

To indicate to the API where to reach this connector, two environment variables must be provided

• TELEM_DB_REQ_<db_type>_URL: URL of the request endpoint of the data connector
• TELEM_DB_REQ_<db_type>_SECRET: Secret sent by the API in the x-api-key header

Replace <db_type> by the identifier of your connector. For instance, with InfluxDB, use TELEM_DB_REQ_INFLUXDB_URL. Providing those values will automatically make the API understand that it supports a new database type. When requesting device telemetries from the endpoint /tenant/<id>/device/<id>/telemetries, <db_type> can be provided in the header to indicate from which database the telemetries should be requested.

The endpoint must return a response respecting this format:

[
    {
        "deviceId": "id1",
        "timestamp": "ISO timestamp",
        "field": "temperature",
        "value": 25
    },
    {
        "deviceId": "id2",
        "timestamp": "ISO timestamp",
        "field": "temperature",
        "value": 74
    }
]

Storing telemetries

To store telemetries, a topic subscription (when using Service Bus) or a queue (when using RabbitMQ) must be created for the database. The message bus must be configured so that the routing key for this database correctly sends data to the specific queue. Read the routing documentation for more information. Also, see the Service Bus Terraform configuration or RabbitMQ initialization in the API source code to have a better understanding of how to configure this.

The decoded message will be delivered to this queue/subscription with this format:

{
    "deviceId": "...",
    "tenantId": "...",
    "body": {
        "temperature": 22.5,
        "humidity": 60
    },
    "deviceSentTimestamp": "ISO timestamp",
    "platformReceivedTimestamp": "ISO timestamp"
}

It's up to the data connector to fetch as many messages as it needs, to format them, and to store them in the database.