Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-01-11 20:02:12 +01:00
Code Issues Projects Releases Wiki Activity

Color mode documentation (#1328)

Browse Source
This commit is contained in:
Oxan van Leeuwen 2021-08-17 02:37:22 +02:00 committed by Jesse Hills
parent 4fa7131172
commit 4088388004
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
8 changed files with 117 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
components/light/custom.rst
View File

@ -27,9 +27,7 @@ The example below is an example of a custom light output.
// return the traits this light supports
auto traits = LightTraits();
traits.set_supports_brightness(true);
traits.set_supports_rgb(true);
traits.set_supports_rgb_white_value(false);
traits.set_supports_color_temperature(false);
traits.set_supports_color_modes({ColorMode::RGB});
return traits;
}

22
components/light/cwww.rst
View File

@ -5,9 +5,9 @@ Cold White + Warm White Light
:description: Instructions for setting up Cold White + Warm White lights.
:image: brightness-medium.png
The ``cwww`` light platform creates a Cold-White+Warm-White
light from 2 :ref:`float output components <output>` (one for each channel). The two
channels will be mixed using the color temperature configuration options.
The ``cwww`` light platform creates a cold white + warm white light from 2
:ref:`float output components <output>` (one for each channel). The two channels
can be controlled individually or together.
.. code-block:: yaml
@ -21,15 +21,27 @@ channels will be mixed using the color temperature configuration options.
warm_white_color_temperature: 2000 K
constant_brightness: true
.. _cwww_mixing:
Mixing
------
The two channels of this light can be controlled individually by using the ``cold_white`` and ``warm_white`` options of
the :ref:`light control actions <light-turn_on_action>`.
If the color temperature of both lights is supplied, it is also possible to control the the two channels together by
setting a color temperature, using the ``white`` (interpreted as brightness) and ``color_temperature`` options. This
calculation assumes that both lights have the same illuminance, which might not always be accurate.
Configuration variables:
------------------------
- **name** (**Required**, string): The name of the light.
- **cold_white** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the cold white channel.
- **warm_white** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the warm white channel.
- **cold_white_color_temperature** (**Required**, float): The color temperate (in `mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin)
- **cold_white_color_temperature** (*Optional*, float): The color temperature (in `mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin)
of the cold white channel.
- **warm_white_color_temperature** (**Required**, float): The color temperate (in `mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin)
- **warm_white_color_temperature** (*Optional*, float): The color temperature (in `mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin)
of the warm white channel.
- **constant_brightness** (*Optional*, boolean): When enabled, this will keep the overall brightness of the cold and warm white channels constant by limiting the combined output to 100% of a single channel. This reduces the possible overall brightness but is necessary for some power supplies that are not able to run both channels at full brightness at once. Defaults to ``false``.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.

7
components/light/hbridge.rst
View File

@ -36,6 +36,11 @@ The pins are switched alternatively to allow two sets of lights to operate.
pin_a: pina
pin_b: pinb
Internally, H-bridge lights are implemented as cold/warm white lights. This means that the brightness of the two colors
is mapped to the cold white and warm white values, even if the colors aren't actually white in reality. To individually
control the colors in the :ref:`light control actions <light-turn_on_action>`, you need to use the ``cold_white`` and
``warm_white`` options.
Configuration variables:
------------------------
@ -48,7 +53,7 @@ Configuration variables:
.. note::
As we are switching the h-bridge in software, the light may glitch every so often when other tasks run on the MCU.
As we are switching the H-bridge in software, the light may glitch every so often when other tasks run on the MCU.
See Also
--------

80
components/light/index.rst
View File

