Quirks v2: no way to disable binding of a cluster (e.g. IasZone)

[zigpy-review-bot]

Summary

There is currently no quirks-v2 mechanism to opt a device out of binding a particular cluster (e.g. IasZone). The natural candidate, prevent_default_entity_creation(...), does not achieve this — by design it only suppresses HA entity registration and deliberately leaves the bind/reporting/cluster-config machinery untouched. This request is to add a first-class way for QuirkBuilder to disable a cluster bind (and ideally attribute reporting) for a device.

Found while answering a user question; analysis is against dev @ 3a884dc3.

Why prevent_default_entity_creation can't do this

After #657, binding/reporting/cluster-setup moved onto entities via _server_cluster_config / _client_cluster_config, and IAS Zone enrollment is now driven by the virtual entity IasZoneEnrollment, which declares the bind:

# zha/application/platforms/virtual.py
class IasZoneEnrollment(VirtualEntity):
    _server_cluster_config = {
        IasZone.cluster_id: ClusterConfig(bind=True, ...),
    }

It fails on two independent grounds:

1. The prevent-filter is hardcoded to skip virtual entities. _is_entity_removed_by_quirk returns early for anything on the VIRTUAL platform:

# zha/zigbee/device.py
def _is_entity_removed_by_quirk(self, entity):
    if self.quirk_metadata is None:
        return False
    if entity.PLATFORM == Platform.VIRTUAL:
        return False
    ...

So no prevent_default_entity_creation clause — by cluster_id=0x0500, by unique_id_suffix="_ias_zone_enrollment", or by a function= predicate matching IasZoneEnrollment — can ever match it. (test_quirks_v2_prevent_default_entities asserts exactly this: it filters e.PLATFORM != Platform.VIRTUAL and the virtuals survive.)

2. Even for non-virtual entities, the prevent-filter doesn't stop binding anyway. In _discover_new_entities, the entity is appended to _discovered_entities before the prevent check, and the prevent check only skips on_add() + HA registration:

# zha/zigbee/device.py
for entity in new_entities:
    self._discovered_entities.append(entity)        # unconditional
    if self._is_entity_removed_by_quirk(entity):
        continue                                     # only skips on_add + _pending_entities
    ...
    self._pending_entities.append(entity)

Binding then aggregates over _discovered_entities (the full set), not the registered set:

# zha/zigbee/device.py
aggregated = aggregate_cluster_configs(self._discovered_entities)

with agg.bind = agg.bind or config.bind in aggregate_cluster_configs (zha/zigbee/cluster_config.py). So a "prevented" entity's bind=True still takes effect — the filter is purely cosmetic w.r.t. the Zigbee layer.

Note: whether binding should aggregate over _discovered_entities rather than _pending_entities is arguably a separate question. It's noted here as the mechanism behind point 2, not as a bug report — for non-virtual entities one could imagine wanting prevent_default_entity_creation to also drop the cluster-config contribution. I've kept it in this one issue since it's the same story; happy to split it out if maintainers prefer.

Proposed enhancement

A way for a quirk to suppress a cluster bind (and ideally reporting), independent of entity creation. Rough sketch — open to whatever shape fits the v2 API best:

• A QuirkBuilder method, e.g. .prevent_cluster_bind(endpoint_id=..., cluster_id=..., cluster_type=...), recorded in quirk metadata; consulted in aggregate_cluster_configs/configure_cluster_configs so the matching (endpoint, cluster, side) entry is forced to bind=False (and/or reporting suppressed).
• This would need to apply to virtual-entity-driven configs too (the IAS Zone case), so it can't reuse the entity-removal path that skips VIRTUAL.

Use case

Some devices misbehave when the coordinator binds a cluster they nominally expose (duplicate/unwanted reports, enrollment side-effects, devices that should be left to a different controller, etc.). Today a quirk author has no v2-native escape hatch for this; the only recourse is custom cluster subclasses. A declarative opt-out keeps it in the quirk where the device-specific knowledge lives.

cc @TheJulianJES

[zigpy-review-bot]

Possibly related real-world case: zigpy/zha-device-handlers#4652 (Innr SP 120 — energy current_summ_delivered only updates on HA restart).

Correction (after reviewing a debug log from an affected device): my original framing of this — that the device's small reporting table fills up with configs for attributes it doesn't support, because the firmware silently accepts them — was wrong, and I'm retracting it. The log shows the opposite: the SP 120 cleanly rejects the attributes it doesn't support (no INSUFFICIENT_SPACE, no table overflow), and specifically refuses reporting for its own current_summ_delivered with INVALID_DATA_TYPE. It's a won't-report device, and the fix there is to poll the attribute (ZHA's existing ExposedFeatureMeteringPoller via SE_POLL_SUMMATION), not to suppress reporting.

So #4652 turns out not to be a motivating case for this issue — it argues for opt-in polling, not an opt-out of binding/reporting. Keeping the cross-link for traceability only. A per-cluster bind/reporting opt-out (the subject of this issue) may still have independent merit, but the Innr case shouldn't be cited as evidence for it.

That said, the (now-closed) PR zigpy/zha-device-handlers#5052 is a concrete example of the reporting half of this: a CustomCluster that overrides configure_reporting to allow-list which attributes get reporting configured. It turned out unnecessary for the SP 120 itself (that firmware rejects unsupported attributes cleanly, so there's nothing to suppress), but it shows the device-side reporting-control that a first-class quirks-v2 opt-out — bind and/or reporting, per cluster — could provide declaratively for devices that do need it.

[zigpy-review-bot]

Cross-referencing puddly's RFC zigpy/zha#762 ("Migrate quirks out of zigpy and provide direct entity access"), which is relevant to where this feature should ultimately live.

That RFC inverts the quirks dependency chain: the v2 quirk definitions/metadata move out of zigpy and into ZHA, quirks import ZHA, and ZHA drops the == pin on quirks (==1.2.0 → >=1.2.0). Note this is a partial inversion: ZHA keeps a loosened dependency on quirks while the quirks now import ZHA, so the end state is a zha ⇄ zha-quirks cycle rather than a clean one-way DAG. Two implications for this issue:

1. The metadata home is moving zigpy → ZHA. Today, adding a bind/reporting-suppression knob means a two-repo, version-locked change (a builder field in zigpy.quirks.v2 + consumption logic in ZHA's aggregate_cluster_configs/device.py, bumped in lockstep). Post-RFC: Migrate quirks out of zigpy and provide direct entity access #762 it collapses to a ZHA-internal change, with the metadata defined next to the aggregation code that honors it. So the clean long-term form of this feature is a ZHA-native metadata field rather than a narrow toggle bolted onto zigpy. (The == → >= relaxation is itself only sound because ZHA becomes the schema authority — further reason the metadata belongs in ZHA.)

2. The device-level discover_entities() override in RFC: Migrate quirks out of zigpy and provide direct entity access #762 would address the IAS Zone case directly — and in a way prevent_default_entity_creation structurally can't. Binding aggregates over the discovered entity set; a quirk that overrides discover_entities() can simply not yield IasZoneEnrollment, and the bind goes with it. That sidesteps the wall noted above (_is_entity_removed_by_quirk hardcodes return False for Platform.VIRTUAL, so virtual entities are unfilterable today).

This shouldn't block on #762 (unmerged POC, provisional API names), but scoping here should assume the metadata's home is ZHA, and that a declarative per-cluster opt-out on the simple v2 builder + discovery-level access to virtual entities are the two complementary pieces.