API Reference

Telemetry

Overview

Telemetry is the main method by which a device updates the server on its current operating conditions.

A telemetry message is a JSON object containing key/value pairs of telemetry items.

The supported data types are:

  • Decimal number
  • Boolean
  • String
{
    "fan_speed": 50.3,
    "online": true,
    "resolution": "1080p"
}

Device state

The current device state is calculated by adding the latest received telemetry to the previously collected data, with new information overwriting the previously sent values.

Sample device state flow:

First telemetry:
{
    "key1": "initial value",
    "key2": 2
}
Followed by
{
    "key1": "new value",
    "new_key": 30
}
Results in the following device state:
{
    "key1": "new value",
    "key2": 2,
    "new_key": 30
}

Every time the server receives new telemetry from a device, the device state is calculated and the rule engine uses the device state to determine if there are any issues with the device.

Removing keys
Sending NULL as the value of a telemetry key will remove it from the device state. This can be useful when there is temporary telemetry added (e.g., overheating_rate) that should not appear in the device state once the "overheating" error goes away.

Sending the telemetry
Devices should send telemetry:

1. Continuously, every few seconds
2. When an event occurs, to immediately update the server

It is recommended for periodic updates to occur every 5-120 seconds (depending on the subscribed plan).

Since the telemetry is appended to the latest device state, the device may send all the key/value pairs or only a subset (new keys and keys whose values have changed).

📘

The telemetry's size should not exceed 128kb.

Return values
When a device sends telemetry to the server, the reply it receives will include the following fields:

  1. config_version - The current version of the configuration.
    The device should save locally the last version of the configuration downloaded and applied to the device. If the version number of the locally saved configuration is lower than the version number returned by this API, the device should call the Get Config API and apply the new configuration.

  2. command - A Boolean field Indicating whether there is a waiting command.
    If true, there is a pending command the server needs the device to run. The device should call the Get Command API to get the command that needs to be executed. When the command has been executed, it should send an update using the Update Command API.

  3. info_version - DEPRECATED - The current version of the info tab of the device.

  4. new_licenses - A Boolean field indicating whether new licenses are available.
    When the value is true, the device should call the Get Licenses API and enable the new license. When it's done, the device should call the Update License API.

  5. latest_fw_version- The version of the latest firmware file.

  6. latest_fw_file_id - The ID of the latest firmware file.

  7. space_data_version - The current version of the space configuration.
    The space_data_version field indicates whether the device is claimed or not. If the value is 0, the device is not yet claimed; otherwise, it is claimed.

  8. success - A Boolean field that indicates whether the telemetry was successfully sent.

Example: 

{
    "config_version": 0,
    "command": false,
    "info_version": 0,
    "new_licenses": true,
    "latest_fw_version": "1.3.4",
    "latest_fw_file_id": "ca3f78be-4424-40b1-8e28-9d04e9cd9923",
    "space_data_version": 4,
    "success": true
}

Special telemetry keys

Some keys send in the telemetry object are considered special in the platform and have additional side effects: