Don’t forget that the first post in a community guide is a wiki - feel free to add to it or correct it.
This guide was written with reference to:
Core 2023.12.3
Supervisor 2023.11.6
Operating System 11.2
Frontend 20231208.2
Some subjects come up quite a lot...
That map
The ZHA “network visualisation” was originally a dashboard card. It was absorbed into ZHA and the card is now deprecated, but the repository is still on Github.
The lines on the map show every route between nodes that Zigbee has discovered - not just the ones it is using. They are colour coded according to their LQI:
- Green >192
- Yellow 129-192
- Red 80-128
- Grey < 80
The map is a snapshot. It will be different each time you generate it.
There are two numbers on each link because messages pass in both directions. A value is supplied by the router at each end of the hop.
It is normal to see nodes on the map that don’t have a link to anything else. These are usually end devices and they’re probably sleeping to conserve battery. They will wake immediately if one of their sensors is triggered, and in any event they should wake periodically to check in with their parent router. A router with no connections is unavailable, which may indicate a problem.
LQI Values
We talk about link quality rather loosely. Strictly speaking LQI is a measure of error rates. An LQI of 255 means that no messages have been lost between two nodes, and in theory this is possible even if signal strength (RSSI) is not great.
Each router in a network maintains a table of information about its neighbours so that it can direct messages efficiently. It tracks the LQI of incoming links and the number we see is the average for recent messages.
Can I control the route my messages take?
No.
If you watch the videos in this post you’ll see that even the standard’s developers talk about Zigbee as a black box that “just works” - and it does, providing your network has enough routers and not too much interference.
When a message passes from the coordinator to a device at the other end of the house each router along the way will make a decision about how to forward it and the outcome will be different each time, depending on traffic and the number of other routers in range. If you don’t have enough routers messages will be forced along the same path and that’s when you get problems.
When you pair an end device with the network you can do it through a nearby router rather than the coordinator - sometimes this is easier. Devices from some manufacturers tend to “stick” with the original router they were paired through, but they shouldn’t - if it becomes unavailable they will fail. If a parent router fails, its children should connect elsewhere and inform the rest of the network of the fact.
Interference
Zigbee only has a weak signal which is easily swamped by wi-fi if you or your neighbours are using the same channel. Before you embark on major surgery, however, bear in mind that Zigbee channel numbers and wi-fi channel numbers are not the same.
Ironically, Channel 11 Zigbee and Channel 11 wi-fi are a good combination, at opposite ends of the 2.4 GHz spectrum.
There’s a post about this here.
What's the difference between ZHA and Z2M?
Zigbee Home Automation is Home Assistant’s built in Zigbee integration. If you buy a SkyConnect coordinator, it will be installed by default; with a different coordinator installation and device discovery is very simple through the GUI. If a Zigbee device is standards compliant it will work with ZHA out of the box. In practice this is less common than you might think and many devices need custom device handlers, or quirks. More details here.
Zigbee2MQTT is an open source gateway application for controlling Zigbee networks - in other words, it performs the same function as (say) a Philips Hue bridge but it is not restricted to any particular manufacurer’s devices. It works well with HA, but also with other smart home systems. If you wish you can run it on a machine separate from your HA server - which means your lights will still work while HA is being restarted. As the name suggests, it needs a MQTT broker, which makes it more complicated to set up and maintain than ZHA, however Z2M supports more non-compliant devices. More details here.
These are the two main Zigbee integrations, and with either of them you will be able to mix devices from different manufacturers. Which one you use is a matter of personal preference (some people use both, but they need separate coordinators and a device can’t be on both networks at the same time). Both are equally stable. Whichever one you choose, the Zigbee protocol is the same.
Where do I find ZHA quirks?
There’s a list here, sorted by manufacturer:
It’s a good idea to look up your device on the issues page before you download anything - some have several variants.
Can I use a Zigbee integration in HA and run a hub by [insert manufacturer's name here] at the same time?
Yes, if you must. But devices can’t be on both networks.
How can I find out which devices work well?
Search the forum. Ask.
There is a useful database here.
If you’re using Z2M, there’s a catalogue of supported devices here. With pictures! If you’re using ZHA, compliant devices should all work, so you need to look for warnings about buggy ones that don’t. The GitHub issues list is a good place to start.
I've just restarted HA and lots of my devices are unavailable
This is normal for end devices, which may have been sleeping, and it can sometimes take a long time for all of them to report in.
Bear in mind that “reporting in” takes place in stages. A device may poll its parent every few seconds to see whether there are any buffered messages, but it may only update link values every five minutes and battery status every couple of hours. All this is part of the device designer’s strategy to conserve battery and it will vary from device to device. If a sensor is triggered the device should update immediately.
I have lots of devices but Zigbee is still unstable
OK. But what kind of devices? Routers do the heavy lifting in a Zigbee network; end devices are just along for the ride. Best practice is to build a solid network of mains-powered routers first (bearing in mind that not all mains-powered devices are routers) and add the fun stuff afterwards.