Zha zigbee home assistant

Как использовать Zigbee Home Automation (ZHA) для Home Assistant

Все контроллеры и стики JetHome поддерживаются в системе Zigbee Home Automation.

Для подключения необходимо добавить новую интеграцию в Home Assistant. Проверьте, что zigbee адаптер не занят другим процессом (zigbee2mqtt, к примеру).

Тип устройства необходимо выбрать ZNP Texas Instruments Z-Stack

В настройках подключения необходимо правильно указать порт, где находится адаптер. Для контроллеров JetHub D1 и H1 порт для встроенного адаптера должен быть /dev/ttyAML2. Скорость подключения 115200, управление потоком данных оставить не выбранным.

При правильно выбранных настройках подключение завершится успехом.


ZHA vs Zigbee2MQTT – choosing the best system?

Published by Oliver on 25.01.2021 25.01.2021

There are two awesome tools for local control over Zigbee devices: ZHA vs Zigbee2Mqtt. Which one should you use? I recently switched from Zigbee2MQTT to ZHA. Here I will show you how to set up ZHA with Home Assistant and compare ZHA and Zigbee2MQTT.

My setup

I recently started a new smart home setup after moving into a new apartment. I had been running Zigbee2MQTT with this setup for a couple of years now with about a dozen sensors from Aqara and IKEA Tradfri lightbulbs. It has been a really good experience: quite stable with few problems, mixing devices from multiple manufacturers and good integration into my smart home controller (OpenHab at the time).

A new Zigbee bridge

So why would I switch systems? My only real complaint about my Zigbee2MQTT system was the hardware used. I ran the network using a CC2531 USB-to-Zigbee stick. This works really great for beginners. The devices is very cheap and can be ordered with the right firmware online. Unfortunately it is also not very powerful. It can’t control too many devices directly (fortunately this is not really a problem as I have a lot of repeaters in the form of lightbulbs in my network) and it has a pretty bad range.

If you run this setup in an apartment or a small house with a lot of repeaters you might not run into any problems. I tried to also set up a similar system in my parents’ house though and quickly ran into a range problem. The server running the smart home system is stored in quite a remote place with no repeaters nearby. The walls are also built from reinforced concrete so radio-waves are blocked a lot. No luck here.

  • CC2531 Zigbee USB stick (preflashed or with a debugger)
  • Sonoff Zigbee bridge (you need to flash Tasmota)
  • USB to serial 3.3V stick needed to flash Tasmota
  • Alternative: the Conbee2 stick
  • Some nice Zigbee devices like the Aqara motion sensor, the Aqara switch or the Hue ambiance adjustable white bulbs
    If you are interested in buying Zigbee devices for your smart home consider doing it via my affiliate links above. It does not change prices for you and allows me to pay for the servers 😉

Fortunately I ran across a possible solution for this range problem: a product with a better range that is not bound directly to the control server: the Sonoff Zigbee bridge. A small Wifi connected box with a Zigbee chip. The Wifi connection makes it much more flexible in regards to the position and you can flash the open source firmware Tasmota. This gives you full (local) control over the device. Awesome! It is also still quite cheap: I paid around 20€ for mine.

While it has not really changed anything for me yet, I would also like to add that the bridge supports the Zigbee 3.0 standard while the CC2531 is stuck with older versions. Zigbee version 3 is supposed to make devices for unified which might be a big plus later on.

Small update here: I have since actually switched to another controller. Now I am using the Sonoff Zigbee 3.0 USB dongle plus. It also comes with support for many devices and the modern Zigbee version but it eliminates another wireless connection. While the Wifi bridge worked great this should be even more stable. I was even able to migrate all the data without the need to re-pair my devices.

Setting up ZHA with Home Assistant

To prepare the Sonoff Zigbee bridge we need to first flash Tasmota and then update the firmware on the Zigbee chip. There is a very nice full guide on how to do this here. Here is the quick rundown:

  • open the Zigbee bridge by removing the small wire feet and removing the screws
  • set your USB to serial adapter to 3.3V and connect it to the bridge:
    • ETX to RX
    • ERX to TX
    • 3V3 to 3V3
    • GND to GND
    • IO0(GPIO Zero) to GND
  • Plug in the adapter and select it in Tasmotizer. Select tasmota-zbbridge.bin and flash. Afterwards you can also use the program to burn the config for your Wifi
  • Assemble the bridge again and connect it to a USB power adapter
  • Wait until it connects to your network (or go to the AP provided by the device) and open the console. Run this:

Now we are ready to connect the bridge to Home Assistant.

Adding ZHA to Home Assistant

In your Home Assistant instance go to integrations tab and “add integration” via the button below. Select “Zigbee Home Automation” (ZHA) from the list and install it.

