A to Zig - a Zigbee glossary

Community Guides
1

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? :roll_eyes:

Other Zigbee guides

4 Likes
2

Are you sure about that ? I was just looking at my Zigbee map, my Sonoff Zigbee 3.0 Dongle Plus has 15 active children routes passing through. My ZB-GW04 even 20. And my Sonoff ZB-Bridge 19.

3

Aren’t those co-ordinators? If so they would have up to 32 direct connections. This refers to connections from routers (lightbulbs etc) to end devices (motion sensors etc.) - on my network map (much smaller than yours!) I don’t have any router connected to more than two end devices.

4

They can be co-ordinators if flashed with coordinator firmware, but in my case they are flashed with router firmware.

1 Like
5

Interesting - so they act as network extenders? I was wondering if it was possible to do that.

6
1 Like
7

Ya. Some routers can do more than 6. For example I know my ikea routers were limited to 6. But my sylvania led strip was doing up to 20.

It was always a pain because whenever that light went offline it took down half the network. The devices loved it for some reason.

I think its dependent on the manufacturer.

8

The maximum number of devices that can be connected to Zigbee Router device depends on the limit set by its firmware developer. So some Zigbee Router devices can only route 5 devices while others can handle 50, (though for most is closer to 5). For reference see TubeZB’s Zigbee Router/Repeater → Zigbee Router/Repeater – TubesZB (while other commercial dedicated Zigbee Router products like IKEA Trådfri Signal Repeater are known route 10-20 devices).

Tip is to buy a few dedicated Zigbee Router devices or DIY your own by flashing Zigbee USB adapters with Zigbee Router firmware then powering them via USV chargers. Check out → Zigbee networks: how to avoid interference and get the best range and coverage

9

@Stiltjack Do they need to be listed in alphabetical order? Personally think that in this context describing working parts of Zigbee I would prefer a non-alphabetical glossary as believe it should rather be read as a bibliographic compilation rather than as a dictionary, with more important things at the top and related things listed after each other instead of spread out.

And btw, must write it as “Zigbee Coordinator”, not “co-ordinator” or just “coordinator”.

PS: Slightly off-topic but you might be interesting to read my open PRs for ZHA docs:

10

Good thought. I was basing this on the glossary in the HA docs, which I have always found helpful as a starting point when I’m figuring out how to do something. The problem is, what do you put at the top? And what order do the other items go in?

As an experiment I have added a “Key concepts” section at the beginning with internal links to the alphabetical list (and figuring out how to do internal links took some doing, I can tell you… :weary:). Now that I have figured it out, I thought I might add links between the various items - probably the words currently in bold. Edit: Done this.

Anything else that should go in the “Key concepts” summary?

Thanks. I’ve fixed them all (I think). :grinning:

11

Off-topic however I like to strongly recommend that everyone here try to contribute to the official ZHA integration documentation on the home-assistant.io website, it is relatively easy to edit the markup page and submit a pull request via GitHub web interface:

https://github.com/home-assistant/home-assistant.io/blob/1a6ca4c3bd7f1eea02e15274cc332cb881e95648/source/_integrations/zha.markdown

image
image943×178 13.2 KB

While making changes to a markup formatted text-file via Git/GitHub might sound daunting the learning curve is really short and it is not a great deal more difficult than editing an article on wikipedi. The only major downside it that the reviews are far and few between so can take a long time before someone will review and merge it, and it is therefore generally recommended to submit many smaller changes that are each limited to a single section: