Clarify light effect and light color mode

[emontnemery]

Background

The primary reason for introducing light color modes was that a light's state should not be ambiguous. As an example, a light which supports color and white with adjustable color temperature must be in either color mode hs (for example) or color_temp.

However, effects complicate this because when the same light is rendering an effect, none of the hs_color, color_temp or brightness state attributes may be meaningful.

Core PR #55450 proposes to add a new color mode to be used when the light is rendering an effect. However, that doesn't solve the ambiguity because while a light is rendering effect the brightness of the effect or brightness + color of the effect may be adjustable.

Proposal

Loosen requirements on color_mode when a light is rendering an effect

Allow more restrictive color modes than what's otherwise supported by the light when an effect is active:

• A light which supports colors would be allowed to indicate color modes on_off and brightness when controlled by an effect
• A light which supports brightness would be allowed to indicate color mode on_off when controlled by an effect.

For example, a light which has its supported_color_modes set to {"hs", "color_temp"} would be allowed to set its color_mode to on_off when rendering an effect which can't be adjusted and to brightness when rendering an effect which allows brightness to be controlled.

Integrations which can benefit from loosening requirements on color_mode when a light is rendering an effect

There are 28 core integrations with support for effects, I believe most of them would benefit from a stricter color_mode when rendering an effect.
It's at least the case for:

• nanoleaf
• philips_js - This integration already sets color mode to on_off when rendering effects
• tasmota

Add a special effect off which means no effect / turn off effect

There's currently no standard way for a light which supports effects to show that no effect is active.
Solve this by adding an off effect to indicate no effect is active,.

Integrations which can benefit from an off effect

I've not reviewed all 28 integrations with effect support, but a quick review of the 10 first integrations with lights which support effects show that half of them support turning off the effect:

• evil_genius_labs
• homematic
• hue
• hyperion
• iaqualink

[MartinHjelmare]

Won't this confuse supported_color_modes? What use cases are there for that attribute today?

[emontnemery]

Yes, this proposal suggests the light would be allowed to set the color mode to a color mode not in the supported_color_modes set when displaying an effect.
I think it we can restrict it to only allow a more restrictive color mode, meaning:

• A light which supports colors would be allowed to indicate color modes on_off and brightness when controlled by an effect
• A light which supports brightness would be allowed to indicate color mode on_off when controlled by an effect.

supported_color_modes is used for:

• Filtering and converting service call parameters, for example, a light which supports xy_color will have other colors converted to the xy color space
• Influence what controls are shown in frontend

[thecode]

Regarding effect, since there was no support for showing that there is no effect active, we added another state to the device effects list Off. I am not sure how other integrations solved this since (checked Deconz and there is no option to turn off an effect), I am just wondering if Off would be better than None which is usually used in cases something is not supported, Home Assistant uses On & Off in multiple places already.

[emontnemery]

since there was no support for showing that there is no effect active, we added another state to the device effects list Off

There are several integrations which have made this kind of implementation, but with varying name for the off / no effect option.
I think you're right, a string such as off would probably be a better choice.

[Kane610]

deCONZ should support turning off the effect and also tell if it's active. Haven't specifically verified it in practice but according to documentation it should.

[MartinHjelmare]

The proposal sounds ok.