Skip to content

Conversation

@puddly
Copy link
Contributor

@puddly puddly commented Jan 6, 2026

As part of a medium-term goal of getting rid of cluster handlers and eventually rewriting entity classes themselves to request attribute reporting config/binding/attribute values, I think a first stepping stone would be to move away from implicit entity registration decorators and have entity objects themselves decide what cluster handlers they want (or if they are not applicable).

This is first draft and has not been runtime tested but I have most device entity tests passing. The few that do not may actually be current bugs with ZHA that are accidentally fixed by this PR.

Basically, instead of this:

@STRICT_MATCH(
    cluster_handler_names=CLUSTER_HANDLER_ON_OFF,
    aux_cluster_handlers={CLUSTER_HANDLER_COLOR, CLUSTER_HANDLER_LEVEL},
)
class Light(BaseClusterHandlerLight, PlatformEntity):
    ...

We do this:

@register_entity
class Light(BaseClusterHandlerLight, PlatformEntity):
    ...
    @classmethod
    def match_cluster_handlers(cls, endpoint: Endpoint) -> ClusterHandlerMatch | None:
        """Match cluster handlers for this entity."""
        # Only create an on/off light if the device type is correct
        if (
            endpoint.zigpy_endpoint.profile_id,
            endpoint.zigpy_endpoint.device_type,
        ) not in {
            # ZHA
            (zha.PROFILE_ID, zha.DeviceType.COLOR_DIMMABLE_LIGHT),
            ...
        }:
            return None

        return ClusterHandlerMatch(
            cluster_handlers=frozenset({CLUSTER_HANDLER_ON_OFF}),
            optional_cluster_handlers=frozenset(
                {CLUSTER_HANDLER_COLOR, CLUSTER_HANDLER_LEVEL}
            ),
            legacy_discovery_unique_id=f"{endpoint.device.ieee}-{endpoint.id}",
        )

There is no more complexity in ClusterHandlerMatch. It lists what cluster handlers are required, what cluster handlers are optional, and what unique ID format will be used for the entity. There are no stop groups or anything else, entity classes are expected to be explicitly coordinated to be mutually exclusive.

This has a few benefits:

  1. It moves unique ID calculation logic into the entity itself and makes it 100% explicit, allowing us to more easily migrate.
  2. Allows us to fine-tune cluster handler matching per-entity without adding more matching rules or even relying on a weighting system at all.
  3. Will allow us to move cluster handler ZCL attribute reporting and binding config into the ZCL entity objects themselves, allowing ZHA to granularly merge binding/reporting config when setting up a device.

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.

1 participant