Pairing Zigbee Devices

Use this guide after completing the Zigbee Protocol Setup . Your coordinator should be connected and your chosen integration (ZHA or Zigbee2MQTT) should be installed and showing the coordinator as online.

Before You Start

Confirm the following before pairing devices:

1. The Zigbee coordinator is connected and detected by Home Assistant.
2. Your chosen integration (ZHA or Zigbee2MQTT) is installed, configured, and showing the coordinator as online.
3. You have the device manuals or pairing instructions available.

Mesh-Building Strategy

Build your Zigbee mesh outward from the coordinator. The order you pair devices matters for network reliability.

1. Start with mains-powered routing devices — plugs, switches, in-wall relays. These act as Zigbee routers and extend the mesh.
2. Add battery-powered sensors last — motion sensors, door/window sensors, temperature sensors. These are Zigbee end devices that connect through the nearest router.

Pairing routers first ensures that battery devices can find a nearby router during pairing rather than connecting directly to the coordinator.

Pairing with ZHA

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.

Pairing with Zigbee2MQTT

1. In the Zigbee2MQTT frontend, toggle Permit Join in the top-right corner. This opens the network for new devices for a configurable duration (default 254 seconds).
2. Put your Zigbee device into pairing mode according to its manual.
3. The device should appear in the device list within 30 seconds. Zigbee2MQTT identifies the device model, manufacturer, and supported features automatically.

Tips for Reliable Pairing

• Pair 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.
• 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.
• Check the supported devices list before pairing if using Zigbee2MQTT. Visit zigbee2mqtt.io/supported-devices to confirm your device is supported. Unsupported devices may still work but could require a custom converter.

Rename Devices After Pairing

Rename devices immediately after pairing to avoid confusion later.

ZHA

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.

Zigbee2MQTT

1. Select the device from the Zigbee2MQTT device list.
2. Select the Settings tab (gear icon).
3. Change the Friendly Name to something descriptive (e.g., kitchen_motion_sensor).
4. The MQTT topic and Home Assistant entity update automatically.

If Pairing Fails

1. Confirm the coordinator is still online in your integration.
2. Move the device closer to the coordinator or a nearby router device and try again.
3. Factory reset the device according to its manual and attempt pairing again.
4. For ZHA, check the coordinator status under Settings → Devices & Services → ZHA → Configure.
5. For Zigbee2MQTT, check the Log tab for error details.

For detailed troubleshooting, see the Zigbee device unavailable or unresponsive guide .