@ -131,26 +131,49 @@ Configuration variables:
- **id** (**Required**, :ref:`config-id`): The ID of the light.
- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the transition
if the light supports it.
- **brightness** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The brightness of the light. Must be in range
``0%`` to ``100%`` or ``0.0`` to ``1.0``. This is a master brightness that applies to all channels (both color and white) of the
light. Defaults to not changing brightness.
- **color_brightness** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The brightness of the color lights. Must
be in range ``0%`` to ``100%`` or ``0.0`` to ``1.0``. Useful to control brightness of colored and white lights separately for
RGBW lights. Defaults to not changing brightness.
- **red** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The red channel of the light. Must be in range
``0%`` to ``100%`` or ``0.0`` to ``1.0``. Defaults to not changing red channel.
- **green** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The green channel of the light. Must be in range
``0%`` to ``100%`` or ``0.0`` to ``1.0``. Defaults to not changing green channel.
- **blue** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The blue channel of the light. Must be in range
``0%`` to ``100%`` or ``0.0`` to ``1.0``. Defaults to not changing blue channel.
- **white** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The brightness of the white lights. Must be in range
``0%`` to ``100%`` or ``0.0`` to ``1.0``. Defaults to not changing white channel.
- **color_temperature** (*Optional*, float, :ref:`templatable <config-templatable>`): The white color temperature value (in `mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin) for CWWW / RGBWW lights. Defaults to not changing the color temperature value.
- **color_mode** (*Optional*, :ref:`templatable <config-templatable>`): For lights that support more than one color mode, the color
mode that will be activated. The color mode determines which outputs of the light are active, and which parameters can be used.
This can for example be used to switch between colored and white light. Must be a color mode that is supported by the light.
Valid color modes are:
- ``ON_OFF``: Only on/off control.
- ``BRIGHTNESS``: Only brightness control. Accepts *brightness* parameter.
- ``WHITE``: Single white channel only. Accepts *brightness* and *white* parameters.
- ``COLOR_TEMPERATURE``: Color-temperature controlled white channel. Accepts *brightness* and *color_temperature*
parameters.
- ``COLD_WARM_WHITE``: Cold and warm white channels. Accepts *brightness*, *color_temperature*, *cold_white* and
*warm_white* parameters.
- ``RGB``: RGB color channels. Accepts *brightness*, *color_brightness*, *red*, *green* and *blue* parameters.
- ``RGB_WHITE``: RGB color channels and a separate white channel. Accepts parameters from ``RGB`` and ``WHITE``
color modes.
- ``RGB_COLOR_TEMPERATURE``: RGB color channels and a separate color-temperature controlled white channel. Accepts
parameters from ``RGB`` and ``COLOR_TEMPERATURE`` color modes.
- ``RGB_COLD_WARM_WHITE``: RGB color channels and two separate cold and warm white channels. Accepts parameters
from ``RGB`` and ``COLD_WARM_WHITE`` color modes.
- **brightness** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The master brightness of the light, that
applies to all channels (both color and white) of the light.
- **color_brightness** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The brightness of the color lights. Useful
to control brightness of colored and white lights separately for RGBW lights.
- **red** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The red channel of the light.
- **green** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The green channel of the light.
- **blue** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The blue channel of the light.
- **white** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The brightness of the white channel.
- **color_temperature** (*Optional*, float, :ref:`templatable <config-templatable>`): The color temperature
(in `mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin) of the white channel.
- **cold_white** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The brightness of the cold white channel.
Cannot be used at the same time as *color_temperature*.
- **warm_white** (*Optional*, percentage, :ref:`templatable <config-templatable>`): The brightness of the warm white channel.
Cannot be used at the same time as *color_temperature*.
- **flash_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): If set, will flash the given color
for this period of time and then go back to the previous state.
- **effect** (*Optional*, string, :ref:`templatable <config-templatable>`): If set, will attempt to
start an effect with the given name.
All percentage options accept values in the range ``0%`` to ``100%`` or ``0.0`` to ``1.0``, and default to not changing
the current value (which might be the value from before the light was last turned off). To reset values, explicitly set
them to zero.
.. note::
This action can also be expressed in :ref:`lambdas <config-lambda>`:
@ -161,7 +184,10 @@ Configuration variables:
// set parameters (optional)
call.set_transition_length(1000); // in ms
call.set_brightness(1.0); // 1.0 is full brightness
call.set_rgb(1.0, 1.0, 1.0); // color, 1.0 is fully lit
call.set_color_mode(ColorMode::RGB_COLD_WARM_WHITE);
call.set_rgb(0.5, 0.25, 1.0); // color in RGB order, this example is purple
call.set_cold_white(0.5);
call.set_warm_white(0.75);
call.set_effect("The Effect");
// perform action:
call.perform();
@ -175,8 +201,9 @@ Configuration variables:
.. note::
The master brightness (``brightness``) and separate brightness controls for the color and
white channels (``color_brightness`` and ``white``) are multiplied together. Thus, this will
result in color at 40% brightness and white at 60% brightness:
white channels (``color_brightness``, ``white``, ``cold_white`` and ``warm_white``) are
multiplied together. Thus, this will result in color at 40% brightness and white at 60%
brightness:
.. code-block:: yaml
@ -482,14 +509,21 @@ Configuration variables:
- **name** (*Optional*, string): The name of the effect. Defaults to ``Strobe``.
- **colors** (*Optional*, list): A list of colors to cycle through. Defaults to a quick cycle between ON and OFF.
- **state** (*Optional*, boolean): The ON/OFF state to show. Defaults to ``true``.
- **state** (*Optional*, boolean): The on/off state to show. Defaults to ``true``.
- **color_mode** (*Optional*, ): The color mode of the light. Defaults to the current color mode.
- **brightness** (*Optional*, percentage): The brightness of the light. Defaults to ``100%``.
- **red** (*Optional*, percentage): The percentage that the red color should be on for RGB lights. Defaults to ``100%``.
- **green** (*Optional*, percentage): The percentage that the green color should be on for RGB lights. Defaults to ``100%``.
- **blue** (*Optional*, percentage): The percentage that the blue color should be on for RGB lights. Defaults to ``100%``.
- **white** (*Optional*, percentage): The percentage that the white color should be on for RGBW lights. Defaults to ``100%``.
- **color_brightness** (*Optional*, percentage): The brightness of the RGB lights, if applicable. Defaults to ``100%``.
- **red** (*Optional*, percentage): The red channel of the light, if applicable. Defaults to ``100%``.
- **green** (*Optional*, percentage): The green channel of the light, if applicable. Defaults to ``100%``.
- **blue** (*Optional*, percentage): The blue channel of the light, if applicable. Defaults to ``100%``.
- **white** (*Optional*, percentage): The white channel of the light, if applicable. Defaults to ``100%``.
- **color_temperature** (*Optional*, percentage): The color temperature of the light, if applicable. Defaults to ``100%``.
- **cold_white** (*Optional*, percentage): The cold white channel of the light, if applicable. Defaults to ``100%``.
- **warm_white** (*Optional*, percentage): The warm white channel of the light, if applicable. Defaults to ``100%``.
- **duration** (**Required**, :ref:`config-time`): The duration this color should be active.
See `light.turn_on <light-turn_on_action>` for more information on the various color fields.
Flicker Effect
**************

