jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-09 18:36:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add ColorMode enum to light platform (#1284)

Browse Source
This commit is contained in:
Franck Nijhof 2022-04-11 18:16:34 +02:00 committed by GitHub
parent 866a4752ca
commit 33c6fff69c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 35 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
docs/core/entity/light.md
View File

@ -12,59 +12,63 @@ A light entity controls the brightness, hue and saturation color value, white va
| ---- | ---- | ---- | ----
| brightness | int | None | Return the brightness of this light between 0..255
| color_mode | string | None | Return the color mode of the light. The returned color mode must be present in the `supported_color_modes` property.
| color_temp | int | None | Return the CT color value in mireds. This property will be copied to the light's state attribute when the light's color mode is set to `COLOR_MODE_COLOR_TEMP` and ignored otherwise.
| color_temp | int | None | Return the CT color value in mireds. 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 | String | None | Return the current effect.
| effect_list | list | None | Return the list of supported effects.
| hs_color | tuple | None | Return 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 `COLOR_MODE_HS` and ignored otherwise.
| hs_color | tuple | None | Return 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` | Returns if the light entity is on or not.
| max_mireds | int | int | Return the warmest color_temp that this light supports.
| min_mireds | int | int | Return the coldest color_temp that this light supports.
| rgb_color | tuple | None | Return the rgb color value (int, int, int). This property will be copied to the light's state attribute when the light's color mode is set to `COLOR_MODE_RGB` and ignored otherwise.
| rgbw_color | tuple | None | Return the rgbw color value (int, int, int, int). This property will be copied to the light's state attribute when the light's color mode is set to `COLOR_MODE_RGBW` and ignored otherwise.
| rgbww_color | tuple | None | Return the rgbww color value (int, int, int, int, int). This property will be copied to the light's state attribute when the light's color mode is set to `COLOR_MODE_RGBWW` and ignored otherwise.
| rgb_color | tuple | None | Return the rgb color value (int, int, int). This property will be copied to the light's state attribute when the light's color mode is set to `ColorMode.RGB` and ignored otherwise.
| rgbw_color | tuple | None | Return the rgbw color value (int, int, int, int). This property will be copied to the light's state attribute when the light's color mode is set to `ColorMode.RGBW` and ignored otherwise.
| rgbww_color | tuple | None | Return the rgbww color value (int, int, int, int, int). This property will be copied to the light's state attribute when the light's color mode is set to `ColorMode.RGBWW` and ignored otherwise.
| supported_color_modes | set | None | Flag supported color modes.
| supported_features | int | int | Flag supported features.
| white_value | int | None | Return the white value of this light between 0..255. This is deprecated and will be removed in Home Assistant 2021.10.
| xy_color | tuple | None | Return the xy color value (float, float). This property will be copied to the light's state attribute when the light's color mode is set to `COLOR_MODE_XY` and ignored otherwise.
| xy_color | tuple | None | Return the xy 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.XY` and ignored otherwise.
## Color Modes
New integrations must implement both `color_mode` and `supported_color_modes`. If an integration is upgraded to support color mode, both `color_mode` and `supported_color_modes` should be implemented.
Supported color modes are defined by using values in the `ColorMode` enum.
If a light does not implement the `supported_color_modes`, the `LightEntity` will attempt deduce it based on deprecated flags in the `supported_features` property:
- Start with an empty set
- If `SUPPORT_COLOR_TEMP` is set, add `COLOR_MODE_COLOR_TEMP`
- If `SUPPORT_COLOR` is set, add `COLOR_MODE_HS`
- If `SUPPORT_WHITE_VALUE` is set, add `COLOR_MODE_RGBW`
- If `SUPPORT_BRIGHTNESS` is set and no color modes have yet been added, add `COLOR_MODE_BRIGHTNESS`
- If no color modes have yet been added, add `COLOR_MODE_ONOFF`
- If `SUPPORT_COLOR_TEMP` is set, add `ColorMode.COLOR_TEMP`
- If `SUPPORT_COLOR` is set, add `ColorMode.HS`
- If `SUPPORT_WHITE_VALUE` is set, add `ColorMode.RGBW`
- If `SUPPORT_BRIGHTNESS` is set and no color modes have yet been added, add `ColorMode.BRIGHTNESS`
- If no color modes have yet been added, add `ColorMode.ONOFF`
If a light does not implement the `color_mode`, the `LightEntity` will attempt to deduce it based on which of the properties are set and which are `None`:
- If `supported_color_mode` includes `COLOR_MODE_RGBW` and `white_value` and `hs_color` are both not None: `COLOR_MODE_RGBW`
- Else if `supported_color_mode` includes `COLOR_MODE_HS` and `hs_color` is not None: `COLOR_MODE_HS`
- Else if `supported_color_mode` includes `COLOR_MODE_COLOR_TEMP` and `color_temp` is not None: `COLOR_MODE_COLOR_TEMP`
- Else if `supported_color_mode` includes `COLOR_MODE_BRIGHTNESS` and `brightness` is not None: `COLOR_MODE_BRIGHTNESS`
- Else if `supported_color_mode` includes `COLOR_MODE_ONOFF`: `COLOR_MODE_ONOFF`
- Else: COLOR_MODE_UNKNOWN
| Constant | Description
- If `supported_color_mode` includes `ColorMode.RGBW` and `white_value` and `hs_color` are both not None: `ColorMode.RGBW`
- Else if `supported_color_mode` includes `ColorMode.HS` and `hs_color` is not None: `ColorMode.HS`
- Else if `supported_color_mode` includes `ColorMode.COLOR_TEMP` and `color_temp` is not None: `ColorMode.COLOR_TEMP`
- Else if `supported_color_mode` includes `ColorMode.BRIGHTNESS` and `brightness` is not None: `ColorMode.BRIGHTNESS`
- Else if `supported_color_mode` includes `ColorMode.ONOFF`: `ColorMode.ONOFF`
- Else: ColorMode.UNKNOWN
| Value | Description
|----------|-----------------------
| `COLOR_MODE_UNKNOWN` | The light's color mode is not known.
| `COLOR_MODE_ONOFF` | The light can be turned on or off. This mode must be the only supported mode if supported by the light.
| `COLOR_MODE_BRIGHTNESS` | The light can be dimmed. This mode must be the only supported mode if supported by the light.
| `COLOR_MODE_COLOR_TEMP` | The light can be dimmed and its color temperature is present in the state.
| `COLOR_MODE_HS` | The light can be dimmed and its color can be adjusted. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light's color can be set using the `hs_color` parameter and read through the `hs_color` property. `hs_color` is an (h, s) tuple (no brightness).
| `COLOR_MODE_RGB` | The light can be dimmed and its color can be adjusted. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light's color can be set using the `rgb_color` parameter and read through the `rgb_color` property. `rgb_color` is an (r, g, b) tuple (not normalized for brightness).
| `COLOR_MODE_RGBW` | The light can be dimmed and its color can be adjusted. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light's color can be set using the `rgbw_color` parameter and read through the `rgbw_color` property. `rgbw_color` is an (r, g, b, w) tuple (not normalized for brightness).
| `COLOR_MODE_RGBWW` | The light can be dimmed and its color can be adjusted. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light's color can be set using the `rgbww_color` parameter and read through the `rgbww_color` property. `rgbww_color` is an (r, g, b, cw, ww) tuple (not normalized for brightness).
| `COLOR_MODE_WHITE` | The light can be dimmed and its color can be adjusted. In addition, the light can be set to white mode. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light can be set to white mode by using the `white` parameter with the desired brightness as value. Note that there's no `white` property. If both `brighthness` and `white` are present in a service call, the `white` parameter will be updated with the value of `brightness`. If this mode is supported, the light must also support at least one of `COLOR_MODE_HS`, `COLOR_MODE_RGB`, `COLOR_MODE_RGBW`, `COLOR_MODE_RGBWW` or `COLOR_MODE_XY`.
| `COLOR_MODE_XY` | The light can be dimmed and its color can be adjusted. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light's color can be set using the `xy_color` parameter and read through the `xy_color` property. `xy_color` is an (x, y) tuple.
| `ColorMode.UNKNOWN` | The light's color mode is not known.
| `ColorMode.ONOFF` | The light can be turned on or off. This mode must be the only supported mode if supported by the light.
| `ColorMode.BRIGHTNESS` | The light can be dimmed. This mode must be the only supported mode if supported by the light.
| `ColorMode.COLOR_TEMP` | The light can be dimmed and its color temperature is present in the state.
| `ColorMode.HS` | The light can be dimmed and its color can be adjusted. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light's color can be set using the `hs_color` parameter and read through the `hs_color` property. `hs_color` is an (h, s) tuple (no brightness).
| `ColorMode.RGB` | The light can be dimmed and its color can be adjusted. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light's color can be set using the `rgb_color` parameter and read through the `rgb_color` property. `rgb_color` is an (r, g, b) tuple (not normalized for brightness).
| `ColorMode.RGBW` | The light can be dimmed and its color can be adjusted. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light's color can be set using the `rgbw_color` parameter and read through the `rgbw_color` property. `rgbw_color` is an (r, g, b, w) tuple (not normalized for brightness).
| `ColorMode.RGBWW` | The light can be dimmed and its color can be adjusted. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light's color can be set using the `rgbww_color` parameter and read through the `rgbww_color` property. `rgbww_color` is an (r, g, b, cw, ww) tuple (not normalized for brightness).
| `ColorMode.WHITE` | The light can be dimmed and its color can be adjusted. In addition, the light can be set to white mode. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light can be set to white mode by using the `white` parameter with the desired brightness as value. Note that there's no `white` property. If both `brighthness` and `white` are present in a service call, the `white` parameter will be updated with the value of `brightness`. If this mode is supported, the light must also support at least one of `ColorMode.HS`, `ColorMode.RGB`, `ColorMode.RGBW`, `ColorMode.RGBWW` or `ColorMode.XY`.
| `ColorMode.XY` | The light can be dimmed and its color can be adjusted. The light's brightness can be set using the `brightness` parameter and read through the `brightness` property. The light's color can be set using the `xy_color` parameter and read through the `xy_color` property. `xy_color` is an (x, y) tuple.
Note that in color modes `COLOR_MODE_RGB`, `COLOR_MODE_RGBW` and `COLOR_MODE_RGBWW` there is brightness information both in the light's `brightness` property and in the color. As an example, if the light's brightness is 128 and the light's color is (192, 64, 32), the overall brightness of the light is: 128/255 * max(192, 64, 32)/255 = 38%.
Note that in color modes `ColorMode.RGB`, `ColorMode.RGBW` and `ColorMode.RGBWW` there is brightness information both in the light's `brightness` property and in the color. As an example, if the light's brightness is 128 and the light's color is (192, 64, 32), the overall brightness of the light is: 128/255 * max(192, 64, 32)/255 = 38%.
If the light is in mode `COLOR_MODE_HS`, `COLOR_MODE_RGB` or `COLOR_MODE_XY`, the light's state attribute will contain the light's color expressed in `hs`, `rgb` and `xy` color format. Note that when the light is in mode `COLOR_MODE_RGB`, the `hs` and `xy` state attributes only hold the chromaticity of the `rgb` color as the `hs` and `xy` pairs do not hold brightness information.
If the light is in mode `ColorMode.HS`, `ColorMode.RGB` or `ColorMode.XY`, the light's state attribute will contain the light's color expressed in `hs`, `rgb` and `xy` color format. Note that when the light is in mode `ColorMode.RGB`, the `hs` and `xy` state attributes only hold the chromaticity of the `rgb` color as the `hs` and `xy` pairs do not hold brightness information.
If the light is in mode `COLOR_MODE_RGBW` or `COLOR_MODE_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.
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.
## Supported Features