Handle supported 'state' changes via FC03 for supported Philips Hue lights

[hanskroner]

The Philips Hue Bridge uses the manufacturer-specific 0xfc03 cluster to control lights that support the cluster. The 0x00 command of this cluster provides a mechanism for changing multiple state properties of a light with a single command. This PR changes the way the REST API processes PUTs that would change selected 'state' keys of these lights to mimic the Hue Bridge's behavior.

The 0x00 command begins with a 2-byte encoding of the command's payload. This PR addresses only some of the state changes supported by the command. Using the nomenclature of the CLIP v2 API, they are:

| 15 | 14 | 13 | 12 | 11 | 10 | 09 | 08 | 07 | 06 | 05 | 04 | 03 | 02 | 01 | 00 |
| -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
   0    0    0    0    0    0    0    0    1    0    1    1    1    1    1    1
                                           -         -    -    -    -    -    -
                                           ^         ^    ^    ^    ^    ^    ^
                                           |         |    |    |    |    |    |
                                           |         |    |    |    |    |    +--- [on on]
                                           |         |    |    |    |    +-------- [dimming brightness]
                                           |         |    |    |    +------------- [color_temperature mirek]
                                           |         |    |    +------------------ [color xy]
                                           |         |    +----------------------- [dynamics duration]
                                           |         +---------------------------- [effects]
                                           |      
                                           +-------------------------------------- [timed_effects duration]

The PR avoids introducing additional complexity to setLightState() by processing only supported state changes of supported lights separately, in setHueLightState(). The functionality introduced in the this PR also overlaps with functionality that addTaskHueEffect() provides today - this could be removed at a later stage.

Bit 6 of the 0x00 command is very likely gradient, judging by the structure of the command used by addTaskHueGradient() - I unfortunately don't have a gradient light to confirm this.

[ebaauw]

I like this. Not too happy about the reformatting (makes it difficult to identify the real changes), but the logic looking very good to me.

[ebaauw]

Is this routine going to be invoked outside hue.cpp? If not, better define it locally in hue.cpp rather than including it in DeRestPluginPrivate. In that case, also define HueManufacturerSpecificPayload locally.

[hanskroner]

I decided on having it here cause I noticed a couple of places in rest_lights.cpp that call out to addTaskHueEffect() and figured addTaskHueManufacturerSpecific() would eventually succeed them.

[ebaauw]

I like this, making sure we don't break anything. I would like to go through all non-mappable items and see if we really cannot handle them from setHueLightState(). I don't care about hue and sat, but bri_inc and ct_inc would be nice (and I kind of expect the Hue bridge to handle these though FC03). And ontime to trigger an equivalent of On with Timed Off.

[hanskroner]

bri_inc and ct_inc are now dimming_delta and color_temperature_delta in the v2 API. The Hue Bridge sends out Step and ColorTemperatureStep commands for them - it doesn't seem to use 0xfc03 (yet?). I can't find any documentation for ontime, but including it as an additional key in the v2 API commands doesn't actually do anything.

[ebaauw]

There's probably some more places in rest_light.cpp where this could be leveraged.

[ebaauw]

addTaskHueEffect() could probably be refactored simply to call addTaskHueManufacturerSpecific().

[hanskroner]

I like this. Not too happy about the reformatting (makes it difficult to identify the real changes), but the logic looking very good to me.

Thanks. Noticed the formatting a little too late - but I've corrected that now to make the changes clear.

[manup]

Hi thanks for the PR. @hanskroner @ebaauw is this ready to be merged or wait for next beta?

[hanskroner]

I've been running it for a few days on a small test network (3 supported lights) with no surprises. I'm unsure if @ebaauw has had the chance to test this, but if I'm the only one so far it might be more sensible to wait for the next beta.

[ebaauw]

Not yet.

[Thomas-Vos]

The Philips Hue API now also allows customising effect speed/colour for all the effects. When this is supported in deCONZ, please reuse existing effectSpeed and effectColours attributes in the deCONZ API if possible (see xmas.cpp).

[hanskroner]

For some effects (e.g., prism, sunrise, and sunset) customizing the color doesn't seem to be possible. For the other effects, including the xy key along with the effect key in the request will already change the effect's color with this PR - as long as the light in question has firmware (at least) v1.222.2.

Modifying an effect's speed also requires firmware (at least) v1.222.2. The CLIP v2 API exposes it through dynamics/speed and including the effect_duration key in the request will already change the effect's speed with this PR as it uses the same byte in the FC03 command. Modifying the effect's speed this way through the API is awkward, because effect_duration's value is duration is in tenths of a second. I was thinking I'd introduce effect_speed which would take a float value between 0 and 1 to match what the CLIP v2 API does.

Using snake case for the key names seems more consistent with both the deCONZ REST and the CLIP v2 APIs to me.

[ebaauw]

What happens after you turn the effect off? Does the light remain on the effect colour, or does it revert to the previous colour from before the effect? In the latter case, we don’t need effectColors, just effect and xy. Can you change the colour of a running effect through only specifying xy? And the speed?

Note that effectColors (plural !) was introduced for the LIDL Xmas lightstrip, which does support up to six colours to be specified for effects.

The camel case is my bad; at some time I had hoped we’d be moving to that, but since many new snake case or simple lowercase items have been introduced (even by me).

[hanskroner]

What happens after you turn the effect off? Does the light remain on the effect colour, or does it revert to the previous colour from before the effect? In the latter case, we don’t need effectColors, just effect and xy.

After turning the effect off, the light will revert to the effect's color. Starting the underwater effect and then setting "effect": "none" will make the light stay in a light shade of blue. Starting the effect while passing in a purple color through xy and then turning the effect off will make the light stay in the passed-in shade of purple. The FC03 command seems to affect the light's state - not just the effect's state when that is passed. Indeed, starting an effect on a light, turning the light off, and then turning the light back on again will result in the light turning back on to the effect (and whatever color, brightness, speed, etc. attributes it had).

Can you change the colour of a running effect through only specifying xy? And the speed?

It doesn't seem to be possible, no. Passing in only xy while a light is running an effect will stop the effect and set the light to the passed-in color. Passing both effect and xy will cause the effect to (visibly) restart with the new color.