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

```mermaid theme={null}
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**    | The central server that receives all published messages and forwards them to subscribers     |
| **Topic**     | A hierarchical string that categorizes messages (e.g., `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 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:

| Field                   | Description                                                               |
| ----------------------- | ------------------------------------------------------------------------- |
| **Host**                | The MQTT broker's hostname or IP address                                  |
| **Port**                | The broker's port (default: 1883 for TCP, 8883 for TLS)                   |
| **Username / Password** | Credentials for authenticating with the broker                            |
| **Telemetry Topic**     | The topic pattern where devices publish sensor data                       |
| **Metadata Topic**      | The topic pattern where devices publish device metadata                   |
| **Command Topic**       | The topic for sending commands back to devices (if 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 `+` 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

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

  <Accordion title="Intermittent data gaps">
    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.
  </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 the command topic. Some MQTT brokers restrict publish access to specific topics based on the authenticated user's ACL.
  </Accordion>
</AccordionGroup>