Telemetry - quick access to all messages parameters reported by the device

In some tasks, you don’t need to continuously receive messages reported by the device — you just need its current state and the last value of some message parameters to answer the questions like:

1. What is the last position of my device?

2. When was the device online last time?

3. What is the last value of the given sensor and when was it updated?

Telemetry is a structure that analyses each new message reported by the registered device, splits it on the dedicated parameters from which device message consists and for each updated parameter republishes its value into the dedicated MQTT topic and stores for subsequent access via REST or MQTT. Following is the principle of device telemetry operation:

You can get device telemetry via the appropriate REST API call (GET /gw/devices/{device-selector}/telemetry/{telemetry-selector}). Telemetry will be returned as an object where the key is a parameter name, value is an object with fields value, and ts is a timestamp when the value was updated, e.g. 

     "telemetry": {
        "channel_id": {
          "ts": 1540982367,
          "value": 3300
        },
        "chat_id": {
          "ts": 1540982367,
          "value": 168488620
        },...etc

It is a good practice to obtain telemetry over MQTT API:

• Subscribe to the topic flespi/state/gw/devices/{device-id}/telemetry/+
• Receive current telemetry values during subscription.
• Receive updated value for every parameter each time it changes (with MQTT 5.0 the timestamp of the parameter being updated is sent in MQTT message user properties).

Telemetry will be updated automatically as soon as device will process new messages. To update telemetry manually just register a new device message using POST /gw/devices/{dev-selector}/messages API call with appropriate timestamp and parameter values set in the body of request.

Telemetry can be viewed in TrackIt:

or in the Telemetry tab in flespi panel UI in the device view:

You use device telemetry when you do not need device message as a whole - just few parameters and only their latest values. If you want to receive messages the way they were reported by the device or operate with multiple message parameters in a single call handler you'd better to retrieve device messages via REST API (use reverse=true and count=1 to retrieve the latest message reported by the device) or via MQTT topic: flespi/message/gw/devices/{device-id}.

Please note that device telemetry values are stored for 370 days and limited by 1024 recently updated parameters. It means that if the device does not update some parameters in 370 days, these parameters will disappear from telemetry automatically. The length of parameter value (string, object or array) to be stored in telemetry is limited by 4Kb.

You can also remove certain parameters from telemetry at any time using the special REST API request (DELETE gw/devices/{device-selector}/telemetry/{telemetry-selector}) or by clicking the red cross button next to the respective parameter in the Telemetry tab. Telemetry is available as separate submodule in ACL tokens, so it is possible to give access to Telemetry actions without giving access to other submodules.