Zigbee Home Automation integration for Home Assistant allows you to connect many off-the-shelf Zigbee based devices to Home Assistant, using one of the available Zigbee radio modules that is compatible with zigpy (an open source Python library implementing a Zigbee stack, which in turn relies on separate libraries which can each interface a with Zigbee radio module a different manufacturer).
There is currently support for the following device types within Home Assistant:
- Binary Sensor
- Climate (beta)
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.
Zigbee devices that deviate from or do not fully conform to the standard specifications set by the Zigbee Alliance may require the development of custom ZHA Device Handlers (ZHA custom quirks handler implementation) to for all their functions to work properly with the ZHA integration in Home Assistant. These ZHA Device Handlers for Home Assistant can thus be used to parse custom messages to and from Zigbee devices.
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-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.
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.
- dresden elektronik deCONZ based Zigbee radios (via the zigpy-deconz library for zigpy)
- EmberZNet based radios using the EZSP protocol (via the bellows library for zigpy)
- ITEAD Sonoff ZBBridge (Note! This first have to be flashed with Tasmota firmware and EmberZNet 6.5.x.x)
- Nortek GoControl QuickStick Combo Model HUSBZB-1 (Z-Wave & Zigbee USB Adapter)
- Elelabs Zigbee USB Adapter
- Elelabs Zigbee Raspberry Pi Shield
- Telegesis ETRX357USB (Note! This first have to be flashed with other EmberZNet firmware)
- Telegesis ETRX357USB-LRS (Note! This first have to be flashed with other EmberZNet firmware)
- Telegesis ETRX357USB-LRS+8M (Note! This first have to be flashed with other EmberZNet firmware)
- XBee Zigbee based radios (via the zigpy-xbee library for zigpy)
- Digi XBee Series 3 (xbee3-24) modules
- Digi XBee Series 2C (S2C) modules
- Digi XBee Series 2 (S2) modules (Note! This first have to be flashed with Zigbee Coordinator API firmware)
- Texas Instruments CC253x, CC26x2R, and CC13x2 based radios (via the zigpy-cc library for zigpy)
- CC2531 USB stick hardware flashed with custom Z-Stack coordinator firmware from the Zigbee2mqtt project
- CC2530 + CC2591 USB stick hardware flashed with custom Z-Stack coordinator firmware from the Zigbee2mqtt project
- CC2530 + CC2592 dev board hardware flashed with custom Z-Stack coordinator firmware from the Zigbee2mqtt project
- CC2652R dev board hardware flashed with custom Z-Stack coordinator firmware from the Zigbee2mqtt project
- CC1352P-2 dev board hardware flashed with custom Z-Stack coordinator firmware from the Zigbee2mqtt project
- CC2538 + CC2592 dev board hardware flashed with custom Z-Stack coordinator firmware from the Zigbee2mqtt project
- ZiGate based radios (via the zigpy-zigate library for zigpy and require firmware 3.1a or later)
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.
In the popup:
- Serial Device Path - List of detected serial ports on the system. You need to pick one to which your radio is connected
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|
||Silicon Labs EmberZNet protocol (ex; Elelabs, HUSBZB-1, Telegesis)|
||dresden elektronik deCONZ protocol: ConBee I/II, RaspBee I/II|
||Texas Instruments Z-Stack ZNP protocol (ex: CC253x, CC26x2, CC13x2)|
||ZiGate Serial protocol: PiZiGate, ZiGate USB-TTL, ZiGate WiFi|
||Digi XBee ZB Coordinator Firmware protocol (Digi XBee Series 2, 2C, 3)|
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 very least the serial device path, like
/dev/ttyUSB0, but it is recommended to use
device path from
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.
If you are use ZiGate or Sonoff ZBBridge you have to use some special usb_path configuration:
- ZiGate USB TTL or DIN:
autoto auto discover the zigate
- PiZigate :
- Wifi Zigate :
- Sonoff ZBBridge :
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.
ZHA component does have 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.
Currently, OTA providers for firmware updates are only available for IKEA and LEDVANCE devices. OTA updates for device of other manufactures could possible also be supported by ZHA dependencies in the future, if these manufacturers publish their firmware 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:
zha: zigpy_config: ota: ikea_provider: true # Auto update Trådfri devices ledvance_provider: true # Auto update LEDVANCE devices #otau_directory: /path/to/your/ota/folder # Utilize .ota files to update everything else
You can choose if the IKEA or LEDVANCE 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.
To add a new device:
- Go to the Integrations page, find the Zigbee Home Automation integration that was added by the configuration steps above, and select Configure.
- Click on the plus button at the bottom right corner to start a scan for new devices.
- 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.
- 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.
When reporting issues, please provide the following information in addition to information requested by issue template:
- Debug logs for the issue, see debug logging
- Model of Zigbee radio being used
- If issue is related to a specific Zigbee device, provide device Zigbee signature. Signature is available at Configuration -> Integrations -> Zigbee Home Automation (click Configure) -> Devices (pick your device) -> Zigbee Device Signature
To enable debug logging for ZHA component ard radio libraries, add the following logger configuration to
logger: default: info logs: homeassistant.core: debug homeassistant.components.zha: debug bellows.zigbee.application: debug bellows.ezsp: debug zigpy: debug zigpy_cc: debug zigpy_deconz.zigbee.application: debug zigpy_deconz.api: debug zigpy_xbee.zigbee.application: debug zigpy_xbee.api: debug zigpy_zigate: debug zhaquirks: debug
Philips Hue bulbs that have previously been added to another bridge won’t show up during search. You have to restore your bulbs back to factory settings first. To achieve this, you basically have the following options.
Using a Philips Hue Dimmer Switch is probably the easiest way to factory-reset your bulbs. For this to work, the remote doesn’t have to be paired with your previous bridge.
- Turn on your Hue bulb you want to reset
- Hold the Dimmer Switch near your bulb (< 10 cm)
- Press and hold the (I)/(ON) and (O)/(OFF) buttons of the Dimmer Switch for about 10 seconds until your bulb starts to blink
- Your bulb should stop blinking and eventually turning on again. At the same time, a green light on the top left of your remote indicates that your bulb has been successfully reset to factory settings.
Follow the instructions on https://github.com/vanviegen/hue-thief/ (EZSP-based Zigbee USB stick required)
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 modemmanger on the host system.
To remove modemmanager from an Debian/Ubuntu host run this command:
sudo apt-get purge modemmanager
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.
Install Docker-Compose for your platform (Linux -
sudo apt-get install docker-compose).
docker-compose.yml with the following data:
version: '2' services: homeassistant: # customisable name container_name: home-assistant # must be image for your platform, this is the rpi3 variant image: homeassistant/raspberrypi3-homeassistant volumes: - <DIRECTORY HOLDING HOME ASSISTANT CONFIG FILES>:/config - /etc/localtime:/etc/localtime:ro devices: # your usb device forwarding to the docker image - /dev/ttyUSB0:/dev/ttyUSB0 restart: always network_mode: host