Lights don't get their color state updated on reports

[JojiiOfficial]

Currently, it seems that color-change reports for light endpoints aren't properly handled.
I'm trying to let my Zigbee device report its changed color, but (in my case) Home Assistant doesn't update its state.

For the on/off and level clusters, event listeners are properly created.
However, for color clusters they aren't, despite the cluster being created inside the constructor.

I assume this is the root cause of the behavior I'm seeing, but I didn't get to verify it yet.

Is there a reason color clusters don't get event listeners assigned or is that eventually a bug?

[TheJulianJES]

It's intentional because a transitioning light would constantly show intermediate state in HA, even though HA expects light state to be the target state. So when setting a light to a specific color in the picker, the selection would jump back to the starting state and then move a lot before stopping (when using a (default) transition time longer than 0).

However, we worked around that for brightness by just debouncing those reports, so we could probably just do that for color as well.

However, the color_mode attribute isn't reportable, so we don't know if/when a color + temperature light switches between those two modes. I do plan to take a look at this eventually.

Do note ZHA already polls lights in the background every hour or so, so the state should eventually correct itself. You can also poll the light manually by calling the homeassistant.update_entity service/action in some automation or script.

[zigpy-review-bot]

For future reference, here's how other Zigbee implementations (Zigbee2MQTT, deCONZ, openHAB) handle color attribute reports — checked against their current sources.

TL;DR: none of the three suppress mid-transition reports — deCONZ and openHAB configure color reporting and apply whatever arrives immediately (accepting intermediate values), while Z2M configures no reporting for lights at all by default (on/off, brightness, and color alike) and relies on optimistic state plus explicit reads, so it sidesteps the problem rather than solving it.

For the non-reportable ColorMode attribute, all three combine optimistic mode tracking from the last command sent with configure-reporting-anyway, polling, and/or inference from which attribute reported.

Comparison at a glance

	Applies color reports to state?	Configures color reporting by default?	Mid-transition reports	Active color mode determined by
ZHA today	❌ (cache only, entity updates on ~1 h poll)	✅ x/y + color temp (min 30 s, max 900 s)	n/a (all reports ignored)	optimistic on command + color_mode read when polling
Zigbee2MQTT	✅ immediately	❌ (opt-in per device definition)	applied live, no suppression	optimistic on command → reported colorMode if present → cached → inferred from reporting attribute
deCONZ	✅ immediately	✅ x/y + CT (min 1 s, max 300 s) and ColorMode despite the spec	applied live, no suppression (optimistic target write masks the jump)	optimistic on command + ColorMode/EnhancedColorMode reports + poll fallback
openHAB	✅ immediately	✅ hue/sat or x/y + CT (min 1 s, max 2 h) and tries ColorMode	applied live, no suppression	any x/y (or hue/sat) report invalidates the CT channel; ColorMode read on refresh/poll

Zigbee2MQTT details

fz.color_colortemp (herdsman-converters fromZigbee.ts) handles attributeReport and readResponse identically and publishes to MQTT state immediately; there's no transition suppression anywhere (an opt-out converter to drop color reports exists but no device uses it).

The catch: Z2M configures no reporting at all for lights by default — on/off, level, and color reporting setup all sit behind configureReporting: false in the generic light() modern-extend (only ~220 device definitions across the library opt in; when enabled: color at min 10 s / change 1, level at min 5 s). In fact it doesn't even bind the light clusters to the coordinator by default — the bind call sits behind the same flag, and the default light configure step only reads colorCapabilities and colorTempPhysicalMin/Max — so reports that do arrive anyway (e.g. Hue bulbs spontaneously reporting their on/off state, per Z2M's own code comments) are firmware-default device behavior, not something Z2M requested. So Z2M rarely sees report storms during transitions in the first place — state freshness comes from optimistic state published on every command, reads on MQTT get, and scheduled reads after relative move/step commands (it sleeps 100 + transition × 100 ms, then reads the attribute plus colorMode).

Color mode resolution in syncColorState (lib/color.ts) is a three-tier fallback: reported colorMode if the frame contained it → previously cached mode → inferred from which attribute arrived. Every color/CT set command stamps the mode optimistically, which resolves the color+CCT ambiguity in the common case. The color_sync option (default on) then back-fills the other representations (xy ↔ hs ↔ color_temp) so they stay mutually consistent.

Which devices opt in: the ~220 configureReporting: true definitions are dominated by white-label dimmer/LED-controller vendors (Sunricher and its rebrands like Iluminize/ROBB/iCasa/EcoDim, Candeo, Schneider Electric, Namron, Gledopto, Samotech, …) — the major consumer bulb brands all leave it off: Philips Hue and IKEA lights have zero opt-ins, as do LEDVANCE, Sengled and Paulmann (Innr has one, OSRAM three). Outside those opt-ins, the only automatic path to level/color reporting in Z2M is the bind-time setup described in the bound-remotes section below — a stock major-brand bulb with no remote bound and no manual reporting config sends no reports at all, so its MQTT state is purely optimistic command echo corrected by explicit reads.

deCONZ details

Both the legacy path (updateLightNode() in de_web_plugin.cpp) and the modern DDF path write every received color attribute (x, y, CT, hue, sat, color mode) straight into REST state and push a websocket event — no transition guard at all. The UI jump is masked by writing the target value optimistically when the command is issued, so live reports just walk the state toward where it already points.

Reporting is configured aggressively at pairing: color temp + currentX/Y at min 1 s / max 300 s (change 10 on x/y; relaxed values for IKEA), and — notably — ColorMode 0x0008 is configured for reporting anyway, despite ZCL marking it non-reportable. Many lights report it regardless; spec-conformant ones just NACK that one record. DDF-era device files do the same via EnhancedColorMode 0x4001.

Mode tracking is belt-and-suspenders: optimistic write on every command (REST handler and task layer, including group casts fanned out to members), ColorMode/EnhancedColorMode reports when the light provides them, and polling as the backstop (legacy: reads 0x0008 + 0x4001 every poll round while the light is on; DDF: per-item refresh.interval of 300 s where incoming reports suppress the polling). Hue bulbs bypass ZCL entirely: one proprietary 0xFC03 report carries on/bri/CT/xy plus mode bits atomically.

openHAB details

ZigBeeConverterColorColor.attributeUpdated() applies reports immediately, with two small smoothing mechanisms: an X or Y report is cached until its partner attribute arrives (or a 500 ms one-shot timer fires and updates using the cached partner), and value-equality dedup. Mid-transition reports flow straight to the channel, throttled only by the configured min 1 s reporting interval.

It configures reporting for hue/sat or x/y, CT, level, and on/off at min 1 s / max 2 h / change 1 — and also tries ColorMode; if the device rejects it, that channel degrades to 60 s polling. (The underlying zsmartsystems library correctly models ColorMode as non-reportable but sends the configure request anyway.)

The mode problem is solved directionally: the color-temperature converter treats any x/y or hue/sat report as "not in CT mode" and sets its channel to UNDEF — the x/y reporting itself doubles as the mode signal — while ColorMode is additionally read on every refresh/poll.

Vendor specifics: Philips Hue and IKEA

Newer Hue bulbs support atomic native control via manufacturer cluster 0xFC03: one frame/report carries on/off + brightness + color/CT plus the color mode bits, sidestepping both the multi-attribute-burst and the ColorMode problems entirely. deCONZ uses this as its primary Hue path (binds only 0xFC03 attr 0x0002, disables standard-attribute polling); Zigbee2MQTT offers it behind an off-by-default hue_native_control option (manuSpecificPhilips2 multiColor command).

Notably, Z2M registers the decoder for Hue native state reports but deliberately does not auto-bind/configure reporting for them: "causes unwanted effects (reports in-between states, conflicting with optimistic states)" (philips.ts, see Koenkk/zigbee2mqtt#32050) — i.e. the one place Z2M enabled report-driven light state, it ran into exactly the mid-transition problem described above, which a transition-aware buffer on the ZHA side would address rather than avoid. A draft of the same native Hue support for ZHA (atomic 0xFC03 frames driving the light entity) already exists in the description of #762.

IKEA: Z2M configures no reporting for IKEA lights either, and its IKEA integration re-applies any configured reportings when a bulb re-announces, because IKEA bulbs lose reporting configuration on power cycle (bindings survive). For the color-mode side, IKEA speaks EnhancedColorMode (0x4001) — deCONZ's IKEA handling prefers 0x4001 over 0x0008, another argument for ZHA opportunistically configuring both.

Related: how Z2M handles remotes bound directly to lights

A remote bound directly to a light changes the light's state without the coordinator seeing any command, so state would go stale even with report handling — unless the light reports. Z2M's bind extension addresses this with two complementary mechanisms:

1. Reporting configured at bind time: when a bind is created through Z2M, it also configures reporting on the target light for each bound cluster — onOff (min 0 s / max 1 h), currentLevel (min 5 s / max 1 h / change 1), and colorTemperature/currentX/currentY gated on the light's colorCapabilities (same intervals; colorMode again not included). The reporting is removed again when the last relevant bind is removed. So this is the one common flow where Z2M does set up color reporting automatically.
2. Poll-on-remote-command fallback for lights known not to report properly (manufacturer allowlist: Philips/Signify, Gledopto, Müller Licht, Telink, Busch-Jaeger, Trust, ATMEL): when the coordinator hears a remote's command, Z2M reads the affected attributes from the remote's bound targets — level step/move/stop → currentLevel, on/off/toggle → onOff, scene recall → on/off + level + color attributes, with the Hue Dimmer's manufacturer-specific notification mapped per button — debounced 1 s per target; group-addressed commands trigger reads of all group members instead. Notably, color attributes are only read on scene recall; remote color-temp move/step commands are not in the trigger list.

Both halves depend on the coordinator knowing the binds: zigbee-herdsman persists every device's bindings in its database, so Z2M can resolve "this remote is bound to those lights". zigpy/ZHA currently does not store binding information, so only the group-addressed part (reading members of the target group, which zigpy does track) would be directly portable today — the bound-unicast case would additionally need ZHA to track binds it creates (or query the device's binding table via Mgmt_Bind_req).

