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 02:16:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve light docs (#906)

Browse Source
This commit is contained in:
Erik Montnemery 2021-04-29 09:20:21 +02:00 committed by GitHub
parent 0409bcd9fe
commit f08f6127b9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 23 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -12,26 +12,26 @@ 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 | brightness | int | None | Return the brightness of this light between 0..255
| color_mode | string | None | Return the color mode of the light. Must be present in the `supported_color_modes` property. | color_mode | string | None | Return the color mode of the light. Must be present in the `supported_color_modes` property.
| color_temp | int | None | Return the CT color value in mireds. | 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.
| effect | String | None | Return the current effect. | effect | String | None | Return the current effect.
| effect_list | list | None | Return the list of supported effects. | effect_list | list | None | Return the list of supported effects.
| hs_color | tuple | None | Return the hue and saturation color value (float, float). | 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.
| is_on | bool | bool | Returns if the light entity is on or not. | is_on | bool | bool | Returns if the light entity is on or not.
| max_mireds | int | int | Return the warmest color_temp that this light supports. | 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. | 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). | 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_COLOR_RGB` and ignored otherwise.
| rgbw_color | tuple | None | Return the rgbw color value (int, int, int, int). | 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_COLOR_RGBW` and ignored otherwise.
| rgbww_color | tuple | None | Return the rgbww color value (int, int, int, int, int). | 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_COLOR_RGBWW` and ignored otherwise.
| supported_color_modes | list | None | Flag supported color modes. | supported_color_modes | list | None | Flag supported color modes.
| supported_features | int | int | Flag supported features. | 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. | 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). | 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_COLOR_XY` and ignored otherwise.
## Color Modes ## Color Modes
| Constant | Description | Constant | Description
|----------|----------------------- |----------|-----------------------
| `COLOR_MODE_UNKNOWN` | | `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_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_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_COLOR_TEMP` | The light can be dimmed and its color temperature is present in the state.
@ -41,10 +41,12 @@ A light entity controls the brightness, hue and saturation color value, white va
| `COLOR_MODE_RGBWW` | The light can be dimmed and its color is present in the state as an (r, g, b, cw, ww) tuple (not normalized for brightness). | `COLOR_MODE_RGBWW` | The light can be dimmed and its color is present in the state as an (r, g, b, cw, ww) tuple (not normalized for brightness).
| `COLOR_MODE_XY` | The light can be dimmed and its color is present in the state as an (x, y) tuple (no brightness). | `COLOR_MODE_XY` | The light can be dimmed and its color is present in the state as an (x, y) tuple (no brightness).
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. 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.
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 information is lost when the light is in mode `COLOR_MODE_RGB` as `hs` and `xy` don't hold brightness information. 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 information is lost when the light is in mode `COLOR_MODE_RGB` as `hs` and `xy` don't 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.
## Support Feature ## Support Feature
| Constant | Description | Constant | Description
@ -70,6 +72,19 @@ class MyLightEntity(LightEntity):
"""Turn device on.""" """Turn device on."""
``` ```
Note that there's no `color_mode` passed to the `async_turn_on` method, instead only a single color is allowed.
Colors in the service call will be translated before the entity's `async_turn_on` method is called if the light doesn't support the corresponding color mode:
| Color type | Translation
|--------------|-----------------------
| color_temp | Not translated, will be passed as is even if not supported by the light.
| hs_color | Will be removed from the service call if not supported and translated to `rgb_color`, `rgbw_color`, `rgbww_color` or `xy_color` if supported by the light.
| rgb_color | Will be removed from the service call if not supported and translated to `rgbw_color`, `rgbww_color`, `hs_color` or `xy_color` if supported by the light.
| rgbw_color | Not translated, will be passed as is even if not supported by the light.
| rgbww_color | Not translated, will be passed as is even if not supported by the light.
| hs_color | Will be removed from the service call if not supported and translated to `hs_color`, `rgb_color`, `rgbw_color` or `rgbww_color` if supported by the light.
### Turn Off Light Device ### Turn Off Light Device
```python ```python