Skip to main content
How KODE OS receives real-time data from MQTT-based devices and systems
MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol designed for constrained devices and low-bandwidth networks. KODE OS uses MQTT to receive real-time data from IoT devices, sensors, and building systems that publish messages to MQTT brokers.

​
How MQTT Works

MQTT uses a publish/subscribe model. Instead of devices connecting directly to KODE OS, they publish messages to topics on an MQTT broker. KODE OS subscribes to those topics and processes incoming messages as they arrive.

​
Key Concepts

​
MQTT vs. Polling

Unlike REST-based integrations where KODE OS polls for data at intervals, MQTT delivers data in real-time as soon as the device publishes it. This results in:
  • Lower latency: Data arrives in milliseconds rather than waiting for the next polling interval
  • Reduced bandwidth: Only changed values are transmitted, rather than full data snapshots
  • Better scalability: The broker handles routing, so thousands of devices can publish simultaneously

​
MQTT Connector Configuration

MQTT integrations in KODE OS typically require the following configuration: Some MQTT integrations use additional topic configurations for schedules, status updates, or discovery.

​
Topic Structure

MQTT topics are hierarchical strings separated by forward slashes. The exact structure depends on the integration and the device manufacturer. Common patterns:
  • {building}/{floor}/{device}/telemetry — Sensor data from a specific device
  • {building}/+/+/metadata — Metadata from all devices (using + wildcard)
  • {building}/# — All messages from a building (using # wildcard)
Wildcards:
  • + matches a single level (e.g., building/+/temperature matches building/floor1/temperature and building/floor2/temperature)
  • # matches all remaining levels (e.g., building/# matches everything under building/)

​
Security

MQTT connections should be secured using TLS encryption (port 8883) whenever possible. KODE OS supports:
  • Username/password authentication for basic broker access
  • TLS certificates for encrypted connections
  • Client certificates for mutual TLS authentication where required

​
MQTT Integrations in KODE OS

Several integrations use MQTT as their primary communication method:
  • KODE MQTT — Generic MQTT connector for custom device integrations
  • EnOcean — Wireless sensor protocol bridged via MQTT
  • CloudGate — IoT gateway that publishes device data via MQTT
  • Other integrations that support MQTT as an alternative to REST polling
Check each integration’s page for specific MQTT configuration requirements and topic structure details.

​
Troubleshooting

Verify the MQTT broker is reachable from KODE OS. Check that the topic subscriptions match the topics the devices are publishing to — MQTT topics are case-sensitive and must match exactly. Also confirm that the broker credentials are correct and the user has subscribe permissions.
Check the QoS level configured on both the publisher (device) and subscriber (KODE OS). QoS 0 allows messages to be lost if the connection is unstable. Consider upgrading to QoS 1 or 2 for more reliable delivery. Also verify that the MQTT broker is not overloaded or rate-limiting connections.
Verify that the command topic is correctly configured and that the KODE OS MQTT client has publish permissions on the command topic. Some MQTT brokers restrict publish access to specific topics based on the authenticated user’s ACL.
Last modified on March 29, 2026