Skip to content

MQTT

Jump to bottom
Matej Sychra edited this page Jul 28, 2017 · 4 revisions

MQTT

Main purpose of MQTT in THiNX is the Device Status. It does not work without that (shows only last connected time).

Secondary purposes are: firmware update (multi-file+ott), actionable notifications and generic messaging.

TOC

  • Authentication

  • Channels

    • Status Channel

    • Device Channel

  • Notifications

    • Status Notifications

    • Device Registration

    • Actionable Notifications

  • Streamed Firmware Updates

    • Stream Client connection requirements

  • On QoS

Authentication

THiNX server enables the authentication on MQTT on device registration.

Client devices must authenticate to the MQTT broker at thinx.cloud on ports 1883 and 8883 using their owner_id and api_key used on registration as MQTT as username/password.

Channels

There are two designated channels:

Status Channel

/owner_id/udid/status - for status (connected/disconnected/registration) messages

Device SHOULD send status notifications and registration data to this channel in order to aquire possible firmware update.

Status channels take all the heavy annoying high-speed traffic.

Device Channel

/owner_id/udid - for user communication with device

The device channel is used for human communication to the device (e.g. respond to Actionable Notifications).

Shared Channel

/owner_id/shared - for user communication between devices of same owner

The device channel is used for machine-to-machine communication between devices of same owner, because devices otherwise do not have access to others’ channels.

Notifications

Status Notifications

Device SHOULD send following messages to this channel:

	{ "status": "connected" }

	{ "status": "disconnected" } (as MQTT Last Will)

Device Registration

Device CAN send following message to this channel in order to aquire possible firmware update:

    { "registration":
        { "mac":"5CCF7FE4631D",
          "firmware":"thinx-firmware-esp8266-1.7.24:2017-07-25",
          "version":"1.7.24",
          "commit":"24e715f7fb5dc3ebe228165dae45fa933fade1bd",
          "owner":"cedc16bb6bb06daaa3ff6d30666d91aacd6e3efbf9abbc151b4dcade59af7c12",
          "alias":"robotdyn-mega+wifi",
          "platform":"platformio"
        }
    }

In case the 'commit' parameter is omitted, version will be used for matching. The 'alias' parameter can be ommitted as well, because it's only informative and not processed in any way.

The backend may reply with either OK or UPDATE_AVAILABLE response types.

Actionable Notifications

In case the device has THINX_AUTO_UPDATE disabled, it MUST ask user for consent before upgrading. This is done through Actionable Notifications sent to device channel.

Actionable notification declares response_type of bool or string and the notification may not be responded to at all. MQTT messages are forwarded using WebSocket to the RTM console so user can see what happens and can react.

Each notification has a corellation-id called nid which is currently based on udid and therefore each device can hold only one pending transaction. Can be easily extended to UDID in future.

  1. Device finds out it has update available
  2. Device sends actionable notification in following format:
    {
        notification: {
        udid: "41528570-6965-11e7-9b6d-6924bbc83a7c",
        nid: "nid:12345A",
        title: "Firmware update available",
        body: "Do you want to update your device now?",
        type: "action",
        response_type: "bool"
        }
    }
  1. The transaction is kept in Redis, notification is extended with UDID and NID in Messenger.js and forwarded to web interface using websocket.
    {
        notification: {
        udid: "41528570-6965-11e7-9b6d-6924bbc83a7c",
        nid: "nid:12345A",
        title: "Firmware update available",
        body: "Do you want to update your device now?",
        type: "action",
        response_type: "bool"
        response: true
        done: true
        }
    }

  1. User responds to notification using Yes/No buttons (or string in future) and the reply to notification is sent using API call to the MQTT queue and forwarded using Messenger back to the device and stored to Redis.

  2. In case the request reply is true, device can commence the firmware update now.

Streamed Firmware Updates

On future roadmap.

QoS

  • Status Notifications should be sent from device with QoS 0 and use the RETAIN feature
  • Actionable Notifications should be send/replied to with QoS 2 (Retain is questionable here, must be unretained from device side after action is done)
Clone this wiki locally