Zigbee Home Automation (ZHA)

What it is

ZHA wirelessly links Zigbee devices to WoowTech by way of a supported piece of hardware — a Zigbee coordinator. The integration is radio-agnostic: it's built on the open-source zigpy Python library, so it can drive many different coordinator chips rather than being tied to one vendor.

Device categories it handles

ZHA can present Zigbee hardware as the following WoowTech entity domains:

• Alarm control panel
• Binary sensor
• Button
• Climate (beta)
• Cover
• Device tracker
• Fan
• Light
• Lock
• Number
• Select
• Sensor
• Siren
• Switch
• Update

How a Zigbee network is put together

• A coordinator — usually a USB dongle — is the single brain of the network. There is exactly one per network.
• Router devices, which are mains-powered, repeat traffic to stretch range and raise capacity.
• End devices, typically battery-powered, attach either straight to the coordinator or through a router.
• All of this forms a self-healing mesh.

Two hard rules to remember: a Zigbee network can hold only one coordinator, and any given Zigbee device can belong to only one network at a time.

Hardware worth buying

Silicon Labs EmberZNet (EZSP):

• WoowTech Connect ZBT-2 (EFR32MG24)
• WoowTech Connect ZBT-1 (EFR32MG21)
• WoowTech Yellow (built-in MGM210P)
• SONOFF Zigbee 3.0 USB Dongle Plus (ZBDongle-E)
• SMLIGHT SLZB-07

Texas Instruments Z-Stack:

• CC2652P / CC2652R / CC2652RB USB adapters
• CC1352P / CC1352R USB adapters

dresden elektronik deCONZ:

• ConBee III USB adapter

Getting set up

1. Plug in a compatible radio adapter and restart WoowTech.
2. Open Settings > Devices & Services.
3. Click Add Integration and choose Zigbee Home Automation.
4. Pick your radio's serial path from the list that's detected.
5. WoowTech tries to identify the radio on its own.
6. If that fails, set the radio type yourself (ezsp, deCONZ, znp, zigate, or xbee).
7. Confirm the serial device path — a /dev/serial/by-id path is the stable choice.
8. Set the port speed and flow control if your adapter needs specific values.

Global options

Tune these under Settings > Zigbee > Options:

• Identify on join — devices blink when they pair, giving you visual confirmation.
• Light transition time — the default fade length, in seconds.
• Smooth transition on power-on — avoids a color flash on older, pre-3.0 bulbs.
• Prevent slider jumping — keeps UI sliders steady during transitions.
• Assume state of group — updates group state optimistically.
• Consider mains-powered devices unavailable after — defaults to 7200 seconds.
• Consider battery-powered devices unavailable after — defaults to 21600 seconds.
• Refresh mains-powered state on startup — polls those devices after a restart.

Network information

Under Settings > Zigbee > Network information you'll find:

• The active channel (somewhere in 11–26, all in the 2.4 GHz band)
• The PAN ID (16-bit network ID)
• The Extended PAN ID (64-bit)
• The coordinator's IEEE (MAC) address
• The radio type, serial path, and baud rate

Channel choice

Best advice: leave the channel on the ZHA default rather than changing it. If you must pick, 15, 20, or 25 dodge the worst of the Wi-Fi overlap. The "Smart" option scans the band and selects what looks best automatically. After any channel change, give devices up to an hour to find the network again.

Pairing devices

1. Open Settings > Zigbee.
2. Choose Add device.
3. Factory-reset the target device following its manufacturer's steps.
4. Wait for it to show up.
5. Optionally rename it and drop it into an area.

Pairing tends to go best when interference is low, several router devices blanket the area, the device is placed near where it'll live, any prior pairing was cleared with a factory reset, and battery devices have fresh cells.

Router devices

Anything mains-powered automatically doubles as a Zigbee router (a repeater). A healthy mesh leans hard on having several of these to widen coverage and lift the device ceiling. A coordinator can talk directly to about 32 devices, but with routers in the mix the whole network can scale into the hundreds — for instance, a coordinator backed by three routers can carry roughly 77 devices total.

Forcing a device's type

Some off-spec devices come up as the wrong entity type. You can correct that in configuration.yaml:

zha:
  device_config:
    a4:c1:38:7b:2e:0f:91:cd-1:
      type: "light"

The key follows the {ieee}-{endpoint_id} form, with the IEEE address written in lowercase.

Firmware updates over the air

ZHA can push OTA firmware to devices when an update is published. Providers currently bundled in:

• IKEA
• Inovelli
• Ledvance / OSRAM
• Sonoff / iTead
• Third Reality

Updates occasionally break behavior or force you to reconfigure a device, so read up before flashing.

