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. Devices publish messages to topics on an MQTT broker instead of connecting directly to KODE OS. 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 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 at once

​
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 the + wildcard)
  • {building}/# — All messages from a building (using the # wildcard)
Wildcards:
  • + matches a single level (for example, building/+/temperature matches building/floor1/temperature and building/floor2/temperature)
  • # matches all remaining levels (for example, building/# matches everything under building/)

​
Security

Secure MQTT connections with TLS encryption (port 8883) whenever possible. KODE OS supports:
  • Username and 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 MQTT configuration requirements and topic structure details. MQTT connectors usually receive data as it arrives and often do not use a discovery step. See the Discovery guide for protocol-specific behavior.

​
Troubleshooting

Verify the MQTT broker is reachable from KODE OS. Check that topic subscriptions match the topics devices publish to — MQTT topics are case-sensitive and must match exactly. Confirm that broker credentials are correct and the user has subscribe permissions.
Check the QoS level on both the publisher (device) and subscriber (KODE OS). QoS 0 allows messages to be lost if the connection is unstable. Consider 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 that topic. Some MQTT brokers restrict publish access by authenticated user ACL.
Last modified on August 18, 2026