Now the setup process begins. Select “Enter manually” when asked for a device path and choose “EZSP” as the device type. Afterwards you can use socket:// :8888 as the serial path and 115200 as the port speed. This will connect to your Zigbee bridge directly via TCP.

After a few seconds the setup process should be done now. If you want to you can assign a room to your bridge, afterwards you can close the setup. You should now see a new working integration in your setup.

Pairing Zigbee devices from Home Assistant

Now it is time to actually connect some Zigbee devices to your setup. Fortunately this process is super easy with ZHA. Click “CONFIGURE” and then “add device” in your ZHA integration. ZHA will now start searching for new devices. Now all you need to do is put your devices in pairing mode. This is usually done by pressing a certain button for some time. A list of compatible devices and how to pair them can be found on this website.

After a couple of seconds devices will now start showing up in the ZHA integration. Each one will have a default name. Change that name and optionally assign a room here, then continue with the next device. Once you are done just close this screen. All your Zigbee devices should now show up in Home Assistant.

I was able to join a couple of Tradfri lightbulbs, different Philips Hue lightbulbs as well as different Aqara sensors and buttons without any problem. Adding a IKEA Fyrtur blind was a little bit more complicated but also worked.

ZHA vs Zigbee2MQTT

So after using both systems, which ones is better? Which should you be using? It depends. Both systems are great, both are working very well. It depends on your use-case which system will work better for you. Here are a couple of (dis)advantages of the different systems though.

ZHA vs Zigbee2MQTT – there are advantage for both systems

What is great about Zigbee2MQTT

Zigbee2MQTT is the more independent of the two systems. You are not tied to any specific smart home system as pretty much all of them can interface with MQTT. This means you can also run it on a machine separate from your smart home server. It will also stay online while you restart your actual smart home controller, which can be a big plus with Home Assistant that needs to be restarted every time something changes in the configuration files.

It is pretty easy to set up, at least if you have a certain knowledge about technology. Check out my GitHub repository if you are looking for a ready-to-go setup. It supports a very wide range of devices and I never had any major problems with my setup.

It does not come with a graphical user interface but the Zigbee2MQTT assistant will fix that problem. Since I wrote this a graphical interface was actually added and is available by default on port 8080 of your server.

Zigbee2MQTT will also allow you to upgrade the firmware of devices from some companies like IKEA (Tradfri) and Philips (Hue) – OTA updates. Additionally you can change some of the device settings (like report frequency, etc…).

Finally it seems to be relatively easy to add support for new devices, although I never had to do that.

What is not so great about Zigbee2MQTT

Zigbee2MQTT has been working very well for me. Of the two systems it is the slightly more complex one though. While the setup was not very hard it requires additional software (a MQTT broker) and some technical skills.

Although the configuration via the text file is pretty simple, and makes it easy to back up your settings, some changes like renaming a device require editing of said file and a restart. That can be quite annoying. A fully integrated GUI like ZHA included in Home Assistant makes all of this much easier.

Pairing of devices also sometimes took quite a while for me but did always end up working. Most likely this is a fault of the network though, not the software.

For me the biggest drawback of Zigbee2MQTT is something that is not actually part of the software: the hardware. The CC2531 stick is used in most cases and while it is cheap and works, its range and capacity are very limited. While the project does support a wider range of adapters now, as far as I can see they are all supposed to be directly connected to your server. Some of them, while being very powerful, are also more expensive.

Actually Zigbee2MQTT does support the Wifi bridge now. It is still recommended to use a directly connected controller though to avoid another error source. It also seems like new hardware gets added to ZHA quicker but that might change from case to case.

What is great about ZHA

ZHA is a newer alternative to Zigbee2MQTT and does a couple of things differently. The great integration into Home Assistant makes installation and device discovery really really simple. No text configuration needed in most cases, just the GUI.

While the list of supported devices is a little bit smaller than Zigbee2MQTT’s it is still very likely to support everything you want to use. I certainly had no problems in that regard. Ikea Tradfri, Philips Hue and all the Aqara devices just worked.

Adding new devices and groups as well as seeing a map of your network right there in Home Assistant is just great and an awesome user experience.

Maybe my biggest reason for using ZHA was the support for the Sonoff Zigbee bridge. A cheap device, with custom locally controlled firmware that can be placed anywhere (has since been added to Z2MQTT too). Being able to switch controllers without repairing was great too and might be properly integrated into Home Assistant soon.

What is not so great about ZHA

The tight integration into Home Assistant, while being a great user experience, is also the biggest drawback of ZHA. As far as I know you simply can not use it with another system. It also means restarting Home Assistant, which unfortunately you still need to do to update certain things, will also make your Zigbee devices unavailable for some time.

