For the complete documentation index, see llms.txt. This page is also available as Markdown.

What MQTT is

A friendly intro to MQTT brokers, topics, and JSON payloads — the messaging behind the smart home.

MQTT is a way for devices and software to exchange messages. Think of a temperature sensor sending a reading to a named channel, such as home/bedroom/temperature. That channel is a topic. A server called a broker receives the message and passes it to software listening to that topic.

Sending a message is called publishing; asking to receive messages is subscribing. Chirp uses an MQTT connection to receive readings and associate them with your registered sensors. Zigbee sensors need a bridge such as Zigbee2MQTT to translate their messages first.

Chirp supplies the broker connection with Cloud MQTT.

How does MQTT work in simple terms?

Three things are involved in any MQTT setup:

  • A broker — the central post office that everything connects to. Devices don't talk to each other directly; they all talk to the broker, and the broker forwards messages to whoever asked for them.

  • Publishers — anything that sends messages. A Zigbee2MQTT bridge publishing temperature readings, an ESP32 publishing soil moisture, a smart plug publishing its on/off state.

  • Subscribers — anything that listens for messages. Chirp's MQTT connector is a subscriber; so is your home automation hub if you have one.

The same device can be both a publisher (it tells the broker about its temperature) and a subscriber (it listens for commands telling it to change a setpoint). The broker is the one constant — every message goes through it.

Living room sensor  →  publish  →
                                   Broker  →  forward  →  Chirp
Kitchen sensor      →  publish  →

Chirp's MQTT connector subscribes to messages the broker is forwarding. When you register a device, you're telling Chirp which messages from the broker belong to which device record.

What is an MQTT topic?

Every MQTT message has a topic — a slash-separated path that identifies what the message is about. The broker uses topics to route messages: subscribers say "I'm interested in topics that look like home/+/temperature," and the broker delivers anything matching that pattern.

Topics are not predefined. Whoever publishes a message decides the topic — there's no central registry. Conventions vary by software:

  • Zigbee2MQTT publishes each device's data to zigbee2mqtt/{friendlyName} — for example, zigbee2mqtt/LivingRoomSensor. Below this device-level topic, the bridge also publishes status, command-acknowledgements, and per-device subtopics for actions like /set and /get.

  • Tasmota smart plugs publish to tele/{deviceName}/SENSOR for periodic telemetry, stat/{deviceName}/RESULT for state changes, and several other topics.

  • Custom firmware can use whatever topic scheme you write into it. A common pattern is home/{location}/{deviceName}/{metric}.

When you register a device in Chirp, the Device ID Topic field is where you tell the connector what the topic shape looks like. You write the pattern with {{deviceId}} standing in for the part of the topic that names the device — for Zigbee2MQTT, that's zigbee2mqtt/{{deviceId}}. Chirp matches incoming topics against the pattern and pulls the device identifier out of the placeholder position.

What is an MQTT payload?

The body of an MQTT message is the payload. MQTT itself doesn't care what's in there — bytes are bytes — but in practice almost every modern device publishes JSON.

A typical Zigbee temperature/humidity sensor publishes something like:

That single message contains four sensor metrics, all delivered together as a flat object. Chirp's Mapping tab reads the keys from this JSON and maps them to your sensor's metric templates — temperature becomes the temperature reading, humidity becomes humidity, and so on.

Some devices publish each measurement to its own topic with just a number as the payload:

For that style, you add per-topic rows on the Telemetry topics section so Chirp knows which topic carries which metric. The flat-JSON case (one topic, all metrics in the payload) is more common and is the default path.

What are QoS and retained messages in MQTT?

MQTT has features beyond the basics: three quality-of-service levels (QoS 0/1/2), retained messages that the broker keeps and replays to new subscribers, last-will messages that the broker publishes when a device disconnects unexpectedly. For a home setup with Chirp, you almost never need to think about these. Zigbee2MQTT picks reasonable defaults; Tasmota does too; Chirp's broker accepts what it's given.

The one detail that comes up: when Zigbee2MQTT first connects, it publishes a "bridge online" retained message. Chirp's connector will see that as the first incoming traffic — that's a signal the connection is healthy, even before any device has reported.

Why use MQTT instead of something else?

MQTT is the lingua franca of the smart home for three reasons:

  • Tiny overhead. A temperature reading is a few bytes of header plus the JSON. This matters on battery-powered sensors that wake up every few minutes.

  • Loose coupling. Devices don't need to know about each other. Add a new sensor and the broker just routes its messages — no other device has to be reconfigured.

  • It already works. Zigbee2MQTT, Tasmota, ESPHome, Theengs, OpenMQTTGateway, and dozens of other projects all speak MQTT. Most off-the-shelf "smart home compatible" hardware can be made to publish MQTT with a small bridge.

When you're ready, continue to Cloud MQTT to set up your broker connection.

Last updated