Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document "Zigbee Groups" in ZHA integration #29316

Open
wants to merge 10 commits into
base: current
Choose a base branch
from
25 changes: 19 additions & 6 deletions source/_integrations/zha.markdown
Expand Up @@ -424,16 +424,29 @@ In this theoretical example, a CC2652-based Zigbee coordinator has three CC2530

In practice, you will likely need to add a lot more Zigbee router devices than in this example in order to extend the coverage of the network to reach that many devices.

## Binding and unbinding
## Zigbee Groups, Bindings and Unbindings

ZHA supports binding and unbinding. Binding is an action in Zigbee which defines relations between two Zigbee devices, specific endpoints, and cluster id. It provides a mechanism for attaching an endpoint on one Zigbee node to one or more endpoints on another Zigbee node or Zigbee group (a group of Zigbee devices).
ZHA integration support for native Zigbee Groups, as well as Zigbee Bindings and Unbindings. These features can be used separately or combined. Binding a remote directly to a bulb or group has the benefit of faster response time and smoother control. This can improve user visual experience like dimming lights as the remote then directly dims the light and thus does not have to make the software roundtrip via the ZHA coordinator.

Binding is a "target destination" in form of a device address or group ID, endpoint, and cluster. For example, binding a Zigbee device like a remote to a Zigbee lightbulb, switch or group of lightbulbs 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 lightbulb/group of lightbulbs even when the Zigbee coordinator is not available.
Binding is only supported within the same cluster, for example, "output cluster id 6" (on/off cluster) of a remote, can be only bound to an "input cluster id 6" on the target device -- light, switch.
### Zigbee Group

Note that not all devices support binding as it depends on the Zigbee implementation of the device itself. Also, by default ZHA binds remotes to the coordinator, so the coordinator can receive ZCL commands from the remotes and originate zha_events. However, some remotes, for example, the Philips RWL021 can only be bound to a single destination and it is not possible to make this switch to bind to other destinations like a device or groups unless you first unbind the remote from the coordinator. After you unbind the remote from the ZHA coordinator you can then bind it directly to any other Zigbee device or a group.
A "Zigbee Group" enables native on-device grouping of multiple Zigbee lights, switches, and fans that enable controlling all compatible entities for those devices in those groups with only one command/entity.

Binding a remote directly to a bulb or group has the benefit of faster response time and smoother control. This greatly improves user feedback experience functions like dimming as the remote then directly dims the lightbulb and thus does not have to make the software roundtrip via the ZHA coordinator.
<div class='note'>
Note that while using a native "Zigbee Group" inside the ZHA integration instead of Home Assistant's [Group](/integrations/group/) integration can improve the visual responsiveness and better synchronization grouping lights, the control commands broadcast can be rejected by devices if try to issue it to any Zigbee groups more than once or twice per minute.
</div>

To create a Zigbee Group click on "CONFIGURE" in the Zigbee Home Automation integration, at the top of the screen you will find "Groups", and there you can select "+ CREATE GROUP". Give the group a name and choose which devices that are compatible with each other should be in that group.

The group should consist of products of the same device type, (e.g. all lights, switches, or fans), and at least two entities must be added to a Zigbee group inside the ZHA integration before a group entity is created.

### Zigbee Binding and Unbinding

Binding is a native on-device action for Zigbee devices, defining relations between specific endpoints two Zigbee devices. It provides a mechanism for attaching an endpoint on one Zigbee device to one or more endpoints other Zigbee devices or a Zigbee group.

For example, binding a "target destination" Zigbee device like a remote to a Zigbee lightbulb, switch or group of lightbulbs 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 lightbulb/group of lightbulbs even when the Zigbee coordinator is not available.

Note that not all devices support binding as it depends on the Zigbee implementation of the device itself. Also, by default, the ZHA integration binds remotes to the coordinator when joining/pairing them, so the coordinator can receive commands from the remotes and originate zha_events. However, some remotes can only be bound to a single destination and it is not possible to make this switch to bind to other destinations like a device or groups unless you first unbind the remote from the coordinator. Only after you unbind such a remote from the ZHA coordinator you can then bind it directly to any other Zigbee device or a group.

## Zigbee backup and restore in ZHA

Expand Down