Battery devices want fresh cells before an OTA, and some need a manual nudge — a button press — to wake up and accept the transfer.

Zigbee groups

Bundle similar devices so one command drives them all:

1. Settings > Zigbee > Groups.
2. Choose Create group.
3. Name it.
4. Add at least two devices of the same kind.
5. Choose Create group.

Keep a group homogeneous — all lights, all switches, or all fans.

Binding

Binding sets up direct device-to-device communication that doesn't route through ZHA, which is great for a remote that should command lights even if the hub is busy:

1. Settings > Zigbee > Devices.
2. Open the source device.
3. From the three-dot menu, choose Manage Zigbee device.
4. Switch to the Bindings tab.
5. Pick a target device or group.
6. Wake any battery devices before confirming.
7. Choose Bind or Unbind.

Backups and migration

ZHA backs the network up on its own, and you can also grab a manual backup under Settings > Zigbee > Network Settings.

Migrating to a new adapter requires:

• The old adapter currently in ZHA (not deCONZ-the-app or Zigbee2MQTT).
• A radio type of ezsp, znp, or deCONZ.
• deCONZ firmware 0x26700700 or newer.

Steps:

1. Settings > Zigbee > Migrate.
2. Plug the new adapter in.
3. Choose Migrate to a new adapter.
4. Select a backup (automatic or manual).
5. Overwrite the radio IEEE address if asked to.
6. Devices rejoin within the hour.

Troubleshooting

Pairing tips

Reduce interference, give the mesh enough routers, pair devices where they'll be used, factory-reset anything previously joined elsewhere, use fresh batteries, and be patient — some devices need a couple of tries.

Beating interference

• Keep the coordinator away from USB 3.x ports and devices.
• Run it on a shielded USB extension cable.
• Place it centrally, away from walls, ceilings, and floors.
• Keep distance from Wi-Fi routers and power supplies.
• If Wi-Fi is the culprit, consider shifting the Wi-Fi channel rather than the Zigbee one.

EMI / EMF / RMI

• Use a powered USB 2.0 hub if the machine lacks a native USB 2.0 port.
• Shield noisy gear inside a metal enclosure.
• Keep clear of mains wiring and large appliances.
• Move to modern coordinator hardware with up-to-date firmware.

Device support and quirks

ZHA understands every standard Zigbee device class from the CSA spec. Devices that bend the rules may need a custom "quirk" handler from the ZHA Device Handlers project on GitHub. For crowd-sourced compatibility notes, blakadder's unofficial Zigbee Device Compatibility Repository is a good reference.

Network map

Settings > Zigbee > Show map draws the topology, including multi-hop links and signal figures (RSSI/LQI). Don't worry about missing links between two end devices — that's normal and harmless as long as those devices keep reporting state.

OTA update problems

Fresh batteries first, keep the device awake during the transfer (tap buttons repeatedly), expect roughly 10 minutes per device, and treat slow or failed updates as a sign of a weak mesh that needs more routers or better placement.

Actions

• zha.permit — opens the network so new devices can join. Parameters: duration (seconds), ieee (an existing device), install_code, qr_code.
• zha.remove — kicks a device off the network. Requires the device's IEEE address.
• Lock code actions — zha.set_lock_user_code, zha.clear_lock_user_code, zha.enable_lock_user_code, zha.disable_lock_user_code. Parameters: code_slot, plus user_code for the set action.

Limitations

• One coordinator per ZHA instance.
• One Zigbee network per coordinator.
• A device can't be on two coordinators at once.
• Zigbee Green Power (ZGP) is not supported.
• Zigbee Smart Energy (ZSE) is not supported.
• There's no UI for scanning QR codes — use the zha.permit action instead.

Special situations

Philips Hue bulbs

A bulb that was bound to a Hue Bridge must be reset before it'll join ZHA. You can reset it with:

• A Zigbee remote (a Hue Dimmer Switch or a Lutron remote)
• An Android Bluetooth app
• The Hue Thief command-line tool

To reset with a remote: power the bulb on, hold the remote about 10 cm away, then press and hold the buttons (ON and OFF together on a Hue Dimmer; the 2nd and 4th buttons on a Lutron) for roughly 10 seconds until the bulb blinks, and release.

Running inside Docker

Pass the USB stick through to the container with a device mapping:

devices:
  - /dev/ttyACM0:/dev/ttyACM0

modemmanager on Linux

ModemManager can grab the serial port and break startup. Remove it with:

sudo apt-get purge modemmanager

Where to go next

• Source: the ZHA component inside the home-assistant/core repository
• Issues: GitHub, filtered by the "integration: zha" label
• Help: the WoowTech community forum and Discord