Send Telemetry

📘
Use the hub_url received in the registration response as your base URL.

📘
This API requires the device to authenticate, see Device Authentication.

Update the server with the current device state.

See the Quickstart guide for a detailed explanation of Telemetry.

Telemetry Data

Name	Type	Description
status	string	Device status: online, offline, or error. Note: This field is automatically injected into the the `telemetries` object below.
timestamp	datetime	Optional: Time when the telemetry was taken (a string based on ISO_8601 format). If this field is not provided, the server sets the telemetry's time to the current server time. Example: 2022-01-01T01:00:00.000Z
telemetries	object	Optional: Telemetry key & value pairs.
override	boolean	Optional: Sending this key with the value set to true will cause this telemetry object to override the current state. Any keys previously set and not included in this telemetry object will be removed. This is useful after events such as a restart, for the first telemetry sent.

{
    "status": "online",
    "timestamp": "2021-08-04T07:45:44.122Z",
    "telemetries": {
        "fan_speed": 100.1,
        "connection": "4g",
        "usbc": true
    }
}

{
    "status": "error",
    "telemetries": {
      "input": "Unknown"
    },
    "message": "Unknown input connected"
}

Return Data

Name	Type	Description
config_version	integer	Current version of the configuration on the server. The device developer should save locally the last version of the configuration downloaded and applied to the device. If the locally saved version number is lower than that returned by this API, the device should call the Get Config API and apply the new configuration.
command	boolean	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, the device should send an update using the Update Command API.
new_licenses	boolean	If true, there are new licenses available for the device. The device should call the Get Licenses API and enable the new licenses.
success	boolean	If true, the telemetry was successfully sent.
info_version	integer	Current version of the info tab of the device.
latest_fw_version	string	Version of the latest firmware file.
latest_fw_file_id	string	ID of the latest firmware file.
space_data_version	integer	Current version of the space configuration. This field can be used to indicate whether the device is claimed or not. When the value is 0, the device is not yet claimed; otherwise, it is claimed.

{
    "config_version": 0,
    "command": false,
    "info_version": 0,
    "new_licenses": true,
    "latest_fw_version": "1.3.4",
    "latest_fw_file_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "space_data_version": 4,
    "success": true
}

Managing new firmware version notifications

Devices keep two variables:

curr_ver - Current firmware version
latest_ver - Last known latest available version (set to curr_ver at initialization)

Every time a device calls the Send Telemetry API, it should check the latest_fw_version field returned in the server's reply. If it's higher than latest_ver, it should show a notification and offer the user the choice to upgrade. The device should overwrite its local latest_ver with latest_fw_version to prevent the notification from popping up again.