ZHA (Zigbee Home Automation)
What it is: The native Zigbee integration in Home Assistant. It's a hardware-independent Zigbee gateway that replaces most proprietary vendor hubs and bridges. It creates one Zigbee network to which you add most Zigbee devices.1 The alternative is Zigbee2MQTT.
Key features
- Coordinator: a USB adapter (e.g. Connect ZBT-2) or a network coordinator via a TCP socket, typically
tcp://<ip>:6638.1,2 - Installation: when adding an adapter in HA, the Recommended option means installing with ZHA. ZHA is active in HA by default.3
- Groups and binding: ZHA supports Zigbee groups and direct device binding (switch โ bulb).1
- OTA updates of device firmware are on by default and show up as regular Update entities. This only works for manufacturers that publish firmware.1
- Backups: ZHA backs up the Zigbee network automatically. A manual backup is in Network Settings. After restoring an HA backup, ZHA can be reconfigured or migrated to a new coordinator without losing devices.1 The backup includes the network key and is part of HA backups.4
- Migration between adapters (Silicon Labs EZSP, Texas Instruments ZNP, deCONZ) works if the backup comes from ZHA. From Z2M or deCONZ you first migrate into ZHA via the old adapter.1,3 Procedures: Zigbee coordinator migration.
- Non-standard devices: devices that don't follow the ZCL are handled by ZHA Device Handlers ("quirks"). If a device lacks entities, try re-pairing it, then look for or request a quirk.1
Channel
- The documentation's advice: don't change the channel. If you do, the Smart option scans once and picks the best channel, preferring 15, 20 and 25.1
- Interference and channel choice versus Wi-Fi: see Zigbee.
Gotchas
- One coordinator, one network. ZHA can't handle two adapters at once, and no other application may use the coordinator. A second adapter only works with another solution (deCONZ, Z2M).1,3
- A device can only be on one Zigbee network. Devices previously paired elsewhere (Z2M, a vendor hub) must be factory-reset.1
- ZHA does not support Zigbee Green Power (ZGP).3
- When using Z2M, delete and ignore the discovered ZHA integration, otherwise they will fight over the adapter.3
- Removing the ZHA integration does not reset the adapter; the network key stays on it.4
- Pairing: mains-powered devices (routers) first, then battery ones. A weak network can prevent pairing. The main interference sources are USB 3.x ports, devices and unshielded cables.1
Integrations
- Home Assistant, Connect ZBT-2, SLZB network coordinators
Related
Sources
- Home Assistant documentation (installation, concepts, backups, MQTT, ZHA, SMLIGHT, UniFi) โ โ ZHA integration documentation.
- SLZB-OS (SMLIGHT Manuals) โ โ network coordinator via socket.
- Home Assistant Connect ZBT-2 (Nabu Casa Support) โ โ installation, migration, single instance, ZGP.
- User Documentation for Home Assistant Connect ZBT-2 (DRAFT) โ โ backups and removing the integration (draft, superseded).
Intellihome