Intellihome
MQTT
What it is: A lightweight publish/subscribe protocol on top of TCP/IP, suitable even for low-power sensors. Clients connect to a broker, subscribe to topics and publish to them. The broker is the common interface through which everything exchanges data. Mosquitto docs HA docs In the smart home it's the bus between Zigbee2MQTT, network coordinators, Node-RED and Home Assistant.
How it works
According to Mosquitto docs:
- Topics don't need to be created; publishing is enough. They're hierarchical with
/as separator, e.g.zigbee2mqtt/living-room/light. - Subscription wildcards:
+matches one level (zigbee2mqtt/+/temperature) and#all remaining levels.#must come last (zigbee2mqtt/#). - QoS (Quality of Service):
| QoS | Delivery | When |
|---|---|---|
| 0 | at most once, no confirmation | frequent sensor values |
| 1 | at least once, with confirmation (may arrive twice) | regular commands |
| 2 | exactly once, four-step handshake | where duplicates hurt |
The subscriber chooses the maximum QoS it will receive. Higher QoS is more reliable but slower. The "When" column is Synthesis.
- Retained message: the broker keeps it and immediately sends it to every new subscriber as the "last known state".
- Will (LWT): the broker sends it when a client disconnects unexpectedly. It's used for an "offline" status.
- Clean session = false: subscriptions and QoS 1 and 2 messages survive a client disconnect.
MQTT in Home Assistant
According to HA docs:
- Running your own broker is the easiest and most private option; the Mosquitto app is recommended. HA doesn't support ActiveMQ or RabbitMQ.
- MQTT discovery is on by default. A device sends its configuration to
homeassistant/<component>/[<node_id>/]<object_id>/configand HA adds it automatically. Thehomeassistantprefix can be changed. - HA sends a birth message after starting and an LWT on disconnect. After an HA restart, MQTT entities are unavailable until discovery arrives, so devices should react to the birth message or publish discovery as retained.
- Zigbee2MQTT and SLZB network coordinators support discovery. The default base topic is
zigbee2mqtt, and each Zigbee network needs its own. SLZB-OS manual
Broker security (Mosquitto)
According to Mosquitto docs:
- Mosquitto 2.x doesn't accept anonymous clients by default (
allow_anonymous false). The exception: with no listener defined, anonymous clients are allowed, but only from the local machine. Mosquitto 1.6 and older always allowed them. - Set up users via a
password_fileor the Dynamic Security plugin. Without TLS, usernames and passwords travel in clear text. - ACLs restrict who may read or write which topics.
- Ports: 1883 for MQTT, 8883 for MQTT over TLS. SLZB-OS manual
- Synthesis: outside a trusted network (VLAN) use 8883 with TLS and always require login.
Gotchas
- On Mosquitto 2.x, devices without a username and password won't connect; that's the default behaviour. Mosquitto docs
- After changing MQTT settings in SLZB-OS, restart the Zigbee Hub. SLZB-OS manual
- Synthesis: retained messages stay in the broker even after a device is removed. Old discovery messages then create dead devices in HA. That's why MQTT devices are deleted when migrating from Z2M, see Zigbee coordinator migration.
Implementation and integrations
- Zigbee2MQTT translates between Zigbee and MQTT. Z2M docs
- SMLIGHT SLZB in Zigbee Hub mode sends data to HA over MQTT. SLZB-OS also has its own API over MQTT. SLZB-OS manual
- Home Assistant (MQTT integration) and Node-RED (MQTT in/out nodes).
Related
Sources
- Mosquitto docs: mqtt(7) and mosquitto.conf(5), i.e. the protocol and broker security.
- HA docs: the MQTT integration in HA (broker, discovery, birth and LWT).
- SLZB-OS manual: MQTT in SLZB-OS.
- Z2M docs: Zigbee2MQTT.