While ZHA offer support for OTA firmware updates (something Z2MQTT does well) it is a bit more complicated to use.

It does include a network map and Home Assistant as a general interface but just for managing your Zigbee devices I actually prefer the UI of Zigbee2MQTT assistant. The assistant does feature a better network map than ZHA im my opinion, has nice labels and supports more firmware upgrades.

Which system should you use?

So – ZHA vs Zigbee2MQTT – which system should you use? As I said it depends.

If you are not using Home Assistant or if you need to run the smart home controller and the Zigbee control software separately, the choice is simple: use Zigbee2MQTT.

If you are using some more rare device it might also be a good idea to check the list of supported devices and go with the system that supports yours.

If, on the other hand, you are using Home Assistant and are looking for a system that is easy to set up without additional software then go with ZHA! The UI integration is well done and the support for a Wifi – Zigbee bridge like the Sonoff bridge can be really really helpful. The rest of the controls are nearly as powerful as Zigbee2MQTT. In my opinion this is the best choice for beginners.

Overall I have to say both systems are great. Both have not been hard to set up and have worked very reliable for me (although I have seen people claim otherwise for both systems). In any case I really recommend going with this open source approach instead of buying and operating a bunch of different gateways. At least if you are enthusiastic about tech and have some time at hand. Integration of most devices is really smooth, you can combine the best & cheapest devices from many companies and YOU take full control over all of it.


Zigbee Home Automation

The ZHA (Zigbee Home Automation) integration allows you to connect many off-the-shelf Zigbee based devices directly to Home Assistant, using one of the many available Zigbee coordinators.

ZHA uses an open-source Python library implementing a hardware-independent Zigbee stack called zigpy. All coordinators compatible with zigpy can be used with ZHA.

There is currently support for the following device types within Home Assistant:

  • Alarm Control Panel
  • Binary Sensor
  • Button
  • Climate (beta)
  • Cover
  • Fan
  • Light
  • Lock
  • Number (i.e. analog output)
  • Select
  • Sensor
  • Siren
  • Switch

There is also support for grouping of lights, switches, and fans (i.e. support for commanding device groups as entities). At least two entities must be added to a group before the group entity is created. As well as support for binding/unbinding (i.e. bind a remote to a lightbulb or group).

Compatible hardware

ZHA integration uses a hardware independent Zigbee stack implementation with modular design, which means that it can support any one of the many Zigbee coordinator radio modules/adapters available from different manufacturers, as long as that module/adapter is compatible with zigpy.

Note! Zigbee 3.0 support or not in zigpy, depends primarily on your Zigbee coordinator hardware and its firmware. Some Zigbee coordinator hardware supports Zigbee 3.0 but might be shipped with an older firmware which does not. In such a case you may want to upgrade the firmware manually yourself.

Some other Zigbee coordinator hardware may not support a firmware that is capable of Zigbee 3.0 at all but can still be fully functional and feature-complete for your needs. This is very common as many, if not most, Zigbee devices do not yet Zigbee 3.0. As a general rule, newer Zigbee coordinator hardware generally supports Zigbee 3.0 firmware and it is up to its manufacturer to make such firmware available for them.

