Zigbee is the reason a door sensor runs for two years on a single coin cell. It’s a radio protocol built for tiny messages and very little power — the opposite of Wi-Fi, which drains a battery sensor in weeks.
Zigbee2MQTT lets you run your own Zigbee network independent of any brand. An IKEA bulb, an Aqara sensor and a Philips switch all sit on one network, without three bridges and three apps.
Budget two hours. The software is the easy part; the radio side is where it goes wrong.
Choose a coordinator
The coordinator is the USB stick that runs your Zigbee network. Your choice determines how many devices you can attach and how stable the whole thing is.
| Stick | Chip | Notes |
|---|---|---|
| SONOFF ZBDongle-E | EFR32MG21 | Good value, widely supported |
| ConBee III | EFR32MG21 | Excellent reception, costs a bit more |
| Home Assistant Connect ZBT-1 | EFR32MG21 | Official, also does Thread/Matter |
Avoid the older CC2531 stick you still see second-hand. It tops out around twenty devices and then falls over — a few euros more buys something that runs a whole house.
Watch the variant too: the SONOFF ZBDongle-P and ZBDongle-E are different chips with different firmware. Both work, but instructions you find online often apply to only one of them.
Connect it with an extension cable
This step looks unnecessary and isn’t. Do not plug the coordinator directly into your Raspberry Pi or NAS.
USB 3.0 ports, and the SSDs attached to them, emit broadband noise around 2.4 GHz — exactly the band Zigbee uses. A coordinator sitting next to that loses half its range. The result is a network that works “sometimes”: sensors dropping off at random, devices refusing to pair, a mesh that looks fine in the map and doesn’t respond in practice.
A 50 cm to 1 m USB 2.0 extension cable fixes it. Hang the stick in free air, away from the case, away from your router, away from the meter cupboard.
This is by far the most common cause of “Zigbee doesn’t work properly for me”.
Install the MQTT broker
Zigbee2MQTT doesn’t talk to Home Assistant directly; it publishes messages over MQTT. So you need a broker.
- In Home Assistant, go to Settings → Add-ons → Add-on store.
- Find Mosquitto broker and install it.
- Start the add-on and enable Start on boot.
- Go to Settings → Devices & services. Home Assistant discovers MQTT itself and offers to configure it — accept.
Also create a separate Home Assistant user account for Zigbee2MQTT (Settings → People → Users) with its own password, so you’re not putting your own credentials in a config file.
Install and configure Zigbee2MQTT
The add-on isn’t in the store by default; you add the repository first.
- Settings → Add-ons → Add-on store → top-right menu → Repositories.
- Add:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt - Install Zigbee2MQTT from the list that appears.
- Open the add-on’s Configuration tab and set the serial path for your stick. You’ll find the name under Settings → System → Hardware → All hardware. Use the
/dev/serial/by-id/...path, not/dev/ttyUSB0— the latter can change number after a reboot, at which point your whole network appears to have vanished.
Start the add-on and open the log. If all is well, you’ll see the coordinator recognised and the network start.
Pick a channel clear of your Wi-Fi
Zigbee and 2.4 GHz Wi-Fi share a band. A Zigbee channel is 2 MHz wide; a Wi-Fi channel is 20 MHz — so your Wi-Fi steamrollers several Zigbee channels at once.
If your Wi-Fi is on the usual channels 1, 6 and 11, Zigbee channels 15, 20 and 25 stay clear. If your Wi-Fi is elsewhere, work it out with our Zigbee/Wi-Fi channel planner — it computes the actual overlap in MHz rather than repeating the rule of thumb.
Set the channel before you pair any devices. Changing it later means battery devices lose the network and have to be re-paired one by one.
In the add-on configuration, under advanced:
advanced:
channel: 20Restart the add-on afterwards.
Pair your first devices
Open the Zigbee2MQTT web interface (OPEN WEB UI on the add-on) and click Permit join. Set a time limit rather than leaving it permanently open — a network that always accepts joins will also accept your neighbour’s devices.
Then put the device into pairing mode. This varies by brand: usually holding a button for five to ten seconds, sometimes a reset pin, sometimes power-cycling a bulb six times.
Pair the device where it’s going to live, not next to the coordinator. Zigbee remembers the route a message takes; pairing at the final location gets you the right route immediately.
Build out the mesh
This is what makes Zigbee strong, and what most people never use.
Every mains-powered device — a smart plug, a bulb, an in-wall module — is also a router: it relays messages for other devices. Battery devices don’t; they sleep to save power.
In practice that means:
- A house with only battery sensors has no mesh. Everything has to reach the coordinator directly, and that fails through two walls.
- A handful of smart plugs spread around the house is the difference between a network that wobbles and one that heals itself. They don’t need to switch anything; being plugged in is enough.
- Reckon on one router per floor, plus one near thick walls or underfloor heating mesh.
The web interface’s Map tab shows how the network actually routes. See sensors hanging off the coordinator on a long, weak link? Put a router in between.
Zigbee rebuilds its routes slowly — give it a day after a change before drawing conclusions.
Common mistakes
“Devices drop off at random.” Almost always interference. Check in this order: extension cable in use, away from USB 3.0 and the router, channel clear of your Wi-Fi, enough routers.
“I changed the channel and now nothing works.” Battery devices don’t follow a channel change. They need re-pairing. Hence: channel first.
“After a reboot my whole network is gone.” Your stick got a different /dev/ttyUSB number. Use the /dev/serial/by-id/ path.
“My new device isn’t recognised.” Zigbee2MQTT knows thousands of devices, but new models lag. Check the supported devices list and update the add-on — it grows with every release.