Color mode documentation (#1328)
This commit is contained in:
Oxan van Leeuwen
Jesse Hills
parent
4fa7131172
commit
4088388004
|
|
@ -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;
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
--------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
**************
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
Neopixelbus Light
|
||||
NeoPixelBus Light
|
||||
=================
|
||||
|
||||
.. seo::
|
||||
|
|
|
|||
|
|
@ -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
|
||||
--------
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue