> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.kodelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MQTT integrations

> How KODE OS receives real-time data from MQTT-based devices and systems

> 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.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    D1["Device 1"] -->|"publish"| Broker["MQTT broker"]
    D2["Device 2"] -->|"publish"| Broker
    D3["Device 3"] -->|"publish"| Broker
    Broker -->|"subscribe"| KODE["KODE OS"]
```

### Key concepts

| Concept       | Description                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------- |
| **Broker**    | Central server that receives published messages and forwards them to subscribers                  |
| **Topic**     | Hierarchical string that categorizes messages (for example, `building/floor1/sensor/temperature`) |
| **Publish**   | A device sends a message to a specific topic on the broker                                        |
| **Subscribe** | KODE OS registers interest in specific topics to receive their messages                           |
| **QoS**       | Quality of Service level (0 = at most once, 1 = at least once, 2 = exactly once)                  |

## 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:

| Field                   | Description                                                           |
| ----------------------- | --------------------------------------------------------------------- |
| **Host**                | MQTT broker hostname or IP address                                    |
| **Port**                | Broker port (default: 1883 for TCP, 8883 for TLS)                     |
| **Username / Password** | Credentials for authenticating with the broker                        |
| **Telemetry topic**     | Topic pattern where devices publish sensor data                       |
| **Metadata topic**      | Topic pattern where devices publish device metadata                   |
| **Command topic**       | Topic for sending commands back to devices when actions are supported |

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](/products/integrations/capabilities/discovery) for protocol-specific behavior.

## Troubleshooting

<AccordionGroup>
  <Accordion title="No data is being received">
    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.
  </Accordion>

  <Accordion title="Intermittent data gaps">
    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.
  </Accordion>

  <Accordion title="Cannot send commands to devices">
    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.
  </Accordion>
</AccordionGroup>