Known working Zigbee radio modules

  • dresden elektronik deCONZ based Zigbee radios (via the zigpy-deconz library for zigpy)
    • ConBee II (a.k.a. ConBee 2) USB adapter from dresden elektronik
    • ConBee USB adapter from dresden elektronik
    • RaspBee II (a.k.a. RaspBee 2) Raspberry Pi Shield from dresden elektronik
    • RaspBee Raspberry Pi Shield from dresden elektronik
  • Silicon Labs EmberZNet based radios using the EZSP protocol (via the bellows library for zigpy)
    • ITead SONOFF Zigbee 3.0 USB Dongle Plus Model “ZBDongle-E” (EFR32MG21 variant)
    • ITead Sonoff ZBBridge (Note! WiFi-based bridges are not recommended for ZHA with EZSP radios. Also, this first have to be flashed with Tasmota firmware and Silabs EmberZNet NCP EZSP UART Host firmware to use as Serial-to-IP adapter)
    • Nortek GoControl QuickStick Combo Model HUSBZB-1 (Z-Wave & Zigbee Ember 3581 USB Adapter) (Note! Not a must but recommend upgrade the EmberZNet NCP application firmware)
    • Elelabs Zigbee USB Adapter/POPP ZB-Stick (Note! Not a must but recommend upgrade the EmberZNet NCP application firmware)
    • Elelabs Zigbee Raspberry Pi Shield (Note! Not a must but recommend upgrade the EmberZNet NCP application firmware)
    • Bitron Video/Smabit BV AV2010/10 USB-Stick with Silicon Labs Ember 3587
    • Telegesis ETRX357USB/ETRX357USB-LR/ETRX357USB-LRS+8M (Note! These first have to be flashed with other EmberZNet firmware)
  • Texas Instruments based radios (via the zigpy-znp library for zigpy)
    • CC2652P/CC2652R/CC2652RB USB stick, module, or dev board hardware flashed with Z-Stack coordinator firmware
    • CC1352P/CC1352R USB stick, module, or dev board hardware flashed with Z-Stack coordinator firmware
    • CC2538 USB stick, module, or dev board hardware flashed with Z-Stack coordinator firmware (no longer recommended as only got deprecated old end-of-life firmware)
    • CC2530/CC2531 USB stick, module, or dev board hardware flashed with Z-Stack coordinator firmware (no longer recommended as uses deprecated hardware and very old end-of-life firmware, plus will not work properly at all if the whole Zigbee network has more than 15-20 devices)
  • Digi XBee Zigbee based radios (via the zigpy-xbee library for zigpy)
    • Digi XBee Series 3 (xbee3-24) and Digi XBee Series S2C modules
      • Note! While not a must, it is recommend to upgrade XBee Series 3 and S2C to newest firmware using XCTU
    • Digi XBee Series 2 (S2) modules (Note! This first have to be flashed with Zigbee Coordinator API firmware)
  • ZiGate based radios (via the zigpy-zigate library for zigpy and require firmware 3.1d or later)
    • ZiGate USB
    • ZiGate USB-DIN
    • PiZiGate (ZiGate Raspberry Pi module)
    • ZiGate-Ethernet (Ethernet gateway board for PiZiGate)
    • ZiGate + WiFi Pack

Warning about Wi-Fi-based Zigbee-to-Serial bridges/gateways

The EZSP protocol requires a stable connection to the serial port. With ITEAD Sonoff ZBBridge connecting over the WiFi network it is expected to see NCP entered failed state. Requesting APP controller restart in the logs. This is a normal part of the operation and indicates there was a drop in communication between ZHA and Sonoff bridge.

Configuration — GUI

Connect your radio module and restart Home Assistant.

From the Home Assistant front page go to Configuration and then select Integrations from the list.

Use the plus button in the bottom right to add a new integration called ZHA.

  • Serial Device Path — List of detected serial ports on the system. You need to pick one to which your radio is connected
  • Submit

Press Submit and the integration will try to detect radio type automatically. If unsuccessful, you will get a new pop-up asking for a radio type. In the pop-up:

  • Radio Type
Radio Type Zigbee Radio Hardware
ezsp Silicon Labs EmberZNet protocol (e.g., Elelabs, HUSBZB-1, Telegesis)
deconz dresden elektronik deCONZ protocol (e.g., ConBee I/II, RaspBee I/II)
znp Texas Instruments (e.g., CC253x, CC26x2, CC13x2)
zigate ZiGate Serial protocol (e.g., ZiGate USB-TTL, PiZiGate, ZiGate WiFi)
xbee Digi XBee ZB Coordinator Firmware protocol (e.g., Digi XBee Series 2, 2C, 3)
  • Submit

Press Submit to save radio type and you will get a new form asking for port settings specific for this radio type. In the pop-up:

  • Serial device path
  • port speed (not applicable for all radios)
  • data flow control (not applicable for all radios)

Most devices need at the very least the serial device path, like /dev/ttyUSB0 , but it is recommended to use device path from /dev/serial/by-id folder, e.g., /dev/serial/by-id/usb-Silicon_Labs_HubZ_Smart_Home_Controller_C0F003D3-if01-port0
A list of available device paths can be found in Settings > System > HArdware > dot menu > All Hardware.

Press Submit . The success dialog will appear or an error will be displayed in the popup. An error is likely if Home Assistant can’t access the USB device or your device is not up to date. Refer to Troubleshooting below for more information.

ZiGate or Sonoff ZBBridge Devices

If you are use ZiGate or Sonoff ZBBridge you have to use some special usb_path configuration:

  • ZiGate USB TTL or DIN: /dev/ttyUSB0 or auto to auto discover the zigate
  • PiZigate : pizigate:/dev/ttyS0
  • Wifi Zigate : socket://[IP]:[PORT] for example socket://
  • Sonoff ZBBridge : socket://[IP]:[PORT] for example socket://

Discovery via USB or Zeroconf

Some devices can be auto-discovered, which can simplify the ZHA setup process. The following devices have been tested with discovery and offer a quick setup experience:

