> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/connectors/mqtt-connector/what-is-mqtt.md).
# What MQTT Is
What is MQTT? A lightweight pub-sub IoT protocol — brokers, topics, QoS — and how it maps to the Kilo connector.
MQTT is a messaging protocol for exchanging small messages between devices and software. A sender **publishes** a message to a named channel called a **topic**. A server called a **broker** receives it and forwards it to clients that **subscribe** to that topic.
For example, a building meter can publish its reading to `building-a/meter-1/state`. Kilo receives the message through an [MQTT connector](/connectors/mqtt-connector.md) and maps it to the registered device and its readings. The broker transports the message; device routing and decoding determine what the reading means.
Use [Cloud MQTT](/connectors/mqtt-connector/cloud-mqtt.md) when Kilo should supply the broker connection details, or [External MQTT](/connectors/mqtt-connector/external-mqtt.md) when your deployment already has a broker.
## Architectural roles
Three roles participate in any MQTT exchange:
* **Broker** — the routing fabric. Devices and applications connect to the broker; the broker matches publishers to subscribers based on topic patterns and handles delivery according to the QoS level requested. The broker is the single connection point for every MQTT participant; there is no peer-to-peer fallback.
* **Publishers** — produce messages to topics. Industrial publishers in practice include PLCs with MQTT firmware, edge gateways translating Modbus / BACnet / OPC-UA to MQTT, vendor-specific bridges (Zigbee2MQTT, ESPHome), and custom embedded firmware on field devices.
* **Subscribers** — consume messages. The Kilo IoT Server's MQTT connector is a subscriber. Multiple subscribers can consume the same topics independently — your existing dashboard, on-premise historian, and the platform can all receive the same data without coordination.
```
Field devices ──┐
PLCs ───────────┤
Bridges ────────┼──> Broker ──> Subscribers (Kilo, historian, dashboards, ...)
Edge gateways ──┘
```
Devices are typically both publishers (reporting telemetry) and subscribers (receiving setpoints, configuration, downlinks). The broker is the always-present middle.
## Topics: the routing key
Each MQTT message carries a **topic** — a slash-separated UTF-8 string. The broker uses topics to match publishers to subscribers; subscribers register interest in patterns using `+` (single-level wildcard) and `#` (multi-level wildcard at the end). Topics are not predefined; the publishing party chooses the topic, and a topic catalog is established by convention or vendor agreement.
Common conventions in industrial deployments:
* **Hierarchical topic structure by site/asset/metric** — for example, `plant-3/line-a/extruder-04/temperature` or `building-12/floor-2/ahu-1/setpoint`. This makes wildcard subscriptions natural for site-wide aggregation.
* **Vendor-prefixed schemes** for protocol bridges — e.g. `zigbee2mqtt/{friendlyName}`, `tasmota/{deviceName}/SENSOR`, `mosquitto/+/state`. The Kilo IoT Server supports any topic shape through the **Device ID Topic** pattern field — see [Topics and device routing](/connectors/mqtt-connector/topics-and-device-routing.md).
* **Sparkplug B namespaces** for OPC-UA-style hierarchies — e.g. `spBv1.0/{group}/DDATA/{node}/{device}`. The platform consumes these as ordinary MQTT topics; Sparkplug-specific decoding is handled by the publishing edge gateway.
The platform's connector configuration treats topics as patterns: on each device you build the topic out of segments and mark the one that carries the device identifier, and the platform extracts the identifier from that position when each message arrives.
## Payloads: structured JSON in practice
The MQTT protocol itself is payload-agnostic — bytes go in, bytes come out. In production deployments JSON is overwhelmingly the format of choice for new systems, with occasional Sparkplug B (Protocol Buffers) and proprietary binary formats for legacy bridges. The Kilo IoT Server's MQTT connector parses JSON payloads automatically — flat objects, nested objects (flattened to dot-notation paths), and primitive values are all handled.
A typical industrial telemetry payload:
```json
{
"timestamp": "2026-01-15T14:32:18Z",
"temperature": 78.4,
"pressure": 4.21,
"vibration": {"rms": 0.42, "peak": 1.8},
"status": "running"
}
```
When mapped to platform metrics, `temperature`, `pressure`, `vibration.rms`, `vibration.peak`, and `status` each become an addressable Connector Key. The Mapping tab links each Connector Key to a normalized metric, which is what then flows into the Digital Twin, the rules engine, and historical storage.
For readings carried in topic segments, configure **Topic Telemetry** on the device's **Connection** tab. JSON payloads normally need no telemetry rows. See [Topics and device routing](/connectors/mqtt-connector/topics-and-device-routing.md#topic-telemetry) for the editor's supported patterns.
## QoS, retained messages, last-will
Three protocol features come up enough in industrial deployments to be worth stating explicitly:
* **QoS levels** — 0 (at most once), 1 (at least once), 2 (exactly once). The platform's connector handles whatever QoS the publisher uses; pick the level that matches your operational tolerance for duplicates vs. drops. QoS 2 has the highest broker overhead and is typically reserved for control commands or critical state changes.
* **Retained messages** — flagged messages that the broker stores and replays to new subscribers on connect. Useful for current-state advertisement (e.g. "online/offline" announcements). If the broker delivers retained messages to the platform as standard subscribed publishes, they can be mapped like any other payload — verify against your broker's behavior.
* **Last-will and testament (LWT)** — a message the broker publishes on the publisher's behalf if it disconnects unexpectedly. Common pattern: a device's LWT publishes `"offline"` to its status topic, so subscribers see disconnection state changes without polling. If your broker delivers LWT messages to the connector as standard MQTT publishes, they can be mapped like any other payload.
These features are configured by the publishing party, not by the connector. The connector accepts whatever the broker delivers.
## Why MQTT for industrial IoT
The protocol's adoption in commercial deployments is driven by three properties that map cleanly to operational requirements:
* **Bandwidth efficiency.** Wire-format overhead is small enough for cellular-attached field devices and high-density wireless deployments. Keep-alives and pings are configurable to fit available connectivity windows.
* **Decoupled producers and consumers.** Adding a new subscriber (a historian, a third-party analytics platform, the Kilo IoT Server) does not require reconfiguring publishers. Operations teams can roll out new consumers without touching the field.
* **Mature ecosystem.** Mosquitto, HiveMQ, AWS IoT Core, Azure IoT Hub, and many other brokers exist. Most modern industrial protocol bridges (Modbus-to-MQTT, BACnet-to-MQTT, Sparkplug B edge gateways) ship with first-class MQTT publishing.
For deployment-specific configuration, continue to [Cloud MQTT](/connectors/mqtt-connector/cloud-mqtt.md) for platform-managed brokers, or [External MQTT](/connectors/mqtt-connector/external-mqtt.md) for connecting an existing broker.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.kiloiot.io/connectors/mqtt-connector/what-is-mqtt.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
