Expose the 'multicolor' command on Hue lights

[kjagiello]

Proposed change

I have sourced the Hue device models that support gradients from z2m and added a quirk for them, exposing Hue's "multicolor" command that can be used to control the gradient, i.e. set a custom gradient or activate a built-in gradient effect.

Below you will find more details on how this command can be used.

Static gradients

Here comes an example of how to set a custom gradient using an HA action:

action: zha.issue_zigbee_cluster_command
data:
  ieee: <ieee>
  cluster_id: 0xFC03
  endpoint_id: 11
  command: 0x0000
  command_type: server
  params:
      data: '50010400135000000037a7a30edb6337a7a30edb6337a7a32800'

To try out some other gradients, you can try one of the gradient scenes.

The payload structure is very cryptic, but, thankfully, the deconz and z2m communities have done a great job deciphering it. This PR does however not provide any handy interface for constructing the payload, since I was not sure how to do it properly.

If you want to create your own gradients, you can do it with the help of a simple wizard that I have put together: https://kjagiello.github.io/hue-gradient-command-wizard/..

Built-in effects

Using an HA action, you can activate, for example, the "opal" Hue effect:

action: zha.issue_zigbee_cluster_command
data:
  ieee: <ieee>
  cluster_id: 0xFC03
  endpoint_id: 11
  command: 0x0000
  command_type: server
  params:
      data: '2100010b'

You can find more effects here.

Additional info

This PR should, at least partially, resolve the following issues:

• [Device Support Request] Philips Hue Festavia string lights LCX015 #3500
• [Device Support Request] Hue Ambiance Gradient Lightstrip #2488

Checklist

• The changes are tested and work correctly
  • Caveat: As mentioned above, I have relied on the device signatures provided by z2m. The only gradient device that I own is LCX005, which I performed testing on.
• pre-commit checks pass / the code has been formatted using Black
• Tests have been added to verify that the new code works

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.49%. Comparing base (8124411) to head (7a02e38).
Report is 68 commits behind head on dev.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #3664      +/-   ##
==========================================
+ Coverage   89.85%   90.49%   +0.64%     
==========================================
  Files         322      323       +1     
  Lines       10379    10595     +216     
==========================================
+ Hits         9326     9588     +262     
+ Misses       1053     1007      -46     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[kjagiello]

For an easier way to generate the command payloads, you can check out https://kjagiello.github.io/hue-gradient-command-wizard/.

[BetaRavener]

Fixes #2517.

[jtbandes]

I also have some of these bulbs (Signify LTB003) and they support the candle effect in the Hue app. Should these (and other similar products) be included as well? I'm not entirely sure how to help test the changes but I could try to do so if that's helpful.

[BetaRavener]

@jtbandes I have HomeAssistant running in docker. To test the changes, I've logged in to the container running on remote server with VS Code as it's more convenient for text and folder editing, but you can also use classic ssh <hostname> and then docker exec -ti <container_name> sh and use console text editor. Then you can directly edit files under /usr/local/lib/python3.13/site-packages/zhaquirks/philips/ and once ready, restart home assistant. Even if you make mistake it will start up and you will find your error in the logs. If everything works, the new cluster will show up in GUI on your device:

and then

If you installed HA directly without docker, I'm rather positive you can use the same approach, minus docker exec, but if you are having troubles, find / -name "zhaquirks" 2>/dev/null could help you track down the file location.

[TheJulianJES]

I think we should combine most/all quirks into one file, e.g. gradient.py, since it's essentially the "same quirk", just adding the PhilipsHueCluster (and a friendly name).
Like, just have all QuirkBuilders in one file.

[jtbandes]

@BetaRavener cool, thanks for the info! Btw, are you still planning to pursue the UI work mentioned in #2517 (comment) to make the effects show up in the light's UI?

I was able to confirm that by adding .applies_to(SIGNIFY, "LTB003") I got access to the new command and was able to successfully activate the "candle" effect on my bulbs. I see this bulb is also mentioned in the z2m converter code, so I wonder if another pass should be done to copy all the supported devices from there?

Actually it looks like in Z2M, if I’m reading this right, all Hue devices get the candle effect by default. Should the same be done here, rather than just a handful of the devices being included? I'm not sure what the other 4 default effects (blink, breathe, okay, channel_change) are referring to, but they don't seem to be Philips-specific...wonder what they do? (I'm not a Z2M user so I can't easily play with them.)

