Request add full support Philips Hue native control with decode/encode of custom "Bifrost effects" for Philips Hue lights support Zigbee frames in a manufacturer specific cluster implementation format on cluster 0xFC03 to zha, zigpy, zha-quirks/zha-device-handlers, and the ZHA integration UI:
Philips Hue lights support Zigbee frames in a manufacturer specific cluster implementation format, on cluster 0xFC03.
This type of specialized message is necessary to support many of the advanced features in Hue lights, such as:
- Multiple colors ("gradient") in LED strips
- Light Effects ("Candle", "Fireplace", etc)
- Combining effects with color settings
The use case for this is not only to add feature-parity with the support for this manufacturer specific cluster previously only avalable via a proprietary Philips Hue Bridge, but also to allow users to fully replace their Philips Hue Bridge to instead get a better user experience when only using Zigbee2MQTT for their Philips Hue lighting Zigbee devices.
Note! This feature requested is directly related to fact that a developer named Mihonarium has this week now added hue_native_control option for native control of Philips lights to zigbee-herdsman-converters in an implementation where he has rewritted zigbee-herdsman's existing Philips manufacturer specific cluster encoder/decoder handling and adds full feature-parity support for Philips Hue native control with encode/decode of custom effects, with improved effect UX and configurable color wheel/effect interaction in Zigbee2MQTT UI with now now report state, support color+speed in a single command, and the color wheel/effect interaction is configurable.
Summary
Adds a hue_native_control option for native control of Philips lights.
Rewrites the Philips manuSpecificPhilips2 encoder/decoder drafted by LaurentvdBos based on the Bifrost spec, fixing several data corruption bugs and adding missing functionality. Also improves effect UX: effects now report state, support color+speed in a single command, and the color wheel/effect interaction is configurable.
Opt-in
By default, standard ZCL converters handle on/off, brightness, color, and color temperature. The behavior is unchanged from before this PR. The manuSpecificPhilips2 cluster can send all of these in a single atomic command, which is required for full effect support: changing color while an effect is running, stopping effects by changing color, and setting an effect with a specific color in one command. However, native control also changes some user-facing behavior (e.g., no simulated fade-to-off transition), so it is opt-in.
Users can enable it per-device in Z2M Settings → Settings (Specific), or globally via device_options: { hue_native_control: true } in configuration.yaml.
New features
-
All Bifrost effects — Added sunset, sparkle, opal, glisten, underwater, cosmos, sunbeam, enchant (13 total including no_effect, candle, fireplace, prism/colorloop, sunrise)
-
effect + color in one command — {"effect": "candle", "color": "#FF4400"} activates the effect at that color atomically. Also supports effect_speed in the same payload.
-
effect_color (new expose) — Sets the base color of the active effect without stopping it. Accepts hex or XY.
-
effect_color_mode (new per-device option) — Controls what happens when the regular color wheel is used while an effect is active:
"stop" (default): color change stops the effect (matches Hue app)"update": color change re-sends the effect with the new color
-
Deferred brightness on effect re-send — When re-sending an effect (via effect_color or "update" mode) with an explicit brightness, the brightness is sent as a separate command after the effect, since effects reset brightness on activation.
-
effect and effect_speed access changed to STATE_SET — Current values are now visible in the Z2M frontend and HA.
-
effect_speed — Settable via both the new path (philipsLightTz) and the effect converter.
-
gradient_scale / gradient_offset — Settable. Fixed-point 5.3 format exposed as float.
-
gradient_style — Fully settable (linear, scattered, mirrored). Was decoded but not writable.
-
gradient_xy — Lossless XY coordinates published alongside RGB hex gradient.
-
philips2_raw — Raw hex blob published for advanced clients (e.g. Bifrost) to decode independently.
-
HSV→XY conversion — HSV colors are now converted correctly instead of being silently dropped.
-
transition → fadeSpeed — Mapped to the Bifrost spec's per-message fade speed field.
-
Delayed state read after effect activation — Reads device state 1s after activating an effect to sync actual brightness.
(Feel free to remove or ask me to remove the effect_color, effect_color_mode, and related stuff if it goes against the overall philosophy.)
Encoder/decoder rewrite
Replaced the ad-hoc hex string parsing with structured Encode/DecodeManuSpecificPhilips2 functions using DataView for proper binary field handling. The wire order follows the Bifrost spec (gradient colors before effect speed before gradient params — reversed relative to flag bit order). Each field type is defined as a HueTypeDetails struct with encode/decode/flag/maxLength, iterated in wire order.
Limitations
After activating an effect, we sync the device state via a 1-second setTimeout, as some Hue effects change light color/brightness. If the device goes offline in the window, the error is silently caught. There could be more robust approaches.
Other
I made a very cool hass dashboard card (inspired by the Hue app, but better than it)! See #12008 (comment)
PS: Feature request is also related to this Open Home Foundation roadmap tracker which raise idea of ZHA having feature-parity with Zigbee2MQTT
As well as being related to this guide for migrating from a Philips Hue Bridge to the ZHA (Zigbee Home Automation) integration in Home Assistant:
Request add full support Philips Hue native control with decode/encode of custom "Bifrost effects" for Philips Hue lights support Zigbee frames in a manufacturer specific cluster implementation format on cluster 0xFC03 to zha, zigpy, zha-quirks/zha-device-handlers, and the ZHA integration UI:
Philips Hue lights support Zigbee frames in a manufacturer specific cluster implementation format, on cluster 0xFC03.
This type of specialized message is necessary to support many of the advanced features in Hue lights, such as:
The use case for this is not only to add feature-parity with the support for this manufacturer specific cluster previously only avalable via a proprietary Philips Hue Bridge, but also to allow users to fully replace their Philips Hue Bridge to instead get a better user experience when only using Zigbee2MQTT for their Philips Hue lighting Zigbee devices.
Note! This feature requested is directly related to fact that a developer named Mihonarium has this week now added hue_native_control option for native control of Philips lights to zigbee-herdsman-converters in an implementation where he has rewritted zigbee-herdsman's existing Philips manufacturer specific cluster encoder/decoder handling and adds full feature-parity support for Philips Hue native control with encode/decode of custom effects, with improved effect UX and configurable color wheel/effect interaction in Zigbee2MQTT UI with now now report state, support color+speed in a single command, and the color wheel/effect interaction is configurable.
PS: Feature request is also related to this Open Home Foundation roadmap tracker which raise idea of ZHA having feature-parity with Zigbee2MQTT
As well as being related to this guide for migrating from a Philips Hue Bridge to the ZHA (Zigbee Home Automation) integration in Home Assistant: