API overview

The MQTT messages in this section correspond one-to-one with the HTTPS APIs documented in the Quickstart and API Endpoints sections.

📘
File/dump APIs are not exposed over MQTT
Use the HTTPS Get File and Send Dump endpoints for file transfer. Authenticate them with the same id and access_key returned by 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" }