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:
Home Assistant 2023.9.3
Supervisor 2023.10.0
Operating System 10.5
Frontend 20230911.0 - latest
Thanks to:
zigpy project’s ZHA Device Handlers readme.
Silicon Labs Zigbee knowledge base.
HA docs. Zigbee Home Automation - Home Assistant
Zigbee is a low power radio protocol which relies on mesh networking to overcome the limitations of small, inexpensive devices. In hardware terms it usually consists of a USB radio adapter (the coordinator) plugged directly into the machine running HA, and a swarm of mains-powered lightbulbs and smart plugs relaying messages to and from battery-powered sensors and switches.
A Zigbee network is very resilient since there are many possible connections for the signal to use, and although the signal is weak it can find its way round walls and other obstructions.
But for the user, Zigbee is a bit of a “black box”. You can’t control it - routing devices are constantly re-evaluating links with their neighbours to find better connections. The best you can do is provide a rich and interference free environment - and let the mesh do its magic.
This glossary is an introduction to some of the terminology you may encounter.
Key concepts
Binding
Binding a Zigbee device like a dimmer switch to a Zigbee lightbulb or group of lightbulbs allows direct control of the target device(s), bypassing the network. This means that the switch can control the lightbulb/group of lightbulbs even when the Zigbee coordinator and Home Assistant are not available. Not all devices are capable of binding.
Child
A child device is a non-router to which traffic is directed by a nearby parent router. A battery-powered dimmer switch, for example. Sometimes also used to refer to all devices connected to the Zigbee coordinator, including routers.
Cluster
Clusters contain the attributes and commands needed to make individual functions work. Examples of functions are the ability to turn the switch on and off; energy monitoring; the option to add each switch to an group or a scene, etc.
-
in_clusters are server clusters that control the device. For example, a smart plug or light bulb would have an on_off server cluster.
-
out_clusters are client clusters. These clusters control some other device, sending commands to a server cluster. For example an On/Off remote would have an on_off client cluster and will generate cluster commands and send those to some other device.
Coordinator
The Coordinator is the central device (usually a dongle), that manages and controls the Zigbee network. It acts as a physical interface for the Zigbee wireless protocol, as well as being responsible for maintaining the Zigbee network topology and ensuring secure and efficient communication between Zigbee devices. There can only be one coordinator in a network. It can only connect directly to a limited number of devices - typically between 5 and 50 depending on the model - most connections will be via other routers.
Device
A device is a physical object that you want to join to a Zigbee network: a light bulb, a switch, a sensor etc. The host application, Zigpy in ZHA, needs to understand how to interact with the device so there are standards that define how the application and devices can communicate. A device contains endpoints and endpoints contain clusters.
EndDevice
End devices do not route network traffic. They are often battery-powered devices like motion sensors and buttons and they may sleep when not in use to conserve power. A router will act as a parent to an end device, handling all traffic, but the end device is responsible for maintaining contact with a parent. If an end device is moved it should inform the network that it has a new parent.
Endpoint
Endpoints are groupings of functionality. For example, a typical Zigbee light bulb will have a single endpoint. A multi-gang wall switch may have an endpoint for each individual switch so they can all be controlled separately. Each endpoint has several functions represented by clusters.
Group
Grouped devices (lightbulbs, for example) respond to commands as a single entity. (This is different to Home Assistant groups, where each entity responds individually.) Notice that Zigbee group requests are network-wide broadcasts that are bounced back and forth between all devices to make sure every possible group member has a chance to “hear” the message. It is not a good idea to send several in quick succession - in an automation, for example - as this risks overloading the network.
IDs
ID numbers are hexadecimal. For example, a cluster ID may appear as 0xe004 (the ID number is the last four digits - ignore the 0x). These may need to be translated into decimal for use in Home Assistant scripts. There’s a website that does it here. e004 translates to 57348.
IEEE
The device hardware address (looks like a MAC address, except that there are eight pairs).
LQI
Link quality index. In theory, an LQI value of 255 means a zero error rate. In general, a positive high LQI value is better and a lower LQI value is worse. However, LQI values can be hard to interpret because the Zigbee specifications do not standardize how to perform measurements - values can be different for different manufacturers.
Mesh
A mesh network is one where every node can connect directly with any other node and connections change in response to changing conditions. In a Zigbee network router devices make up the mesh. End devices like buttons and sensors have a single connection to their parent router - however, this may also change dynamically - if the parent becomes unavailable, for example.
Neighbour
Each router device maintains tables of information about other routers and other end devices on the network, allowing a mesh network to be created. The router table is limited - typically (but not always) to 16 devices; the child table, typically to six - these are all neighbour devices. (They are network neighbours - they may not be close to one another physically.) The whole network can be very large - if the coordinator is connected to three routers, each one of those may be connected to six end devices and 16 other routers, and so on. It does mean, however, that the number of end devices is limited by the number of routers.
OTA
Over-the-air firmware update. ZHA and Z2M can perform updates for some manufacturers, providing they publish their firmware images.
Pairing
The action of joining a device to the network. Devices may be paired through the coordinator or through a neighbouring router, but the initial link is likely to change over time. At any given moment it is difficult to tell what connections a device is using. Not the same as binding.
Parent
A parent device is a router which directs traffic to a nearby non-router child device. A lightbulb could be the parent of a battery-powered motion sensor, for example. The parent device is not necessarily the bulb the motion sensor is controlling - it could be another one nearby.
Quirk
(In ZHA) a custom device handler for a device where the manufacturer didn’t follow specs exactly. Some quirks are built-in, others can be downloaded from GitHub or you can write your own. Custom quirks not built into ZHA should be saved in a folder in HA’s config, and a line in configuration.yaml should point to that folder. For example:
zha:
custom_quirks_path: /config/custom_zha_quirks/
Router
Routers are devices responsible for moving traffic round the network. They also allow new devices to join the network. They will be mains-powered and power should always be on. (Notice, however, that not all mains-powered Zigbee devices can act as routers.) The maximum number of end devices that can be connected to router depends on the limit set by its firmware developer. Some can only route 5 devices while others can handle 50 (for most it is closer to 5).
RSSI
Received Signal Strength Indicator. RSSI values are an indicator of the raw signal strength between two devices. RSSI values are negative numbers.
- Anything at -60 and above (meaning -50, -40, etc.) should be considered a strong signal (not losing messages).
- Anything at -80 and below (meaning -85, -90, etc.) should be considered a noisy environment and you risk losing messages.
Signature
The device signature identifies the device, its manufacturer and its capabilities. Used during pairing to identify a new device, and by quirks to identify the device they should be applied to.
Sleep
Battery-powered devices may sleep to conserve power. They will normally wake periodically to check in with their parent, and of course they wake when they are activated (by movement, for example, in a motion sensor). If a battery-powered switch is being used outside the network by being bound
to a group of lights an initial button press may be needed to wake it each time it is used.
Z2M
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 and with many 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 a little more complicated to set up and maintain than ZHA, however Z2M supports more non-compliant devices than ZHA. More details here.
The main alternative to Z2M is ZHA. 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.
ZHA
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. In most cases these will be included in the latest release of the integration, but very new types of device may have missing features initially. More details here.
The main alternative to ZHA is Zigbee2MQTT (Z2M). 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.
Zigbee
The name refers to the waggle dance of honey bees after their return to the beehive. OK?
Other Zigbee guides