Interesting takeaway for ZHA: since ZHA already configures x/y + color-temp reporting (min 30 s) and already has the transition flag + buffer machinery used for brightness, applying color reports with transition buffering would actually make it the only implementation that handles the mid-transition jumping properly rather than relying on optimistic writes to mask it. The remaining gap is externally-initiated mode switches on color + color-temp lights — a possible decision rule for that below.

Possible color-mode decision rule for ZHA (and caveats)

Since ColorMode (0x0008) isn't reportable per spec but some lights report it anyway (see above), a report burst could be classified like this:

1. Burst contains color_mode (or enhanced_color_mode 0x4001): authoritative — use it. ZHA could opportunistically add both to its Configure Reporting command like deCONZ/openHAB do: it's a multi-record command with per-record status, so conformant devices reject just those records (UNREPORTABLE_ATTRIBUTE) while x/y/CT configure fine, and lights that do report the mode (Hue, and per deCONZ also e.g. IKEA via 0x4001) get external mode switches handled for free.
2. Only x/y changed → light is in xy mode; only color temp changed → ct mode.
3. Both x/y and color temp in the burst, no mode attribute → ambiguous: keep the last-known color mode.

Rule 3 deliberately catches two real cases: periodic max-interval reports (at max_interval all configured attributes report regardless of change, so all three arrive together with unchanged values) and lights that keep current_x/current_y synced to the color temperature, where a CT change reports new CT and matching x/y together (Philips Hue is believed to do this — still to be verified; possibly the reverse direction too). In both cases, staying on the last-known mode is correct.

Implementation caveats:

• "Burst" isn't a ZCL concept — attributes arrive as separate report records, possibly in separate frames, and zigpy emits one event per attribute. Classifying needs a short aggregation window (compare openHAB's 500 ms x/y pairing timer).
• Per-attribute reporting timers aren't guaranteed to fire together, so a drifted periodic report could look like a lone "changed" attribute. Gating rules 2/3 on the value actually differing from the cached one defuses that (periodic re-reports carry unchanged values).
• Residual gap: a light that syncs x/y↔CT but doesn't report color_mode and gets its mode switched externally would stay on the stale mode — self-correcting at the next background poll, same as today.

[zigpy-review-bot]

An implementation of this is now available on the zigpy-bot/light-color-reports branch: dev...zigpy-bot/light-color-reports

It applies color attribute reports to light state with transition buffering (reusing the mechanism brightness reports already use), infers the active color mode per the decision rule discussed above, and opportunistically configures reporting for the (per ZCL unreportable) color mode attributes. The branch went through three adversarial review rounds and is ready to become a PR.

Implementation notes (for reviewers and future reference)

Mechanism

