Overview

Telemetry is the primary mechanism by which a Device reports its current operating state to the server.

A Telemetry message is a JSON object of key/value pairs. The supported value types are:

• Integer — 32-bit signed (-2,147,483,648 to 2,147,483,647).
• Float — 32-bit float (-3.4e38 to 3.4e38).
• Boolean.
• String — up to 1000 bytes.

{
    "fan_speed": 50.3,
    "online": true,
    "resolution": "1080p"
}

Device state

The Device's current state is the cumulative result of every Telemetry message received: each new message is merged into the existing state, with new values overwriting previous ones.

Sample 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
}

Each time the server receives new Telemetry, it recomputes the Device state and the Rule engine evaluates that state to detect Incidents.

Removing keys
Send null as the value of a Telemetry key to remove it from the Device state. This is useful for transient keys — for example, an overheating_rate reported during an overheating Incident that should disappear from the state once the condition clears.

Sending Telemetry
A Device sends Telemetry in two situations:

1. Periodically, every few seconds, to keep the state fresh.
2. Immediately when a notable event occurs.

Periodic updates should occur every 5–120 seconds, depending on the subscribed plan.

Telemetry is merged into the Device state, so each message can include the full key set or just the keys that changed.

📘

A Telemetry message must not exceed 128 KB.

Response fields
The server's response to a Telemetry call includes the following fields:

1. config_version — Current Configuration version on the server.
   The Device should persist the version of the Configuration it last applied. If the server's config_version is higher than the persisted value, call Get Config API and apply the new Configuration.

2. command — Boolean. true when a Command is waiting for the Device.
   When true, call Get Command API to retrieve the Command, execute it, then report the outcome via Update Command API.

3. info_version — DEPRECATED. Previously the version of the Device's info tab.

4. new_licenses — Boolean. true when one or more Licenses are pending for the Device.
   When true, call Get License API, apply the License locally, and confirm the change via Update License API.

5. latest_fw_version — Version of the latest available firmware file.

6. latest_fw_file_id — ID of the latest available firmware file.

7. space_data_version — Current version of the Space Configuration. A value of 0 means the Device is not yet claimed; any other value means it is claimed.

8. success — Boolean. true if the Telemetry was accepted by the server.

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

A small number of Telemetry keys are interpreted by the platform and have additional side effects:

• lat and lng — set the Device's reported location. See Geographical location.