MQTT interface

MQTT API

The communication between the sensors and the server runs over four MQTT topics:

  • measurements/<sensor-identifier>: Measurements from sensors
  • logs/<sensor-identifier>: Logs from sensors
  • configurations/<sensor-identifier>: Configurations to sensors
  • acknowledgments/<sensor-identifier>: Configuration acknowledgments from sensors

To ensure that messages arrive reliably, sensors should publish and subscribe with Quality of Service (QoS) level 1. This ensures that messages are delivered at least once. The server publishes configurations as retained messages. This means that when sensors are offline, the MQTT broker retains the latest configuration and relays it to the sensors when they reconnect and subscribe to their configurations topic.

Payloads

The payloads are JSON encoded and have the following structure:

measurements/<sensor-identifier>:

// Array structure allows to batch messages
[
  {
    "value": {
      // Data points have type double
      "temperature": 23.1,
      "humidity": 0.62
    },
    "timestamp": 1683645000.0,
    "revision": 0 // Optional
  }
]

logs/<sensor-identifier>:

// Array structure allows to batch messages
[
  {
    "message": "The CPU is burning; Please call the fire department.",
    "severity": "error", // One of: info, warning, error
    "timestamp": 1683645000.0,
    "revision": 0 // Optional
  }
]

configurations/<sensor-identifier>:

{
  "configuration": {}, // Can be any valid JSON object
  "revision": 0
}

acknowledgments/<sensor-identifier>:

// Array structure allows to batch messages
[
  {
    "success": true, // Did the sensor successfully process the configuration?
    "timestamp": 1683645000.0,
    "revision": 0
  }
]
Design decisionsDatabase schema ↗