Should you use ZHA or Zigbee2MQTT?
How ZHA and Zigbee2MQTT differ in architecture, device support and the MQTT dependency, and how to choose and place a Zigbee coordinator.
Photo: Barry A / Unsplash
After reading this article you will be able to:
- Explain how ZHA and Zigbee2MQTT connect a Zigbee coordinator to Home Assistant
- Choose a USB or network coordinator and check that both stacks support its firmware
- Reduce interference with a USB 2.0 port, an extension cable and a sensible channel
On this page
Use ZHA when you want the simplest setup: it is built into Home Assistant, needs no other service and handles the common Zigbee devices well. Use Zigbee2MQTT when you want its device converters and its own web interface, when you want the Zigbee network to keep running independently of Home Assistant, or when other software besides Home Assistant should read the devices over MQTT. Both drive the same kinds of Zigbee coordinator, both run locally, and either is a sound choice for a home network of a few dozen devices.
The difference is architectural. ZHA is a Home Assistant integration that talks to the radio directly. Zigbee2MQTT is a separate program that talks to the radio and publishes every device to an MQTT broker, which Home Assistant then subscribes to. The table summarizes what follows from that.
| ZHA | Zigbee2MQTT | |
|---|---|---|
| Where it runs | Inside Home Assistant | Separate service: Home Assistant app, Docker or any Linux host |
| Extra services | None | An MQTT broker, such as Mosquitto |
| Non-standard devices | Quirks from ZHA Device Handlers | Converters from zigbee-herdsman |
| Interface | Home Assistant device pages | Own web frontend, plus Home Assistant via MQTT discovery |
| Used by other software | No | Yes, by any MQTT client |
What is a Zigbee coordinator, and which kinds are there?
Every Zigbee network has exactly one coordinator. It forms the network, hands out addresses and holds the network key; mains-powered devices then act as routers and extend the mesh. In Home Assistant the coordinator is a radio adapter plus the firmware that runs on it, and that firmware decides which software stacks can use it.
There are two physical forms. USB adapters plug into the Home Assistant machine; the project’s own Connect ZBT-2 is one, and the ZHA documentation lists tested third-party adapters built on Silicon Labs (EmberZNet), Texas Instruments (Z-Stack) and dresden elektronik (deCONZ) chips. Network coordinators put the same radio in a small box connected by Ethernet, so it can sit in the middle of the house while the server stays in a cupboard. The serial link between software and radio tolerates delays and packet loss poorly, which is why ZHA advises against running it over Wi-Fi, a WAN or a VPN, and the Zigbee2MQTT adapter guide warns that adapters connected over Wi-Fi may be less stable and suggests wired Ethernet.
The Zigbee2MQTT guide also lists its own firmware tiers: Z-Stack, EmberZNet and deCONZ adapters are recommended, ZiGate is no longer maintained and ZBOSS support is experimental. Check that the adapter you buy appears in the supported list of both projects, so that you keep the option of switching later.
How do the two stacks differ in practice?
With ZHA, pairing, renaming and removing devices happen in the normal Home Assistant interface, and a Zigbee device looks like any other device. Restarting Home Assistant restarts the Zigbee stack with it. Updates arrive with Home Assistant releases.
Zigbee2MQTT has its own frontend for pairing, a network map and device settings. It connects to Home Assistant through MQTT discovery: once the MQTT integration is set up, devices appear in Home Assistant’s device registry automatically. Because it is a separate process, you can restart Home Assistant without touching the Zigbee network, run Zigbee2MQTT on a different machine nearer the middle of the house, or feed the same devices to Node-RED or a time-series database directly.
Which one supports more devices?
Both support devices that follow the Zigbee specification. The differences appear with devices that use manufacturer-specific clusters or behave oddly. ZHA handles them with quirks, small Python handlers from the ZHA Device Handlers project, and its documentation notes that Zigbee2MQTT uses an equivalent mechanism, the zigbee-herdsman converters.
Zigbee2MQTT publishes a searchable list of supported devices, which counted 5,798 devices from 608 vendors when checked for this guide; each entry shows which features the converter exposes. ZHA does not publish an equivalent count. The community-maintained Zigbee Device Compatibility Repository reports device compatibility across ZHA, Zigbee2MQTT and other gateways. Before buying an unusual device, look it up in both places: support for the basic function is common, but extra features such as a sensitivity setting or a second relay channel may be supported by only one stack.
What does the MQTT dependency mean?
Zigbee2MQTT needs an MQTT broker; its getting started guide recommends Mosquitto. On Home Assistant OS that means two more apps (the broker and Zigbee2MQTT itself, which is installed from its own repository) and the MQTT integration. On Home Assistant Container you run both as separate containers.
That is more to configure, update and back up, and one more component that can fail. In exchange you get a clean interface: every device has topics you can read and write, which is useful for debugging and for integrating anything that speaks MQTT. If that flexibility has no use for you, ZHA’s single process is simpler to keep running.
How do you avoid interference?
Many Zigbee problems that look like software faults turn out to be radio problems, and both projects give similar advice. The ZHA documentation recommends plugging the adapter into a USB 2.0 port rather than USB 3.x, because USB 3 ports, computers and peripherals are known sources of interference, and placing it on a shielded USB extension cable away from the computer. Zigbee2MQTT’s network range guide notes that a 50 cm extension cable is already enough to reduce interference and warns against placing the adapter near USB or HDMI ports.
Zigbee shares the 2.4 GHz band with Wi-Fi. ZHA generally recommends Zigbee channels 15, 20 or 25 and advises against changing the channel once the network is built; changing it in Zigbee2MQTT may require re-pairing some devices. Keep the coordinator away from Wi-Fi access points, and add mains-powered routers (plugs, in-wall switches with a neutral wire) before blaming a sensor that drops off.
Can you switch later?
Yes, but plan it as a small project. Only one stack can use a coordinator at a time, so the switch happens all at once rather than device by device, and the devices come back into Home Assistant as new entities, so automations and dashboards that reference them need updating. Choosing an adapter supported by both projects keeps the hardware usable whichever way you go.
Where to go next
- Home Assistant explained covers installation types and why apps exist only on Home Assistant OS.
- Zigbee explained covers the mesh, routers and end devices underneath both stacks.
- MQTT explained covers the broker, topics and discovery that Zigbee2MQTT relies on.
- Choosing a smart home hub puts Home Assistant next to the commercial platforms.
Topics: Zigbee, Home Assistant, Zigbee2MQTT, ZHA, MQTT, comparison