Skip to content

Replace cluster handlers with entity attributes - #657

Merged
puddly merged 87 commits into
zigpy:devfrom
puddly:puddly/drop-cluster-handlers
May 27, 2026
Merged

puddly merged 87 commits into
zigpy:devfrom
puddly:puddly/drop-cluster-handlers

Conversation

@puddly

@puddly puddly commented Feb 17, 2026 •

Copy link
Copy Markdown
Member

See #653 for a different approach.

As an example:

    # This now matches clusters instead of cluster handlers
    _cluster_match = ClusterMatch(
        server_clusters=frozenset({PowerConfiguration.cluster_id}),
        profile_device_types=frozenset(
            {(zha.PROFILE_ID, SMARTTHINGS_ARRIVAL_SENSOR_DEVICE_TYPE)}
        ),
    )

    # There is a similar `_client_cluster_config`
    _server_cluster_config = {
        PowerConfiguration.cluster_id: ClusterConfig(
            bind=True,
            attributes={
                PowerConfiguration.AttributeDefs.battery_voltage: AttrConfig(
                    read_on_startup=False,
                    reporting=REPORT_CONFIG_BATTERY_SAVE,
                ),
                PowerConfiguration.AttributeDefs.battery_percentage_remaining: AttrConfig(
                    read_on_startup=False,
                    reporting=REPORT_CONFIG_BATTERY_SAVE,
                ),
                PowerConfiguration.AttributeDefs.battery_size: AttrConfig(
                    read_on_startup=True,
                ),
                PowerConfiguration.AttributeDefs.battery_quantity: AttrConfig(
                    read_on_startup=True,
                ),
            },
        ),
    }

For an individual cluster, all entities referencing that cluster will have their individual cluster configurations combined and then aggregated into binding and attribute reporting requests.

This PR introduces the concept of virtual entities: these are entities that participate in discovery, binding reporting, and so on, same as any other. The only difference is that they have no public API and should be ignored by Core. They effectively replace cluster handlers for the very few circumstances we require something like them and actually cleans up a few hacks.


We should maybe introduce version for entity configuration? Right now, changing a reporting interval or adding new attributes requires a user to manually click "reconfigure". An alternative would be to keep track of all binding and reporting config in the zigpy database and diff it with the ZHA defaults. We'd need to track whether configuration has been automatically configured or if it was manually pushed, in case someone overrides reporting.

This is part of / a requirement for:

@dmulcahey

Copy link
Copy Markdown
Contributor

Cluster handlers that do not create entities but are used for binding need to be explicitly handled. I think the simplest way to do this would be to merge #594 and live with having duplicate entities before device deprecating automation triggers.

I agree. I think adding event entity support first is the way to go

We should maybe introduce version for entity configuration? Right now, changing a reporting interval or adding new attributes requires a user to manually click "reconfigure". An alternative would be to keep track of all binding and reporting config in the zigpy database and diff it with the ZHA defaults. We'd need to track whether configuration has been automatically configured or if it was manually pushed, in case someone overrides reporting.

we need several things to do this correctly .... an additional thing that comes to mind is queuing of commands for sleepy devices for example (if we want to auto apply changes when a new version is created).

@puddly

puddly commented May 27, 2026

Copy link
Copy Markdown
Member Author

Thanks @dmulcahey, fixed 😄

@puddly

puddly commented May 27, 2026

Copy link
Copy Markdown
Member Author

I think the event unique_id bugs were the only things really blocking this PR so we're good to go.

For the other points:

  • The virtual entity filtering will be done in Core
  • Re-wrapping exceptions will also be done in Core
  • Zigpy now handlers retries

@puddly
puddly merged commit e399b13 into zigpy:dev May 27, 2026
10 of 11 checks passed
@puddly
puddly deleted the puddly/drop-cluster-handlers branch May 27, 2026 13:14
@puddly puddly mentioned this pull request May 27, 2026
13 of 21 tasks
dw86uk added a commit to dw86uk/zha-device-handlers that referenced this pull request Oct 7, 2026
ZHA's OnOffClientCacheSync (zigpy/zha#657, zha >= 1.4) already turns the
on/off/toggle commands a client On/Off cluster receives into the cluster's
cached on_off value. With the quirk caching them as well, a toggle was
applied twice and cancelled itself out. Keep only the binary sensor
declaration on the input endpoint.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Further shape Zigbee support by implementing missing features in ZHA while retaining choice

5 participants