2
components/light/neopixelbus.rst
View File

@ -1,4 +1,4 @@
Neopixelbus Light
NeoPixelBus Light
=================
.. seo::

29
components/light/rgbw.rst
View File

@ -43,6 +43,21 @@ perceived intensity of different colors will generally vary. This can be done by
pin: D1
max_power: 80%
.. _rgbw_color_interlock:
Color Interlock
---------------
With some LED bulbs, it is not possible to enable the RGB leds at the same time as the white leds, or setting
the RGB channels to maximum whilst wanting a white light will have an undesired hue effect. For these cases a
configuration variable is available that prevents the RGB leds and white leds from being turned on at the same
time: ``color_interlock``.
Setting this option to ``true`` will result in the light having two color modes available, ``RGB`` and ``WHITE``.
When the ``RGB`` color mode is active, the white leds are turned off, and when the ``WHITE`` color mode is active,
the RGB leds are turned off. Switching between these modes can be done from the Home Assistant interface, or by using
the ``color_mode`` option of the :ref:`light control actions <light-turn_on_action>`.
Configuration variables:
------------------------
@ -57,20 +72,6 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Light <config-light>`.
.. _rgbw_color_interlock:
Color Interlock
***************
With some LED bulbs, it is not possible to enable the RGB leds at the same time as the white leds, or setting
the RGB channels to maximum whilst wanting a white light will have an undesired hue effect. For these cases a
configuration variable is available that prevents the RGB leds and white leds from being turned on at the same
time: ``color_interlock``.
Setting this variable to ``true`` will automatically turn off the RGB leds when the white value is non-zero, or
when the color is set to white (equal values for red, green and blue). When a different color is set, or the
color brightness is raised above 0%, the white leds are automatically turned off.
See Also
--------

21
components/light/rgbww.rst
View File

@ -6,8 +6,8 @@ RGBWW Light
:image: rgbw.png
The ``rgbww`` light platform creates an RGBWW (cold white + warm white)
light from 5 :ref:`float output components <output>` (one for each channel). The cold white
and warm white channels will be mixed using the color temperature configuration options.
light from 5 :ref:`float output components <output>` (one for each channel). The cold and warm
white channels can be controlled individually or together, see :ref:`cwww_mixing` for more information.
.. code-block:: yaml
@ -49,6 +49,19 @@ perceived intensity of different colors will generally vary. This can be done by
pin: D1
max_power: 80%
Color Interlock
---------------
With some LED bulbs, it is not possible to enable the RGB leds at the same time as the white leds, or setting
the RGB channels to maximum whilst wanting a white light will have an undesired hue effect. For these cases a
configuration variable is available that prevents the RGB leds and white leds from being turned on at the same
time: ``color_interlock``.
Setting this option to ``true`` will result in the light having two color modes available, ``RGB`` and ``COLD_WARM_WHITE``.
When the ``RGB`` color mode is active, the white leds are turned off, and when the ``COLD_WARM_WHITE`` color mode is active,
the RGB leds are turned off. Switching between these modes can be done from the Home Assistant interface, or by using
the ``color_mode`` option of the :ref:`light control actions <light-turn_on_action>`.
Configuration variables:
------------------------
@ -61,9 +74,9 @@ Configuration variables:
white channel.
- **warm_white** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the warm
white channel.
- **cold_white_color_temperature** (**Required**, float): The color temperate (in
- **cold_white_color_temperature** (*Optional*, float): The color temperature (in
`mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin) of the cold white channel.
- **warm_white_color_temperature** (**Required**, float): The color temperate (in
- **warm_white_color_temperature** (*Optional*, float): The color temperature (in
`mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin) of the warm white channel.
- **constant_brightness** (*Optional*, boolean): When enabled, this will keep the overall brightness of the
cold and warm white channels constant by limiting the combined output to 100% of a single channel. This

6
components/light/tuya.rst
View File

@ -86,10 +86,10 @@ Configuration variables:
- **max_value** (*Optional*, int, default 255): The highest dimmer value allowed. Most dimmers have a
maximum of 255, but dimmers with a maximum of 1000 can also be found. Try what works best.
- **color_temperature_max_value** (*Optional*, int, default 255): The highest color temperature
value allowed. Some ceiling fans have a value of 100 (also for ``max_value``).
- **cold_white_color_temperature** (*Optional*, float): The color temperate (in `mireds
value allowed. Some ceiling fans have a value of 100 (also for `max_value`).
- **cold_white_color_temperature** (*Optional*, float): The color temperature (in `mireds
<https://en.wikipedia.org/wiki/Mired>`__ or Kelvin) of the cold white channel.
- **warm_white_color_temperature** (*Optional*, float): The color temperate (in `mireds
- **warm_white_color_temperature** (*Optional*, float): The color temperature (in `mireds
<https://en.wikipedia.org/wiki/Mired>`__ or Kelvin) of the warm white channel.
- All other options from :ref:`Light <config-light>`.
- At least one of *dimmer_datapoint* or *switch_datapoint* must be provided.