Skip to main content

MQTT Communication Specification

Overview​

This document describes the MQTT communication protocol between devices (sensors/actuators) and the client application. It includes the topics, payload formats, and the descriptions for publishing and subscribing messages.

Topics Legend:​

  • id: Unique identifier for a device. This is generated with a SHA1 hash truncated to 10 characters. Using a hash prevents mixup, which is a risk if the id is chosen by the developer. This also means that the device generates a new id each time it is restarted.
  • base_topic: The base topic will be declared by the device. It should consist of the devicetype/category, for example sensor/temperature or actuator/motor.

Client App​

This is an example work flow from the Client apps point of view. The client will read the connected devices data, so when you implement your device adapter you will have to think of this in reverse. The topics that the client subscribes to will be the topics that the devices publishes to and vice versa.

  1. Subscribe to device_connected: The client subscribes to the device_connected topic to monitor the connection statuses of devices.
  2. Subscribe to device_meta: The client subscribes to the device_meta topic to receive device metadata when it is published.
  3. Publish to publish_all_connected: The client sends a message to the publish_all_connected topic, requesting all devices to publish their connection status.
  4. Collect responses from device_connected: The client gathers device IDs as devices respond by publishing their connection status to the device_connected topic.
  5. Request metadata via publish_meta/{id}: For each device ID received, the client sends a request to the publish_meta/{id} topic to obtain metadata for that specific device.
  6. Process metadata from device_meta: The client listens on the device_meta topic (subscribed in step 2) and processes the metadata published by the devices. This metadata provides details such as the base topic and the datatype of the device's values.
  7. Subscribe to {base_topic}/{id}: After receiving the metadata, the client subscribes to the {base_topic}/{id} topic to receive the device's sensor values, formatted according to the metadata.
  8. Receive and parse sensor values on {base_topic}/{id}: The client receives real-time sensor data from the device on this topic and parses it correctly based on the datatype specified in the device metadata.

Device topics​

Subscribe Topics​

1. Subscribe to Input Parameters​

  • Topic: {base_topic}/parameters/{id}
  • QoS: 1
  • Retained: No
  • Payload: 
    {
      "param1": {
        "value": "number",
      },
      "param2": {
        "..."
      }
    }
  • Description:
    Devices (e.g., actuators) subscribe to this topic to receive input values for control or action. These inputs define the state of each input with the current value and timestamp.

2. Request Device Meta Data​

  • Topic: publish_meta/{id}
  • QoS: 1
  • Retained: No
  • Payload: 
    {
      "value": "1"
    }
  • Description:
    This topic is used to request the device to republish its meta data to the device_meta topic. The message acts as a signal for the device to send its configuration data again.

3. Request All Connected Devices​

  • Topic: publish_all_connected
  • QoS: 1
  • Retained: No
  • Payload: 
    {
      "value": "1"
    }
  • Description:
    This topic is used to request all devices to republish their connection status. Devices receiving this message should respond by publishing their connection status to the device_connected topic.

Publish Topics​

1. Notify Device Connection​

  • Topic: device_connected
  • QoS: 1
  • Retained: No
  • Payload: 
    {
      "id": "device_id"
    }
  • Description:
    Devices use this topic to notify the platform that they are connected. The payload contains the unique device ID.

2. Publish Device Meta Data​

  • Topic: device_meta
  • QoS: 1
  • Retained: No
  • Payload: 
    {
      "id": "device_id",
      "name": "Display name",
      "base_topic": "base_topic",
      "datatype": "bool | int | float",
      "minValue": "number",
      "maxValue": "number",
      "unit": "Measurement unit",
      "parameters": {
        "param1": {
          "datatype": "datatype1",
          "min": "number",
          "max": "number"
        },
        "param2": {
          "datatype": "datatype2",
          "min": "number",
          "max": "number"
        }
      }
    }
  • Description:
    Devices publish their metadata to this topic, which includes details like datatype, parameter specifications, and other relevant configuration data. The minimum and maximum values are important for scaling on GUIs. The datatype can be either bool, int or float. This is the datatype of the measurement value the device adapter will send.

3. Publish Sensor Data​

  • Topic: {base_topic}/{id}
  • QoS: 0
  • Retained: No
  • Payload: 
    {
      "value": "number | [number]", 
    }
  • Description:
    Devices use this topic to publish sensor data with specific units and value limits for each input.

Payload Examples​

Device Meta Data Example​

  • Topic: device_meta/{id}
  • Payload: 
    {
      "id": "2ie923i3",
      "name": "Voltage meter",
      "base_topic": "sensor/voltage",
      "datatype": "float",
      "unit": "V",
      "minValue": 8,
      "maxValue": 24,
      "parameters": {
        "offset": {
          "datatype": "float",
          "min": -10,
          "max": 10
        },
        "voltage_range": {
          "datatype": "int",
          "min": 0,
          "max": 5
        }
      }
    }

Sensor Data Example​

Single value:

  • Topic: base_topic/{id}
  • Payload: 
    {
      "value": 23.4,   
    }

List of values:

  • Topic: base_topic/{id}
  • Payload: 
    {
      "value": [23.4, 24.1, 25.0],   
    }