• Light.on_add now subscribes to the color cluster's attribute events (read/reported/updated/written), like it already did for on/off and level.
• current_x/current_y/color_temperature/color_mode/enhanced_color_mode updates are debounced with a 0.5 s quiet period (COLOR_REPORT_AGGREGATION_DELAY; each event re-arms the timer) — related attributes arrive as individual events, possibly in separate frames — then classified as one burst in _apply_color_reports.
• Classification order: a single supported color mode is forced first (mirroring async_update, so a bogus mode report can't discard a valid value on e.g. a CT-only light); otherwise a reported color_mode/enhanced_color_mode is authoritative; otherwise the mode is inferred from which values changed vs last-seen baselines (only x/y → XY, only color temp → CT, both or neither → keep the current mode — which covers periodic max-interval reports and lights that keep x/y synced to the color temperature).
• Sentinel color_temperature values (0/0xFFFF) are ignored entirely, as both value and mode signal — some lights park the attribute at a sentinel when leaving CT mode (openHAB filters exactly these values).
• Reports arriving during a transition are buffered in _transition_color_buffer and applied at transition end — async_transition_complete for individual transitions, transition_off() for group members, each guarded so an overlapping other-kind transition defers the buffer. Transition start discards any pending aggregation, so stale pre-transition reports can never overwrite the commanded target.
• Reporting is opportunistically configured for color_mode and enhanced_color_mode (min 0 s / max 900 s): unreportable per ZCL, but some lights (e.g. Hue) report them anyway, and conformant devices reject just those records of the multi-record Configure Reporting command.
• color_loop_active reports update the effect state, gated on the color-loop capability bit (some devices carry a stale color_loop_active: 1 without supporting it).
• The last-seen change-gating baselines are seeded from optimistic command state, poll results, restored external state, and startup, so they cannot drift from entity state.

Review history

Three adversarial review rounds ran against the branch (a Claude Opus 4.8 agent, Copilot CLI with GPT-5.6 Sol, and Claude Opus 5), each finding verified against the code before fixing. Fixed along the way: pre-transition reports leaking through the aggregation window into (or past) a transition; group-transition buffers never being applied (transition_off only cleared the flag); bogus mode reports discarding valid values on single-mode lights; last-seen baseline drift; sentinel CT values wiping color state; the individual/group transition overlap; disable() leaving the aggregation timer armed.

Accepted limitations

• A poll read landing mid-transition gets buffered and applied at transition end — identical to the existing brightness-report behavior, so kept for parity.
• On lights that sync x/y to CT but report no color mode, value reports staggered more than 0.5 s apart can transiently flip the inferred mode; this self-corrects at the next background poll, and mode-reporting lights are immune.
• A device that bogusly answers UNSUPPORTED_ATTRIBUTE (0x86, instead of the conformant UNREPORTABLE_ATTRIBUTE 0x8C) to the color_mode reporting record gets that attribute marked unsupported in the zigpy cache until the first poll's live read self-heals it — judged acceptable given deCONZ/openHAB have configured this reporting in production for years.

Follow-up candidates (not in this branch)

• Revisit HueLight's aggressive polling: the class targets old ZLL-era Hue bulbs that don't report, but currently matches all Philips/Signify lights, and modern Hue bulbs report fine (including color mode) — with color reports applied, the fast poll is doubly redundant for them.
• Pre-existing one-liner: _async_unsub_transition_listener nulls _transition_listener before removing it from _tracked_handles, so it always attempts remove(None) and the handle list grows per transition.

Tests

Ten new tests in tests/test_light.py (report application and mode inference, ambiguous/periodic bursts, authoritative mode reports incl. enhanced, transition buffering, the pre-transition discard, single-mode bogus-mode reports, group-transition buffering, the individual/group overlap, CT sentinels, color loop effect); the regression tests were verified to fail against the unfixed code. Full suite: 1354 passed; ruff/mypy/codespell clean.

Aggregation design notes (why a trailing debounce, known trade-offs)

The flush fires 0.5 s after the last event, not the first: same-frame records are dispatched in one loop tick and always land in one burst, and split frames within the quiet period pair up. Applying on the leading edge instead would run mode inference on a half burst (x arrives → XY inferred → CT lands 100 ms later). The 0.5 s value matches openHAB's x/y pairing timer — the only field precedent for this problem; there's no data yet on how far apart real devices space split frames.

Known theoretical weaknesses, all judged not worth code today:

• Sustained sub-0.5 s report chatter defers the flush indefinitely (a debounce never fires under continuous input). Unreachable with ZHA's own min 30 s color reporting config; if it ever bites (spammy non-conformant devices), the fix is a max-wait cap: flush no later than ~2 s after the first pending event.
• The debounce merges by time, not source: a poll read's color_mode landing < 0.5 s before a genuine report of changed x/y wins as "authoritative" despite being staler, so an externally-switched mode could stick wrong until the next poll. Requires a poll/report collision plus a light that doesn't report its mode; self-corrects.
• The principled fix is one layer down: zigpy's attribute events carry no frame/TSN grouping, so ZHA can't aggregate per Report Attributes frame and has to guess with a timer. If zigpy exposed the grouping, the debounce would only cover genuinely cross-frame stragglers and the poll/report merge hazard would mostly disappear (a read response and a report never share a TSN).