By the way, the Hue app gives me the following options for these bulbs: a few pre-configured candle effects. Curious if anyone knows how the "custom candle" would be accessed via this command's parameters? (Probably not a big deal as I can barely tell the difference between the 3 premade candle effects anyway 😅)

[kjagiello]

I think we should combine most/all quirks into one file, e.g. gradient.py, since it's essentially the "same quirk", just adding the PhilipsHueCluster (and a friendly name). Like, just have all QuirkBuilders in one file.

Done! Though I have decided to put them under hue.py instead, because not all of Hue devices are gradient compatible, e.g. Hue Go or all the light bulbs. Let me know if you disagree! 🙏

[BetaRavener]

@jtbandes thanks for testing, we could include your bulb too then. I don't know what's best solution for dealing with all these models and there are apparently lot of them. With this PR, we are only making it possible to send command to the philips cluster. We could be implicit and enable the quirk for every philips device that has 0xFC03 cluster, but then we run risk that later philips might use the cluster for something else or otherwise break compatibility. Then we have to be explicit anyway and list all models. And for that we could either take something like z2m as source of truth, or add devices gradually as requested. In any case the list will have to be updated as Philips keeps creating new lights.

Regarding the effects, I will use the hue go issue thread as not to spam here, but yes I'll be looking into the HA GUI part. To just answer rest - in z2m code you shared it does does indeed seem like all philips lights have the hueEffect enabled by default because of this line. The definition of light would have to contain hueEffect: false, which is done only for single light in that codebase. That would mean quirk in this PR could apply to all those lights, but I'm still not persuaded we should just copy the whole list over without verifying.. And lastly, the other effects are not implemented by cluster in this PR but by Identify. Those are actually already exposed in (Z)HA:
,

so it's rather strange that z2m throws the "candle" effect into that mix. Maybe it's because any bulb that can change brightness (majority) could support "candle", but I'd still not do it that way.

[TheJulianJES]

And, do we wanna rename hue.py to light.py or hue_light.py? I think that makes it a bit clearer that those quirks are for Hue lightning.

Otherwise, I think we can merge this. I really hope that friendly_name doesn't cause us any issues. I don't think the implementation is ideal and we also don't implement model_id in ZHA, but I guess we can still try it. There shouldn't be any blueprints looking for the previous names.

HA naming generally specifies that the names should be written like this: Hue ambiance spot.

Looking at the US Hue page, this is also how Hue does it, so we should follow that:

"Hue Perifo light tube" should be fine, for example. This is also how Z2M does it: https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/devices/philips.ts

[TheJulianJES]

Would renaming this to PhilipsLightCluster or PhilipsHueLightCluster make sense?

[kjagiello]

And, do we wanna rename hue.py to light.py or hue_light.py? I think that makes it a bit clearer that those quirks are for Hue lightning.

Here's some context behind my thought process when choosing the current naming.

I went back and forth on the naming, but this Wiki article ultimately guided my choice. It describes Philips Hue as "a line of color-changing LED lamps and white bulbs".

Using just "Hue" felt appropriate, as it directly ties to the product line, whereas "Hue lights" seemed a bit redundant. On the other hand, calling it simply "lights" felt too broad (far fetched scenario perhaps, but Philips could introduce a new line of lighting products).

That said, I'm fully open to revisiting this if you feel a different name would be more appropriate. Let me know what you think!

HA naming generally specifies that the names should be written like this: Hue ambiance spot.

Makes sense! I've just pushed a change that aligns the naming.

[TheJulianJES]

Using just "Hue" felt appropriate, as it directly ties to the product line, whereas "Hue lights" seemed a bit redundant.

Hmm, there are Philips Hue remotes/dimmers and their Hue Secure line with Zigbee door sensors and other stuff.
Even if it may be a bit redundant to add use hue_light and PhilipsLightCluster/PhilipsHueLightCluster, I think it does make it a bit clearer that this is for the lights part of Philips Hue.

I mean, we can always freely rename this in the future, but let's say you're working on a quirk for a new Hue dimmer and try to use and import the Hue cluster for the remotes, you might stumble upon PhilipsHueCluster cluster and try to use that for your remotes. Granted, I doubt this will happen, but I think we could just clarify the lights part a bit.

[kjagiello]

Fair enough! Renamed everything now.

@BetaRavener I think you will need to take this rename into account in zigpy/zha#355

[TheJulianJES]

LGTM. Thanks!

[BetaRavener]

Amazing this landed, I'll updated the other PR accordingly. 👍