ZHA: refine docs for groups and binding (#37500)

* ZHA groups and binding revisions

* ZHA: simplify group/binding subheadings

* Add steps for binding, refine steps for groups

* Capitalize Zigbee

* Fix typo, fix bold syntax slip

* Revise some language
This commit is contained in:
kylehakala 2025-02-25 13:07:16 -06:00 committed by GitHub
parent abbd14c23d
commit 9d24e3b112
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -69,7 +69,7 @@ This {% term integration %} currently supports the following device types within
- [Switch](/integrations/switch/)
- [Update](/integrations/update/)
In addition, it has support for "Zigbee groups" that enable native on-device grouping of multiple Zigbee lights, switches, and fans that enable controlling all entities for those devices in those groups with one command. At least two entities must be added to a Zigbee group inside the ZHA {% term integration %} before a group entity is created. There is also support for native on-device Zigbee [binding and unbinding (i.e. bind a remote to a lightbulb or group)](#zigbee-binding-and-unbinding).
In addition, it has support for "Zigbee groups" that enable native on-device grouping of multiple Zigbee lights, switches, and fans that enable controlling all entities for those devices in those groups with one command. At least two entities must be added to a Zigbee group inside the ZHA {% term integration %} before a group entity is created. There is also support for native on-device binding. Refer to the [Zigbee groups and binding devices](#zigbee-groups-and-binding-devices) section for more information.
## Introduction
@ -501,27 +501,52 @@ In practice, you will likely need to add a lot more Zigbee router devices than i
## Zigbee groups and binding devices
ZHA supports Zigbee groups and binding devices to each other. These features can be used separately or combined. For example, binding a remote to a bulb or group has the benefit of faster response time and smoother control, as the remote directly controls the bound devices.
ZHA supports the creation of Zigbee groups (different from Home Assistant's [Group](/integrations/group/) integration), as well as binding devices to each other. Groups and device binding can be set up independently of each other, but they can be also used in combination (such as binding a device to another group of devices).
### Zigbee group
### Groups
A Zigbee group enables the grouping of multiple Zigbee lights, switches, and fans. This allows you to control those devices with only one command/entity.
A Zigbee group is a collection of two or more Zigbee lights, switches, or fans. A Zigbee group can then be controlled using only one command/entity.
{% note %}
While using a native Zigbee group instead of Home Assistant's [Group](/integrations/group/) integration can improve the visual responsiveness, the broadcast commands issued can flood the Zigbee network if issued repeatedly.
{% endnote %}
To create a Zigbee Group, press the "Configure" button on the ZHA integration config page. At the top, choose "Groups" and select "Create Group". Set a group name and choose which devices to include in the group.
#### To create a Zigbee group
The group should consist of products of the same device type (e.g. all lights, switches, or fans), and at least two devices must be added to a Zigbee group before a group entity is created.
1. Select the **Configure** button on the ZHA integration page,
2. Choose **Groups** and select **Create Group**,
3. Enter a name for the group,
4. Select which devices to include in the group:
- At least two devices must be added to a Zigbee Group before a group entity is created.
- The group should consist of products of the same device type (all lights, all switches, or all fans).
### Zigbee binding and unbinding
### Binding
Binding is an on-device feature for Zigbee devices. It provides a mechanism for attaching an endpoint of one Zigbee device to an endpoint of another Zigbee device or to a Zigbee group.
Binding a Zigbee device attaches an endpoint from one device to an endpoint of another device (or group).
For example, binding a "target destination" Zigbee device like a remote to a Zigbee light bulb, switch or group of light bulbs allows direct control of the "target" device (light, switch, shade) from the "remote" Zigbee device, bypassing ZHA. This means that the remote can control the light bulb or group even when ZHA is not active.
Commands sent between bound devices bypass ZHA (even when ZHA is not active) and directly control the targeted device. Binding devices can allow for faster response times and smoother control.
Note that not all devices support binding. By default, ZHA binds remotes to the coordinator, so click events are forwarded to HA. As some remotes can only be bound to a single destination, you might need to unbind the remote from the coordinator before binding it to another device or group.
Before binding devices, note the following:
- ZHA binds remotes to the Zigbee coordinator by default in order to forward click events to Home Assistant.
- Some remotes can only be bound to a single target; you might need to unbind the remote from the coordinator before binding it to another target.
- Not all devices support binding. Refer to the device manufacturer's documentation to confirm features.
#### To manage bindings of a Zigbee device
{% note %}
**This section only outlines how to manage bindings in general. It will not cover all use cases.**
Prerequisites and steps can vary depending on the device type, manufacturer, and your desired end result.
{% endnote %}
1. Navigate to the Zigbee device's configuration page,
2. In the options menu (the "three-dots" icon), select **Manage Zigbee device**,
3. Select the **Bindings** tab in the pop-up dialog,
4. Choose the device from the dropdown list of _Bindable devices_ (or _Bindable groups_),
5. Confirm the Bind or Unbind action:
- To bind devices: select **Bind** (or **Bind group**), or
- To unbind devices, select **Unbind** (or **Unbind group**).
## Backups and migration