Device Discovery Method Identifier
ITead SONOFF Zigbee 3.0 USB Dongle Plus V2 Model “ZBDongle-E” (EFR32MG21 variant) USB 1A86:55D4
ITead SONOFF Zigbee 3.0 USB Dongle Plus Model “ZBDongle-P” (CC2652P variant) USB 10C4:EA60
Bitron Video/SMaBiT BV AV2010/10 USB 10C4:8B34
ConBee II USB 1CF1:0030
Nortek HUSBZB-1 USB 10C4:8A2A
slae.sh CC2652RB development stick USB 10C4:EA60
ZigStar Stick (CC2652 + CH340B variant) USB 1A86:7523
Tube’s EFR32 Pro Ethernet/Serial Coordinator USB 10C4:EA60
ZigStar Coordinators USB 1A86:7523
ZigStar LAN/POE Coordinators Zeroconf zigstargw.local.
Tube’s CC2652P2 USB-powered Zigbee to Ethernet Serial Coordinator) Zeroconf tube_zb_gw_cc2652p2.local.
Tube’s CC2652P2 PoE-powered Zigbee to Ethernet Serial Coordinator) Zeroconf tube_zb_gw_cc2652p2_poe.local.
Tube’s EFR32 Based Zigbee to Ethernet Serial Coordinator) Zeroconf tube_zb_gw_efr32.local.

Additional devices in the Known working Zigbee radio modules list may be discoverable, however, only devices that have been confirmed discoverable are listed above.

Configuration — YAML

For more advanced configuration, you can modify configuration.yaml and restart Home Assistant

Configuration Variables

Full path to the database which will keep persistent network data.

Enable quirks mode for devices where manufacturers didn’t follow specs.

Full path to a directory containing custom quirk modules that will take precedence over any built-in quirks matching a device.

OTA firmware updates

ZHA component has the ability to automatically download and perform OTA (Over-The-Air) firmware updates of Zigbee devices if the OTA firmware provider source URL for updates is available. OTA firmware updating is set to disabled ( false ) in the configuration by default.

Online OTA providers for firmware updates are currently only available for IKEA, LEDVANCE/OSRAM, SALUS/Computime, and INOVELLI devices. Support for OTA updates from other manufacturers could be supported in the future if they publish their firmware images publicly.

To enable OTA firmware updates for the ZHA integration you need to add the following configuration to your configuration.yaml and restart Home Assistant:

You can choose if the IKEA, LEDVANCE, SALUS, or INOVELLI provider should be set to enabled ( true ) or disabled ( false ) individually. After the OTA firmware upgrades are finished, you can set these to false again if you do not want ZHA to automatically download and perform OTA firmware upgrades in the future.

Note that the otau_directory setting is optional and can be used for any firmware files you have downloaded yourself, for any device type and manufacturer. For example, Philips Hue firmwares manually downloaded from here and/or here added to the otau_directory can be flashed, although a manual zha.issue_zigbee_cluster_command command currently (as of 2021.3.3) must be issued against the IEEE of the Philips Hue device under Developer Tools->Services, e.g.:

Note: cluster_id: 25 may also be cluster_id: 0x0019 . The two are synonymous.

Defining Zigbee channel to use

ZHA prefers to use Zigbee channel 15 by default. You can change this using YAML configuration, but this only works if there’s no existing network. To change the channel for an existing network, radio has to be factory reset and a new network to be formed. This requires re-pairing of all the devices.

This is a good reference for channel selection for Zigbee and WiFi coexistance.

The Zigbee specification standards divide the 2.4Ghz ISM radio band into 16 Zigbee channels (i.e. distinct radio frequencies for Zigbee). For all Zigbee devices to be able to communicate, they must support the same Zigbee channel (i.e. Zigbee radio frequency) that is set on the Zigbee Coordinator as the channel to use for its Zigbee network. Not all Zigbee devices support all Zigbee channels, it will usually depend on the hardware and firmware age as well as devices power ratings.

The general recommendation is to only use channels 15, 20, or 25 in order to avoid interoperability problems with Zigbee devices that are limited to only being compatible with the ZLL (Zigbee Light Link) channels as well as lessen the chance of Wi-Fi networks interfering too much with the Zigbee network. Note that especially using Zigbee channels 11, 24, 25, or 26 on your Zigbee Coordinator could mean it will probably not be accessible to older devices as those Zigbee channels are commonly only supported by relatively modern Zigbee hardware devices with newer Zigbee firmware.

Regardless, note that the best practice recommendation is, however, not to change the Zigbee channel from default as not all Zigbee devices support all channels. If you have issues with overlapping frequencies, then it will generally be a better idea to just change Wi-Fi channels on your Wi-Fi Router or all your Wi-Fi Access Points instead.

Modifying the device type

As not all device manufacturers follow the Zigbee standard, at times a device can be incorrectly classified. For example, a switch could be classified as a light.

To correct the device type, also called domain, add the following to your configuration.yaml and restart Home Assistant:

is the device hardware address which can be read from the Home Assistant UI when looking at Device info. From device info, you can find the by viewing the Zigbee device signature.


Service zha.permit

To add new devices to the network, call the permit service on the zha domain. Do this by clicking the Service icon in Developer tools and typing zha.permit in the Service dropdown box. Next, follow the device instructions for adding, scanning or factory reset.

This service opens network for joining new devices.

Data Optional Description
duration yes For how long to allow new devices to join, default 60s
ieee yes allow new devices to join via an existing device

To join a new device using an install code (ZB3 devices) use the following data attributes (must use parameters only from the same group:

Data Parameter Group Description
src_ieee install_code The IEEE address of the joining ZB3 device. Use with install_code
install_code install_code Install Code of the joining device. Use with src_ieee
qr_code qr_code QR code containing IEEE and Install Code of the joining ZB3 device

Currently qr_code supports QR Install Codes from:

Service zha.remove

This service removes an existing device from the network. You can find the IEEE address of the device on the device card of Zigbee devices. An example of an IEEE address data parameter format is 00:0d::6f:00:05:7d:2d:34 .

Data Optional Description
ieee no IEEE address of the device to remove

Service zha.set_lock_user_code

This service sets a lock code on a Zigbee lock.

Data Optional Description
code_slot no Which lock code slot to store the code. Ex. 1-32 will work for Kwikset 954
user_code no Code to set on the lock. Ex. Kwikset accepts numbers 4-8 digits in length

Service zha.clear_lock_user_code

This service clears a lock code from a Zigbee lock.

Data Optional Description
code_slot no Which lock code slot to clear

Service zha.enable_lock_user_code

This service enables a lock code on a Zigbee lock.

Data Optional Description
code_slot no Which lock code slot to enable

Service zha.disable_lock_user_code

This service disables a lock code on a Zigbee lock.

Data Optional Description
code_slot no Which lock code slot to disable

Adding devices

To add a new device:

  1. Go to the Integrations panel, find the Zigbee Home Automation integration that was added by the configuration steps above, and select Configure.
  2. Click on the plus button at the bottom right corner to start a scan for new devices.
  3. Reset your Zigbee devices according to the device instructions provided by the manufacturer (e.g., turn on/off lights up to 10 times, switches usually have a reset button/pin). It might take a few seconds for the devices to appear. You can click on Show logs for more verbose output.
  4. Once the device is found, it will appear on that page and will be automatically added to your devices. You can optionally change its name and add it to an area (you can change this later). You can search again to add another device, or you can go back to the list of added devices.

Best practices to avoid pairing/connection difficulties

Verify that you try to follow recommended best practices to avoid pairing and/or connection issues:

  • If possible try to pair your Zigbee devices in their intended final location, (and not pair it next to the Zigbee coordinator and then need to move it after).
    • Pairing a Zigbee device next to the Zigbee coordinator and then moving it later can result in dropped/lost connections or other issues.
      • If the device you want to add is not brand new and as such never paired before then you always have to make sure to first manually reset the device to its factory default settings before you will be able to add/pair it.
  • Some battery-operated Zigbee devices are known to have problems with pairing if they have Low battery voltage.
    • Some people have reported replacing the battery on their newly received Xiaomi/Aqara devices solved pairing issues.
  • Check that you have enough Zigbee router devices (also known as Zigbee signal repeaters or range extenders) and if you do not have any, invest and add some mains-powered devices that will work as Zigbee routers.
    • Aim to start out with mains-powered devices before adding battery-operated devices as a “weak” Zigbee network mesh (e.g., the device is too far from the Zigbee coordinator or a Zigbee router) may prevent some devices from being paired. Zigbee router devices are also needed to increase the maximum of devices that can be connected to your Zigbee mesh network.
    • Note that some Zigbee devices are not fully compatible with all brands of Zigbee router devices. Xiaomi/Aqara devices are for example known not to work with Zigbee router devices from Centralite, General Electrics, Iris, Ledvance/OSRAM, LIGHTIFY/Sylvania, Orvibo, PEQ, Securifi, and SmartThings/Samsung. Better results can usually be achieved by using mains-powered devices IKEA and Nue/3A Home or dedicated DIY routing devices based on Texas Instruments CC253x/CC26x2 and XBee Series 2/3 Zigbee radios.
  • Be patient as the pairing of some Zigbee devices may require multiple attempts and you may sometimes need to try again and again.
    • Some devices, like example those from Xiaomi/Aqara, are known to not be 100% compliant with the standard Zigbee specifications and may therefore require many paring attempts over 10-20 minutes or longer.

Using router devices

You use routers to increase the number of Zigbee devices that can be used in a network. The total number of Zigbee devices that you have on a Zigbee network depends on a few things, but you should know that Zigbee coordinator hardware and firmware only plays a larger role in Zigbee networks with a lot of devices. More important is how many directly connected devices (“direct children”) versus how many routers are connected to your Zigbee coordinator. Zigpy library which ZHA uses has an upper limit. This is 32 direct children, but if your Zigbee coordinator hardware is powerful enough then you can still have hundreds of Zigbee devices connected through routers.

Even the least powerful Zigbee coordinator hardware supported by Zigpy is CC2530/2531 and its default firmware, only supports 20 devices connected directly to the coordinator. However, by having routers in your Zigbee network, the mesh network size can be extended. You can assume that most, if not all mains/AC-powered devices, e.g., wall-plugs and always powered-on lightbulbs in your Zigbee network can serve as a router. You can even use CC2530/CC2531 with router firmware, as additional routers (which in their turn have a limit of 21 devices).

An example using the default CC2531 coordinator firmware + two CC2531 routers; Your device limit will be:

  • Coordinator: 15 devices — 2 routers = 13
  • Router one: + 21 devices
  • Router two: + 21 devices
  • Total device limit = 55 devices

Binding and unbinding

ZHA support for binding and unbinding. Binding is an action in Zigbee which defines relations between two Zigbee devices, specific endpoints, and cluster id. It provides a mechanism for attaching an endpoint on one Zigbee node to one or more endpoints on another Zigbee node or Zigbee group (a group of Zigbee devices).

Binding is a “target destination” in form of a device address or group ID, endpoint, and cluster. For example, binding a Zigbee device like a remote to a Zigbee lightbulb, switch or group of lightbulbs allows direct control of the “target” device (light, switch, shade) from the “remote” Zigbee device, bypassing ZHA. This means that the remote can control the lightbulb/group of lightbulbs even when the Zigbee coordinator is not available. Binding is only supported between the same cluster, for example, “output cluster id 6” (on/off cluster) of a remote, can be only bound to an “input cluster id 6” on the target device – light, switch.

Note that not all devices support binding as it depends on the Zigbee implementation of the device itself. Also, by default ZHA bind remotes to the coordinator, so the coordinator could receive ZCL commands from the remotes and originate zha_events. However, some remotes, for example, the Philips RWL021 can only be bound to a single destination and it is not possible to make this switch to bind to other destinations like a device or groups unless you first unbind the remote from the coordinator. After you unbind the remote from the ZHA coordinator you can then bind it directly to any other Zigbee device or a group.

Binding a remote directly to a bulb or group has the benefit of faster response time and smoother control. This greatly improves user feedback experience functions like dimming as the remote then directly dims the lightbulb and thus does not have to make the software roundtrip via the ZHA coordinator.

Zigbee backup and restore in ZHA

Zigbee Home Automation (ZHA) integration now features Zigbee network backup, restore/recovery, and migrating between Zigbee coordinators. Backups are taken automatically however, a single backup to a file for easy download can also be manually created from the configuration page under Network Settings.

After restoring a Home Assistant backup, you can re-configure ZHA and migrate to a new Zigbee Coordinator adapter without any loss of your settings or devices that were connected. This is helpful if your current radio fails or a new radio adapter type and model comes out that you may want to migrate to.

Within ZHA is possible to use this backup and restore feature to migrate between some different radio types, if the respective radio library supports it. Currently, ZHA supports migrating the Zigbee network between different Zigbee Coordinator adapters based on chips from Silicon Labs, Texas Instruments, or ConBee/RaspBee if the backup was made from inside ZHA.


To help resolve any kinks or compatibility problems, report bugs as issues with debug logs. Please follow the instructions in this troubleshooting section.

Knowing which devices are supported

There is no official compatibility list of supported devices for the simple reason that practically all devices Zigbee Home Automation that are fully compliant with the standards and specifications as set by the Zigbee Alliance should technically be compatible with this ZHA integration. The fact remains, however, that some hardware manufacturers do not always fully comply with each set specification, which can cause a few devices to only partially work or not work at all with ZHA, but developers can create workarounds for such issues via a solution for ‘ZHA exception and deviation handling’ that this implementation features. See that section for more information.

Tip to new users is that, while there is no official list of supported devices, some ZHA users take comfort that blakadder maintains an unofficial Zigbee Device Compatibility Repository which anyone can submit compatibility reports to, it can be found at zigbee.blakadder.com and currently contains independent compatibility lists and device pairing tips for several home automation gateway/bridge/hub software, including but not limited to open source Zigbee implementations such as; ZHA, Tasmota, Zigbee2MQTT, and ZiGate.

ZHA exception and deviation handling

The ZHA implementation in Home Assistant relies on a library called “ZHA Device Handlers” to resolve issues with Zigbee devices that do not fully conform with the Zigbee standards. The few devices that deviate from the Zigbee specifications set by the Zigbee Alliance may therefore require proper bug reports with debug logs from users to assistant the developers in writing custom ZHA Device Handlers for all of a device functions to work properly with the ZHA integration.

Such a custom “ZHA Device Handler” are Python scripts that internally are also referred to as a “quirk” because they fix “quirks”, like deviations from the standard specifications. ZHA Device Handles do this by transparently, acting as a translator, translating and converting non-compliant device messages and instead present them to the application as coming from a virtual compliant device. These ZHA Device Handlers for Home Assistant can thus be used to parse custom messages to and from Zigbee devices. The ZHA Device Handlers that are made can then be reused by all users in future versions of Home Assistant.

The custom quirks implementations for zigpy implemented as ZHA Device Handlers for Home Assistant are a similar concept to that of Hub-connected Device Handlers for the SmartThings Classics platform as well as that of Zigbee-Herdsman Converters (formerly Zigbee-Shepherd Converters) as used by Zigbee2mqtt, meaning they are each virtual representations of a physical device that expose additional functionality that is not provided out-of-the-box by the existing integration between these platforms.

Reporting issues

When reporting issues, please provide the following information in addition to information requested by issue template:

  1. Debug logs for the issue, see debug logging
  2. Model of Zigbee radio being used
  3. If issue is related to a specific Zigbee device, provide both “Zigbee Device Signature” and “Diagnostics” information.
  • Both the “Zigbee Device Signature” and “Diagnostics” information can be found by clicking Settings ->Devices & Services ->Zigbee Home Automation (click Configure) ->Devices (pick your device) -> Click “Zigbee Device Signature” and “Download Diagnostics” respectively.

Debug logging

To enable debug logging for ZHA component and radio libraries, add the following logger configuration to configuration.yaml :

Add Philips Hue bulbs that have previously been added to another bridge

Philips Hue bulbs/lights that have previously been paired/added to another bridge/gateway will not show up during search in ZHA to pair/add a Zigbee device. That is because you have to first manually restore your bulbs/lights back to their factory default settings first, and just removing them from your old bridge/gateway is not enough to do so. Instead to achieve a proper device factory reset you can use one of these methods below.

Using a Philips Hue Dimmer Switch or Lutron Connected Bulb Remote is probably the easiest way to factory-reset your bulbs. For this to work, the remote does not have to be paired with your previous bridge. Also, make sure there are no other Hue bulbs nearby that have just been turned on when using this method as you otherwise risk resetting them too.

Philips Hue Dimmer Switch

  1. Turn on your Hue bulb/light you want to reset. (It is important that the bulb has just been turned).
  2. Hold the Philips Hue Dimmer Switch near your bulb (closer than 10 centimeters / 4 inches).
  3. Press and hold the (I)/(ON) and (O)/(OFF) buttons on the Philips Hue Dimmer Switch. The bulb should start blinking in 10-20 seconds. The bulb will blink, then turn off, then turn on. You can now release the dimmer buttons.
  4. Your bulb is now factor reset and ready for pairing. A green light on the top left of the dimmer remote indicates that your bulb has been successfully reset to factory default settings.

Note: If you are unable to reset the bulb, remove it from the Hue Bridge and retry the procedure.

Lutron Connected Bulb Remote

  1. Turn on your Hue bulb/light you want to reset. (It is important that the bulb has just been turned).
  2. Hold the Dimmer Switch near your bulb (closer than 10 centimeters / 4 inches)
  3. Press and hold the 2nd (up arrow) and 4th (light off) buttons on the Lutron Connected Bulb Remote simultaneously for about 10 seconds continuously until your bulb starts to blink and the green LED on the remote should also start blink slowly.
  4. Continue to hold both buttons on the remote until the green LED on it stops blinking. Your bulb should also have stopped blinking and eventually turn on again indicating that your bulb has been successfully reset to factory default settings.


Follow the instructions on https://github.com/vanviegen/hue-thief/ (EZSP-based Zigbee USB stick required)

ZHA Start up issue with Home Assistant or Home Assistant Container

On Linux hosts ZHA can fail to start during HA startup or restarts because the Zigbee USB device is being claimed by the host’s modemmanager service. To fix this disable the modemmanager on the host system.

To remove modemmanager from a Debian/Ubuntu host run this command:

Can’t connect to USB device and using Docker

If you are using Docker and can’t connect, you most likely need to forward your device from the host machine to the Docker instance. This can be achieved by adding the device mapping to the end of the startup string or ideally using Docker compose.

Docker Compose

Install Docker-Compose for your platform (Linux — sudo apt-get install docker-compose ).