From 181f468fb40eabc560b279aaa0542963c7121f12 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Wed, 31 Jan 2024 09:48:44 +0100 Subject: [PATCH] Document light color_mode when rendering effects (#2054) --- docs/core/entity/light.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/core/entity/light.md b/docs/core/entity/light.md index 30830a9b..dc07fd4f 100644 --- a/docs/core/entity/light.md +++ b/docs/core/entity/light.md @@ -11,9 +11,9 @@ A light entity controls the brightness, hue and saturation color value, white va | Name | Type | Default | Description | ---- | ---- | ---- | ---- | brightness | int | None | `None` | The brightness of this light between 1..255 -| color_mode | ColorMode | None | `None` | The color mode of the light. The returned color mode must be present in the `supported_color_modes` property. +| color_mode | ColorMode | None | `None` | The color mode of the light. The returned color mode must be present in the `supported_color_modes` property unless the light is rendering an effect. | color_temp_kelvin | int | None | `None` | The CT color value in K. This property will be copied to the light's state attribute when the light's color mode is set to `ColorMode.COLOR_TEMP` and ignored otherwise. -| effect | str | None | `None` | The current effect. +| effect | str | None | `None` | The current effect. Should be `EFFECT_OFF` if the light supports effects and no effect is currently rendered. | effect_list | list[str] | None | `None` | The list of supported effects. | hs_color | tuple[float, float] | None | `None` | The hue and saturation color value (float, float). This property will be copied to the light's state attribute when the light's color mode is set to `ColorMode.HS` and ignored otherwise. | is_on | bool | None | `None` | If the light entity is on or not. @@ -68,6 +68,17 @@ If the light is in mode `ColorMode.HS`, `ColorMode.RGB` or `ColorMode.XY`, the l If the light is in mode `ColorMode.RGBW` or `ColorMode.RGBWW`, the light's state attribute will contain the light's color expressed in `hs`, `rgb` and `xy` color format. The color conversion is an approximation done by adding the white channels to the color. +### Color Mode when rendering effects + +When rendering an effect, the `color_mode` should be set according to the adjustments supported by the +effect. If the effect does not support any adjustments, the `color_mode` should be set to `ColorMode.ONOFF`. +If the effect allows adjusting the brightness, the `color_mode` should be set to `ColorMode.BRIGHTNESS`. + +When rendering an effect, it's allowed to set the `color_mode` to a more restrictive mode than the color modes +indicated by the `supported_color_mode` property: + - A light which supports colors is allowed to set color_mode to `ColorMode.ONOFF` or `ColorMode.BRIGHTNESS` when controlled by an effect + - A light which supports brightness is allowed to set color_mode to `ColorMode.ONOFF` when controlled by an effect + ## Supported Features Supported features are defined by using values in the `LightEntityFeature` enum