Zigbee2MQTT
Bridge that exposes Zigbee devices as MQTT messages, without vendor hubs or apps.
software
also known as Z2M
Knowledge about Zigbee2MQTT
- Building a healthy Zigbee mesh: routers first, then battery devicesprocedure · unverified · Zigbee coverage and capacity come from routers. Add mains-powered routers before battery devices, pair end devices where they will live or through a nearby router, and know that some end devices never switch parents.
- Choosing a Zigbee coordinator: chip families, power amplifier and backup supportrecommendation · unverified · Zigbee2MQTT recommends zStack (Texas Instruments), EmberZNet (Silicon Labs) and deCONZ adapters; ZiGate is unmaintained and ZBOSS experimental. Prefer an adapter that supports coordinator backup.
- Choosing the Zigbee channel next to Wi-Fi (and what changing it costs)guide · unverified · Zigbee and Wi-Fi share 2.4 GHz. Pick the Zigbee channel before pairing devices: Zigbee2MQTT recommends ZLL channels 11, 15, 20 or 25. Changing the channel later may require re-pairing; changing the network key requires re-pairing everything.
- Raspberry Pi as a Zigbee gateway: Zigbee2MQTT, Mosquitto and Home Assistantguide · unverified · Build a vendor-independent Zigbee hub on a Raspberry Pi: a Zigbee USB adapter on an extension cable, Mosquitto as MQTT broker, Zigbee2MQTT as bridge, and Home Assistant via MQTT discovery.
- Tuya Zigbee devices in Zigbee2MQTT and ZHA: the _TZE fingerprint and the Tuya clusterguide · unverified · Many Tuya Zigbee devices send data over a custom manuSpecificTuya cluster using data points instead of standard Zigbee clusters. Zigbee2MQTT matches them by model ID plus manufacturer name (e.g. _TZE200_...); ZHA uses quirks built with TuyaQuirkBuilder.
- Tuya Zigbee devices: same model ID, different datapointswarning · unverified · Many Tuya Zigbee devices use the manufacturer-specific manuSpecificTuya cluster with Tuya datapoints (DPs) instead of standard Zigbee clusters, and share model IDs across different hardware. Support is per manufacturerName (e.g. _TZE200_...).
- Upgrading to Zigbee2MQTT 2.0: the breaking changes that bite, and how to prepareprocedure · unverified · Zigbee2MQTT 2.0 removed permanent permit-join, the permit_join setting and several legacy Home Assistant entities and attributes, stopped defaulting the adapter to zstack, and moved external converters and extensions. Set the legacy options and serial.adapter before upgrading.
- Zigbee OTA firmware updates: slow, battery-hungry and not always an improvementprocedure · unverified · Zigbee2MQTT and ZHA can update device firmware over the air. Updates take 10–100 minutes in Zigbee2MQTT, battery devices need at least 70% charge, updates can change behavior, and downgrading is limited.
- Zigbee coordinator on a USB 3 port or next to an SSD: expect a weak, unstable networkwarning · unverified · USB 3 ports, SSDs, HDMI ports and Wi-Fi routers interfere with 2.4 GHz Zigbee. Put the coordinator on a USB extension cable, use a USB 2 port, and keep it away from these sources.
- Zigbee pairing fails or the interview never completes: what to tryprocedure · unverified · Open the network (Zigbee2MQTT permits joining for 254 s), factory-reset the device, pair closer to the coordinator or a router, keep battery devices awake during the interview, and reduce interference.
- Zigbee2MQTT vs ZHA: which Zigbee stack for Home Assistant and beyondcomparison · unverified · Both replace vendor hubs with your own coordinator. ZHA is built into Home Assistant; Zigbee2MQTT bridges devices to an MQTT broker and works with Home Assistant via MQTT discovery or with any other MQTT consumer.
Related
- alternative to (from): ZHA – Both run a Zigbee network from a coordinator; ZHA is built into Home Assistant, Zigbee2MQTT publishes to MQTT.
- alternative to: ZHA – Both run Zigbee networks without the Tuya hub.
- depends on: MQTT – Needs an MQTT broker such as Mosquitto.
- depends on: Zigbee – Talks to devices through a Zigbee adapter (coordinator).