API Reference

Events in MQTT - With Publish

API Overview

All the messages described in this section correlate with the HTTP-based APIs described in detail in the Quickstart and API Endpoints sections of the documentation.

📘

File/dump-related APIs

File download/upload APIs are not implemented in this protocol. You may use the Get File and Send Dump REST APIs to perform these actions.

You can authenticate using the same device ID and access key that you got using the Register Device API.

Send Telemetry

topic: v1/device/DEVICE_ID/telemetry
userProperties: { "device_id": "DEVICE_ID", "access_key": "ACCESS_KEY" }
payload: 

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

Detailed information on supported fields can be found in the Send Telemetry API documentation.

Get Config

topic: v1/device/DEVICE_ID/config
responseTopic: v1/device/DEVICE_ID/config/update
payload: 

{ 
  version: "CONFIG_VERSION", 
  last_updated: "2021-08-04T07:45:44.122Z",
  …configuration_fields 
}

Update Config

topic: v1/device/DEVICE_ID/config/update
userProperties: { "device_id": "DEVICE_ID", "access_key": "ACCESS_KEY" }
payload: 

{ 
  version: "CONFIG_VERSION", 
  last_updated: "2021-08-04T07:45:44.122Z", 
  …configuration_fields 
}

Get Command

topic: v1/device/DEVICE_ID/commands
responseTopic: v1/device/DEVICE_ID/commands/update
payload: 

{
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
    "status": "pending",
    "name": "update_firmware",
    "parameters": {
        "url": "https://s3.amazonaws.com/xxxx.zip",
        "version": "1.3.4"
    }
}

Update Command

topic: v1/device/DEVICE_ID/commands/update
userProperties: { "device_id": "DEVICE_ID", "access_key": "ACCESS_KEY" }
payload: 

{
    "status": "done",
    "message": "great, success!",
    "id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Possible command statuses: done | in_progress | error

Get License

topic: v1/device/DEVICE_ID/license
responseTopic: v1/device/DEVICE_ID/license/update
payload: 

{
  "data": "device-specific license info...",
  "signature": "RSA signature...",
  "id": "xxxxxxxx-xxxx...",
  "add": true,
  "update": false,
  "remove": false,
}

The add/update/remove fields will be true depending on what operation the device needs to perform (either adding, updating, or removing a license).

Update License

topic: v1/device/DEVICE_ID/license/update
userProperties: { "device_id": "DEVICE_ID", "access_key": "ACCESS_KEY" }
payload: 

{
  "id": "license_id",
  "state": "done",
  "error": "great not success!"
}

Possible license values: inuse | removed | error

Get Space Info

topic: v1/device/DEVICE_ID/space_info
payload: 

{
    "location": {
        "coordinates": {
            "lat": 51.165691,
            "lng": 10.451526
        },
        "utc_offset": 60,
        "name": "Germany"
    },
    "temperature_units": "celsius",
    "maintenance": false,
    "name": "Interactive Class",
    "local_time": "2022-03-17T10:55:28+01:00"
}

Get Firmware Version

topic: v1/device/DEVICE_ID/firmware
payload: 

{
  "latest_fw_version": "1.0.8",
  "latest_fw_file_id": "f62e0c28-5ce2-4590-a6cf-2f255a338544"
}

Update Device

topic: v1/device/DEVICE_ID/update
userProperties: { "device_id": "DEVICE_ID", "access_key": "ACCESS_KEY" }
payload: 

{ 
  "firmware_version": "VERSION", 
  "name": "NAME" 
}

Set Cloud Settings

topic: v1/device/DEVICE_ID/cloud_settings/update
userProperties: {"device_id": "DEVICE_ID", "access_key": "ACCESS_KEY" }
payload:

{ 
  "property": "property_name", 
  "value": "property_value" 
}

Supported properties: Set Cloud Settings

Get latest snapshot

Request the latest snapshot of the device, sent in each relevant topic specified above.

It will do the following:

  • Publish space info information
  • Publish device configuration
  • Publish next command if available
  • Publish licenses information
  • Publish firmware event in case the current device firmware version does not match latest firmware version

topic: v1/device/DEVICE_ID/get
userProperties: {"device_id": "DEVICE_ID", "access_key": "ACCESS_KEY" }