How to Set Up and Use ZHA (Zigbee Home Automation)

What Is ZHA

ZHA (Zigbee Home Automation) is the native Zigbee integration built into Home Assistant. It runs entirely within Home Assistant with no external dependencies — no separate containers, no MQTT broker, and no additional add-ons. For installers who want a straightforward Zigbee setup with minimal moving parts, ZHA is the recommended starting point.

Initial Setup

Prerequisites

• A supported USB Zigbee coordinator connected to your Home Assistant host (directly or via a USB extension cable — at least 1 meter recommended to avoid USB 3.0 interference).
• Home Assistant Core 2024.1 or later for the best ZHA experience.

Install the Integration

1. Go to Settings → Devices & Services.
2. Your Zigbee coordinator can be auto-discovered by Home Assistant as Zigbee Home Automation (ZHA). If an instance was found, it will be shown as Discovered at the top of the page. If your Zigbee coordinator is not auto-detected, select Add Integration and search for Zigbee Home Automation, then select your coordinator from the list.
3. Choose a network channel when prompted. Channel 15, 20, or 25 are recommended because they have the least overlap with common WiFi channels 1, 6, and 11. If you are unsure, channel 15 is a safe default.
4. Select Finish. The ZHA integration is now active.

Verify the Coordinator

After setup, confirm the coordinator is healthy:

1. Go to Settings → Devices & Services → ZHA.
2. Select Configure.
3. The coordinator should show as online with its firmware version displayed.

Pairing Devices

Enter Pairing Mode

1. Go to Settings → Devices & Services → ZHA.
2. Select Add Device. This puts the coordinator into pairing mode for 60 seconds.
3. Put your Zigbee device into pairing mode according to its manual. For most devices this is a long press (5+ seconds) on the reset or pair button. New-out-of-box devices are often already in pairing mode.
4. The device should appear in the ZHA discovery list within 30 seconds. Select it to complete pairing.

Tips for Reliable Pairing

• Pair mains-powered devices first. Routers (plugs, switches, in-wall relays) should be added to the network before battery sensors. This builds out the mesh so that battery devices can find a nearby router during pairing.
• Pair at the installed location when possible. If pairing fails at the installed location, pair near the coordinator and then allow 24–48 hours for the mesh to settle after moving the device.
• One device at a time. Do not put multiple devices into pairing mode simultaneously — the coordinator can only negotiate with one device at a time.

Rename Devices and Entities

After pairing, ZHA assigns default names based on the device model. Rename them immediately to avoid confusion later:

1. Go to Settings → Devices & Services → ZHA and select the device.
2. Select the pencil icon to rename the device (e.g., “Kitchen Motion Sensor”).
3. Rename individual entities as needed (e.g., change binary_sensor.lumi_motion_abc123 to binary_sensor.kitchen_motion).

Day-to-Day Operations

Network Visualization

The network map shows how your Zigbee mesh is structured — which devices are routers, which are end devices, and how they connect.

1. Go to Settings → Devices & Services → ZHA → Configure.
2. Select Visualize the Zigbee Network.
3. The map displays:
   • Green lines: Active routes between devices.
   • Blue nodes: Router devices (mains-powered).
   • Grey nodes: End devices (battery-powered).
   • Center node: The coordinator.

Use the network map to identify coverage gaps. If a cluster of end devices connects directly to the coordinator instead of through a nearby router, adding a router device in that area will improve reliability.

Groups

Zigbee groups allow you to control multiple devices with a single command at the Zigbee protocol level, which is faster and more reliable than sending individual commands from Home Assistant.

When to use groups:

• Controlling multiple lights in the same room simultaneously.
• Creating “all off” functionality for a zone.
• Any scenario where you want instant, synchronized response from multiple devices.

How to create a group:

1. Go to Settings → Devices & Services → ZHA → Configure.
2. Select Manage Zigbee Groups.
3. Select Create Group, name it, and add member devices.
4. A new light or switch entity appears in Home Assistant representing the group.

Bindings

Bindings create direct device-to-device communication without going through Home Assistant. A common use case is binding a Zigbee button or remote directly to a Zigbee light so that the light responds even if Home Assistant is offline.

How to create a binding:

1. Go to the source device (e.g., a remote) in ZHA.
2. Select Manage Bindings (under the device’s Zigbee Device Signature section or via the Configure menu).
3. Select the target device (e.g., a light) and the cluster to bind (typically “On/Off” or “Level Control”).
4. Test by pressing the button — the light should respond directly without any automation.

OTA Firmware Updates

ZHA supports over-the-air firmware updates for devices that provide them (IKEA TRADFRI, Legrand, LEDVANCE, and others).

1. Go to the device page in ZHA.
2. If an update is available, a firmware update entity will appear or you will see an Update Firmware option.
3. OTA updates can take 30–60 minutes depending on the device. Do not power cycle the device during the update.

Coordinator Firmware Updates

Keeping the coordinator firmware up to date improves stability and device compatibility.

• SONOFF ZBDongle-P/E: Flash using the manufacturer’s tool or via the Home Assistant SkyConnect/ZBDongle firmware update flow.
• ConBee II/III: Use the deCONZ firmware update tool.
• SkyConnect / Connect ZBT-1 / ZBT-2: Update through Settings → System → Hardware → Firmware.

After updating coordinator firmware, restart the ZHA integration. Devices do not need to be re-paired — the network keys are preserved.

Backup and Migration

ZHA stores the Zigbee network configuration (network key, device list, routing tables) in Home Assistant. A standard Home Assistant backup includes the ZHA database.

To migrate to a new coordinator:

1. Take a full Home Assistant backup.
2. Shut down Home Assistant.
3. Replace the USB coordinator.
4. Start Home Assistant. ZHA will detect the new coordinator and offer to migrate the existing network.
5. If automatic migration does not appear, go to Settings → Devices & Services → ZHA → Configure → Migrate Radio and follow the prompts.