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

[light] Add `initial_state` documentation (#4331)

Browse Source 
Co-authored-by: H. Árkosi Róbert <robreg@zsurob.hu>
This commit is contained in:
Keith Burzinski 2024-10-16 17:06:57 -05:00 committed by GitHub
parent ab9da0a1d8
commit 5bf9939729
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 268 additions and 258 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

526
components/light/index.rst
View File

@ -5,11 +5,10 @@ Light Component
:description: Instructions for setting up lights and light effects in ESPHome. :description: Instructions for setting up lights and light effects in ESPHome.
:image: folder-open.svg :image: folder-open.svg
The ``light`` domain in ESPHome lets you create lights that will In ESPHome, ``light`` components allow you to create lights usable from Home Assistant's frontend and have many
automatically be shown in Home Assistant’s frontend and have many features such as colors, transitions and even effects.
features such as RGB colors, transitions, flashing and effects.
This component restores its state on reboot/reset. This component can restore its state on reboot/reset if configured to do so.
.. _config-light: .. _config-light:
@ -24,25 +23,39 @@ All light configuration schemas inherit these options.
- platform: ... - platform: ...
Configuration variables: **Configuration variables:**
- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. - **platform** (**Required**, platform): A light platform. See the following for details:
.. toctree::
:maxdepth: 1
:glob:
*
- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be
specified.
- **name** (*Optional*, string): The name of the light. At least one of **id** and **name** must be specified. - **name** (*Optional*, string): The name of the light. At least one of **id** and **name** must be specified.
.. note:: .. note::
If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and you want the light
you want the light to use that name, you can set ``name: None``. to use that name, you can set ``name: None``.
- **icon** (*Optional*, icon): Manually set the icon to use for the light in the frontend. - **icon** (*Optional*, icon): Manually set the icon to use for the light in the frontend.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light. - **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
- **gamma_correct** (*Optional*, float): Apply a `gamma correction - **gamma_correct** (*Optional*, float): Apply a `gamma correction factor
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ to the light channels. <https://en.wikipedia.org/wiki/Gamma_correction>`__ to the light channels. Defaults to ``2.8``.
Defaults to ``2.8``. - **default_transition_length** (*Optional*, :ref:`config-time`): The default transition length to use when no
- **default_transition_length** (*Optional*, :ref:`config-time`): The default transition length transition length is set in the light call. Defaults to ``1s``.
to use when no transition length is set in the light call. Defaults to ``1s``. - **flash_transition_length** (*Optional*, :ref:`config-time`): The transition length to use when flash is called.
- **flash_transition_length** (*Optional*, :ref:`config-time`): The transition length to use when flash Defaults to ``0s``.
is called. Defaults to ``0s``. - **initial_state** (*Optional*): The initial state the light should be set to on bootup. This state will be applied
when the state is **not** restored based on ``restore_mode`` (below).
- **state** (*Optional*, :ref:`templatable <config-templatable>`, boolean): The ON/OFF state for the light.
- All other options from :ref:`light state <light-state_config>`.
- **restore_mode** (*Optional*): Control how the light attempts to restore state on bootup. - **restore_mode** (*Optional*): Control how the light attempts to restore state on bootup.
- ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore. - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore.
@ -54,35 +67,82 @@ Configuration variables:
- ``ALWAYS_OFF`` (Default) - Always initialize the light as OFF on bootup. - ``ALWAYS_OFF`` (Default) - Always initialize the light as OFF on bootup.
- ``ALWAYS_ON`` - Always initialize the light as ON on bootup. - ``ALWAYS_ON`` - Always initialize the light as ON on bootup.
- **on_turn_on** (*Optional*, :ref:`Action <config-action>`): An automation to perform - **on_turn_on** (*Optional*, :ref:`Action <config-action>`): An automation to perform when the light is turned on. See
when the light is turned on. See :ref:`light-on_turn_on_off_trigger`. :ref:`light-on_turn_on_off_trigger`.
- **on_turn_off** (*Optional*, :ref:`Action <config-action>`): An automation to perform - **on_turn_off** (*Optional*, :ref:`Action <config-action>`): An automation to perform when the light is turned off.
when the light is turned off. See :ref:`light-on_turn_on_off_trigger`. See :ref:`light-on_turn_on_off_trigger`.
- **on_state** (*Optional*, :ref:`Action <config-action>`): An automation to perform - **on_state** (*Optional*, :ref:`Action <config-action>`): An automation to perform when the light's set state is
when the light's set state is changed. See :ref:`light-on_state_trigger`. changed. See :ref:`light-on_state_trigger`.
Additional configuration variables for addressable lights: **Additional configuration variables for addressable lights:**
- **color_correct** (*Optional*, list of float): Apply a color correction to each color channel. - **color_correct** (*Optional*, list of float): Apply a color correction to each color channel. This defines the
This defines the maximum brightness of each channel. For example ``[100%, 50%, 100%]`` would set the maximum brightness of each channel. For example ``[100%, 50%, 100%]`` would set the green channel to be at most at
green channel to be at most at 50% brightness. 50% brightness.
- **power_supply** (*Optional*, :ref:`config-id`): The :doc:`/components/power_supply` to connect to - **power_supply** (*Optional*, :ref:`config-id`): The :doc:`/components/power_supply` to connect to this light. When
this light. When the light is turned on, the power supply will automatically be switched on too. the light is turned on, the power supply will automatically be switched on too.
Advanced options: **Advanced options:**
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without frontend (like Home Assistant). Only specifying an ``id`` without a ``name`` will implicitly set this to true.
a ``name`` will implicitly set this to true.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend, - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Defaults to ``false``.
Defaults to ``false``. - **entity_category** (*Optional*, string): The category of the entity. See `this list
- **entity_category** (*Optional*, string): The category of the entity. <https://developers.home-assistant.io/docs/core/entity/#generic-properties>`__ for a list of available options. Set
See https://developers.home-assistant.io/docs/core/entity/#generic-properties to ``""`` to remove the default entity category.
for a list of available options.
Set to ``""`` to remove the default entity category.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`. - If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 <config-webserver-version-3-options>`. - If Webserver enabled and :ref:`version 3 <config-webserver-version-3-options>` is selected, all other options from
:doc:`/components/web_server`.
.. _light-state_config:
**Light state:**
Some actions/configuration refer to **light state**. A **light state** may consist of any of the following
configuration variables:
- **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. For example, this can 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 primary brightness of the light;
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*.
All percentage options accept values in the range ``0%`` to ``100%`` or ``0.0`` to ``1.0`` and they 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.
Light Automations
-----------------
.. _light-toggle_action: .. _light-toggle_action:
@ -100,11 +160,11 @@ This action toggles a light with the given ID when executed.
# Shorthand: # Shorthand:
- light.toggle: light_1 - light.toggle: light_1
Configuration variables: **Configuration variables:**
- **id** (**Required**, :ref:`config-id`): The ID of the light. - **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 - **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the
if the light supports it. transition if the light supports it.
.. note:: .. note::
@ -133,64 +193,25 @@ This action turns a light with the given ID on when executed.
red: 100% red: 100%
green: 100% green: 100%
blue: 1.0 blue: 1.0
# Templated # Templated
- light.turn_on: - light.turn_on:
id: light_1 id: light_1
brightness: !lambda |- brightness: !lambda |-
// output value must be in range 0 - 1.0 // output value must be in range 0 - 1.0
return id(some_sensor).state / 100.0; return id(some_sensor).state / 100.0;
# Shorthand # Shorthand
- light.turn_on: light_1 - light.turn_on: light_1
Configuration variables: **Configuration variables:**
- **id** (**Required**, :ref:`config-id`): The ID of the light. - **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 - **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the
if the light supports it. transition if the light supports it.
- **color_mode** (*Optional*, :ref:`templatable <config-templatable>`): For lights that support more than one color mode, the color - **flash_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): If set, will flash the
mode that will be activated. The color mode determines which outputs of the light are active, and which parameters can be used. given color for this period of time and then go back to the previous state.
This can for example be used to switch between colored and white light. Must be a color mode that is supported by the light. - **effect** (*Optional*, string, :ref:`templatable <config-templatable>`): If set, will attempt to start an effect
Valid color modes are: with the given name.
- All other options from :ref:`light state <light-state_config>`.
- ``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:: .. note::
@ -219,16 +240,15 @@ them to zero.
.. note:: .. note::
The ``red``, ``green`` and ``blue`` values only control the color of the light, not its The ``red``, ``green`` and ``blue`` values only control the color of the light, not its brightness! If you assign
brightness! If you assign ``50%`` to all RGB channels it will be interpreted as 100% on. ``50%`` to all RGB channels it will be interpreted as 100% on. Only use ``brightness`` or ``color_brightness`` to
Only use ``brightness`` or ``color_brightness`` to control the brightness of the light. control the brightness of the light.
.. note:: .. note::
The master brightness (``brightness``) and separate brightness controls for the color and The master brightness (``brightness``) and separate brightness controls for the color and white channels
white channels (``color_brightness``, ``white``, ``cold_white`` and ``warm_white``) are (``color_brightness``, ``white``, ``cold_white`` and ``warm_white``) are multiplied together. Thus, this will
multiplied together. Thus, this will result in color at 40% brightness and white at 60% result in color at 40% brightness and white at 60% brightness:
brightness:
.. code-block:: yaml .. code-block:: yaml
@ -251,15 +271,14 @@ This action turns a light with the given ID off when executed.
then: then:
- light.turn_off: - light.turn_off:
id: light_1 id: light_1
# Shorthand # Shorthand
- light.turn_off: light_1 - light.turn_off: light_1
Configuration variables: **Configuration variables:**
- **id** (**Required**, :ref:`config-id`): The ID of the light. - **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 - **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the
if the light supports it. transition if the light supports it.
.. note:: .. note::
@ -278,8 +297,8 @@ Configuration variables:
``light.control`` Action ``light.control`` Action
************************ ************************
This :ref:`Action <config-action>` is a generic call to change the state of a light - it This :ref:`Action <config-action>` is a generic call to change the state of a light - it is essentially just a
is essentially just a combination of the turn_on and turn_off calls. combination of the turn_on and turn_off calls.
.. code-block:: yaml .. code-block:: yaml
@ -289,20 +308,18 @@ is essentially just a combination of the turn_on and turn_off calls.
id: light_1 id: light_1
state: on state: on
Configuration variables: **Configuration variables:**
- **id** (**Required**, :ref:`config-id`): The ID of the light. - **id** (**Required**, :ref:`config-id`): The ID of the light.
- **state** (*Optional*, :ref:`templatable <config-templatable>`, boolean): Change the ON/OFF - **state** (*Optional*, :ref:`templatable <config-templatable>`, boolean): Change the ON/OFF state of the light.
state of the light. - All other options from :ref:`light state <light-state_config>`.
- All other options from :ref:`light.turn_on <light-turn_on_action>`.
.. _light-dim_relative_action: .. _light-dim_relative_action:
``light.dim_relative`` Action ``light.dim_relative`` Action
***************************** *****************************
This :ref:`Action <config-action>` allows you to dim a light that supports brightness This :ref:`Action <config-action>` allows you to dim a light that supports brightness by a relative amount.
by a relative amount.
.. code-block:: yaml .. code-block:: yaml
@ -313,17 +330,18 @@ by a relative amount.
id: light_1 id: light_1
relative_brightness: 5% relative_brightness: 5%
Configuration variables: **Configuration variables:**
- **id** (**Required**, :ref:`config-id`): The ID of the light. - **id** (**Required**, :ref:`config-id`): The ID of the light.
- **relative_brightness** (**Required**, :ref:`templatable <config-templatable>`, percentage): - **relative_brightness** (**Required**, :ref:`templatable <config-templatable>`, percentage): The relative brightness
The relative brightness to dim the light by. to dim the light by.
- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the transition. - **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the
transition.
- **brightness_limits** (*Optional*): Limits in the brightness range. - **brightness_limits** (*Optional*): Limits in the brightness range.
- **min_brightness** (*Optional*, percentage): The minimum brightness to dim the light to. Defaults to ``0%``. - **min_brightness** (*Optional*, percentage): The minimum brightness to dim the light to. Defaults to ``0%``.
- **max_brightness** (*Optional*, percentage): The maximum brightness to dim the light to. Defaults to ``100%``. - **max_brightness** (*Optional*, percentage): The maximum brightness to dim the light to. Defaults to ``100%``.
- **limit_mode** (*Optional*): What to do when the current brightness is outside of the limit range. Defaults to ``CLAMP``. - **limit_mode** (*Optional*): What to do when the current brightness is outside of the limit range. Defaults to
Valid limit modes are: ``CLAMP``. Valid limit modes are:
- ``CLAMP``: Clamp the brightness to the limit range. - ``CLAMP``: Clamp the brightness to the limit range.
- ``DO_NOTHING``: No dimming if the brightness is outside the limit range. - ``DO_NOTHING``: No dimming if the brightness is outside the limit range.
@ -357,8 +375,8 @@ Configuration variables:
``light.addressable_set`` Action ``light.addressable_set`` Action
******************************** ********************************
This :ref:`Action <config-action>` allows you to manually set a range of LEDs on an addressable light This :ref:`Action <config-action>` allows you to manually set a range of LEDs on an addressable light to a specific
to a specific color. color.
.. code-block:: yaml .. code-block:: yaml
@ -371,24 +389,20 @@ to a specific color.
green: 0% green: 0%
blue: 0% blue: 0%
Configuration variables: **Configuration variables:**
- **id** (**Required**, :ref:`config-id`): The ID of the addressable light to control. - **id** (**Required**, :ref:`config-id`): The ID of the addressable light to control.
- **range_from** (*Optional*, :ref:`templatable <config-templatable>`, int): The beginning - **range_from** (*Optional*, :ref:`templatable <config-templatable>`, int): The beginning of the range of LEDs to
of the range of LEDs to control, inclusive, using zero-based indexing. Defaults to 0 (the beginning of the strip). control, inclusive, using zero-based indexing. Defaults to 0 (the beginning of the strip).
- **range_to** (*Optional*, :ref:`templatable <config-templatable>`, int): The end of the - **range_to** (*Optional*, :ref:`templatable <config-templatable>`, int): The end of the range of LEDs to control,
range of LEDs to control, inclusive, using zero-based indexing. inclusive, using zero-based indexing. Defaults to the end of the strip (``num_leds`` - 1).
Defaults to the end of the strip (``num_leds`` - 1). - **color_brightness** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The brightness to set the
- **color_brightness** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The brightness to color channel to.
set the color channel to. - **red** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to set the red channel to.
- **red** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to - **green** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to set the green channel to.
set the red channel to. - **blue** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to set the blue channel to.
- **green** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to - **white** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The brightness to set the white channel
set the green channel to. to.
- **blue** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to
set the blue channel to.
- **white** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The brightness to
set the white channel to.
.. _light-is_on_condition: .. _light-is_on_condition:
.. _light-is_off_condition: .. _light-is_off_condition:
@ -396,8 +410,8 @@ Configuration variables:
``light.is_on`` / ``light.is_off`` Condition ``light.is_on`` / ``light.is_off`` Condition
******************************************** ********************************************
This :ref:`Condition <config-condition>` checks if the given light is ON or OFF. OFF means This :ref:`Condition <config-condition>` checks if the given light is ON or OFF. OFF means that the light is completely
that the light is completely OFF, and ON means that the light is emitting at least a bit of light. OFF, and ON means that the light is emitting at least a bit of light.
.. code-block:: yaml .. code-block:: yaml
@ -414,8 +428,8 @@ that the light is completely OFF, and ON means that the light is emitting at lea
``light.on_turn_on`` / ``light.on_turn_off`` Trigger ``light.on_turn_on`` / ``light.on_turn_off`` Trigger
**************************************************** ****************************************************
This trigger is activated each time the light is turned on or off. It is consistent This trigger is activated each time the light is turned on or off. It is consistent with the behavior of the
with the behavior of the ``light.is_on`` and ``light.is_off`` condition above. ``light.is_on`` and ``light.is_off`` condition above.
.. code-block:: yaml .. code-block:: yaml
@ -432,10 +446,9 @@ with the behavior of the ``light.is_on`` and ``light.is_off`` condition above.
``light.on_state`` Trigger ``light.on_state`` Trigger
************************** **************************
This trigger is activated each time the set light state is changed. It is not triggered This trigger is activated each time the set light state is changed. It is not triggered based on current state, but
based on current state, but rather, it triggers on the set state which can differ from rather, it triggers on the set state which can differ from the current state due to transitions. For example, the
the current state due to transitions. For example, the ``light.on_state`` trigger can ``light.on_state`` trigger can be used for immediate action when the light is set to off; while ``light.on_turn_off``
be used for immediate action when the light is set to off; while ``light.on_turn_off``
does not trigger until the light actually achieves the off state. does not trigger until the light actually achieves the off state.
.. code-block:: yaml .. code-block:: yaml
@ -451,13 +464,11 @@ does not trigger until the light actually achieves the off state.
Light Effects Light Effects
------------- -------------
ESPHome also offers a bunch of light effects you can use for your lights. The defaults for the ESPHome has several built-in/pre-defined light effects you can use for your lights. The defaults for the effect
effect parameters are made to work well on their own but of course ESPHome gives you the option to manually change parameters are made to work well on their own, but ESPHome also allows you to manually change these parameters.
these parameters.
With ESPHome's light effects system you're basically creating a bunch of entries for the effects dropdown in Each effect you define in ESPHome will appear as an entry in the effects dropdown for the light in Home Assistant. If
Home Assistant. If you wish to have several variants of the same effect you can of course also create multiple you wish to have several variants of the same effect, you can create multiple entries, each having a unique name:
entries with each having a unique name like so:
.. code-block:: yaml .. code-block:: yaml
@ -479,12 +490,16 @@ entries with each having a unique name like so:
.. note:: .. note::
After setting a light effect, it is possible to reset the in-use effect back to a static light by setting the ``effect`` to ``none`` when it is being called through Home Assistant or directly on the device. After setting a light effect, it is possible to reset the in-use effect back to a static light by setting the
``effect`` to ``none`` when it is being called through Home Assistant or directly on the device.
Pulse Effect Pulse Effect
************ ************
This effect makes a pulsating light. The period can be defined by ``update_interval``, the transition length with ``transition_length``. ``transition_length`` should be set to less than ``update_interval``, setting ``transition_length`` to ``1s`` and ``update_interval`` to ``2s`` will result in a transition from 0% to 100% lasting 1 second, 1 second full light, a transition from 100% to 0% for 1 second and off for 1 second. This effect makes a pulsating light. The period can be defined by ``update_interval``, the transition length with
``transition_length``. ``transition_length`` should be set to less than ``update_interval``, setting
``transition_length`` to ``1s`` and ``update_interval`` to ``2s`` will result in a transition from 0% to 100% lasting
1 second, 1 second full light, a transition from 100% to 0% for 1 second and off for 1 second.
.. code-block:: yaml .. code-block:: yaml
@ -501,7 +516,7 @@ This effect makes a pulsating light. The period can be defined by ``update_inter
max_brightness: 100% max_brightness: 100%
- pulse: - pulse:
name: "Slow Pulse" name: "Slow Pulse"
# transition_length: 1s # defaults to 1s transition_length: 500ms
update_interval: 2s update_interval: 2s
- pulse: - pulse:
name: "Asymmetrical Pulse" name: "Asymmetrical Pulse"
@ -510,23 +525,24 @@ This effect makes a pulsating light. The period can be defined by ``update_inter
off_length: 500ms off_length: 500ms
update_interval: 1.5s update_interval: 1.5s
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. Defaults to ``Pulse``. - **name** (*Optional*, string): The name of the effect. Defaults to ``Pulse``.
- **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. - **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. Defaults to ``1s``. Can be a
Defaults to ``1s``. Can be a single time or split for on and off using these nested options. single time or split for on and off using these nested options.
- **on_length** (*Optional*, :ref:`config-time`): The duration of the transition when the light is turned on. - **on_length** (*Optional*, :ref:`config-time`): The duration of the transition when the light is turned on.
- **off_length** (*Optional*, :ref:`config-time`): The duration of the transition when the light is turned off. - **off_length** (*Optional*, :ref:`config-time`): The duration of the transition when the light is turned off.
- **update_interval** (*Optional*, :ref:`config-time`): The interval when the new transition is started. Defaults to ``1s``. - **update_interval** (*Optional*, :ref:`config-time`): The interval when the new transition is started. Defaults to
``1s``.
- **min_brightness** (*Optional*, percentage): The minimum brightness value. Defaults to ``0%`` - **min_brightness** (*Optional*, percentage): The minimum brightness value. Defaults to ``0%``
- **max_brightness** (*Optional*, percentage): The maximum brightness value. Defaults to ``100%`` - **max_brightness** (*Optional*, percentage): The maximum brightness value. Defaults to ``100%``
Random Effect Random Effect
************* *************
This effect makes a transition (of length ``transition_length``) to a randomly-chosen color and/or brightness (e.g. monochromatic) every ``update_interval``. This effect makes a transition (of length ``transition_length``) to a randomly-chosen color and/or brightness (for
monochromatic) every ``update_interval``.
.. code-block:: yaml .. code-block:: yaml
@ -540,12 +556,12 @@ This effect makes a transition (of length ``transition_length``) to a randomly-c
transition_length: 5s transition_length: 5s
update_interval: 7s update_interval: 7s
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. Defaults to ``Random``. - **name** (*Optional*, string): The name of the effect. Defaults to ``Random``.
- **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition to start. Defaults to ``5s``. - **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition to start. Defaults to ``5s``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval with which a new color is selected and transitioned - **update_interval** (*Optional*, :ref:`config-time`): The interval with which a new color is selected and
to. transitioned to.
Strobe Effect Strobe Effect
************* *************
@ -577,7 +593,7 @@ This effect cycles through a list of colors with specific durations.
blue: 0% blue: 0%
duration: 500ms duration: 500ms
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. Defaults to ``Strobe``. - **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. - **colors** (*Optional*, list): A list of colors to cycle through. Defaults to a quick cycle between ON and OFF.
@ -590,13 +606,14 @@ Configuration variables:
- **green** (*Optional*, percentage): The green 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%``. - **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%``. - **white** (*Optional*, percentage): The white channel of the light, if applicable. Defaults to ``100%``.
- **color_temperature** (*Optional*, float): The color temperature (in `mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin) of the light, if applicable. - **color_temperature** (*Optional*, float): The color temperature (in `mireds <https://en.wikipedia.org/wiki/Mired>`__
or Kelvin) of the light, if applicable.
- **cold_white** (*Optional*, percentage): The cold white channel 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%``. - **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. - **duration** (**Required**, :ref:`config-time`): The duration this color should be active.
- **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. Defaults to ``0s``. - **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. Defaults to ``0s``.
See `light.turn_on <light-turn_on_action>` for more information on the various color fields. See :ref:`light state <light-state_config>` for more information on the various color fields.
Flicker Effect Flicker Effect
************** **************
@ -615,11 +632,11 @@ This effect "hovers" around the active color of the light and flickers each colo
alpha: 95% alpha: 95%
intensity: 1.5% intensity: 1.5%
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. Defaults to ``Flicker``. - **name** (*Optional*, string): The name of the effect. Defaults to ``Flicker``.
- **alpha** (*Optional*, percentage): The percentage that the last color value should affect the light. More - **alpha** (*Optional*, percentage): The percentage that the last color value should affect the light. More or less
or less the "forget-factor" of an exponential moving average. Defaults to ``95%``. the "forget-factor" of an exponential moving average. Defaults to ``95%``.
- **intensity** (*Optional*, percentage): The intensity of the flickering, basically the maximum amplitude of the - **intensity** (*Optional*, percentage): The intensity of the flickering, basically the maximum amplitude of the
random offsets. Defaults to ``1.5%``. random offsets. Defaults to ``1.5%``.
@ -630,7 +647,8 @@ This effect allows you to write completely custom light effects yourself using :
Available variable in the lambda: Available variable in the lambda:
- **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when restarting an effect. - **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when
restarting an effect.
.. code-block:: yaml .. code-block:: yaml
@ -660,20 +678,19 @@ Available variable in the lambda:
if (state == 4) if (state == 4)
state = 0; state = 0;
Configuration variables: **Configuration variables:**
- **name** (**Required**, string): The name of the custom effect. - **name** (**Required**, string): The name of the custom effect.
- **update_interval** (*Optional*, :ref:`config-time`): The interval with which the lambda code is executed. - **update_interval** (*Optional*, :ref:`config-time`): The interval with which the lambda code is executed. A value of
A value of ``0ms`` means that the lambda is always executed, without a cool-down. Defaults to ``0ms``. ``0ms`` means that the lambda is always executed, without a cool-down. Defaults to ``0ms``.
- **lambda** (**Required**, :ref:`lambda <config-lambda>`): The code to execute. ``static`` variables are - **lambda** (**Required**, :ref:`lambda <config-lambda>`): The code to execute. ``static`` variables are especially
especially useful. useful.
Addressable Rainbow Effect Addressable Rainbow Effect
************************** **************************
A light effect for individually-addressable LEDs that creates a moving rainbow over the whole LED strip using A light effect for individually-addressable LEDs that creates a moving rainbow over the whole LED strip using the HSV
the HSV color wheel. color wheel.
.. code-block:: yaml .. code-block:: yaml
@ -687,18 +704,17 @@ the HSV color wheel.
speed: 10 speed: 10
width: 50 width: 50
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. Defaults to ``Rainbow``. - **name** (*Optional*, string): The name of the effect. Defaults to ``Rainbow``.
- **speed** (*Optional*, int): The speed of the effect, unitless. Defaults to ``10``. - **speed** (*Optional*, int): The speed of the effect, unitless. Defaults to ``10``.
- **width** (*Optional*, int): The "width" of a full-scale rainbow, unitless. Defaults to ``50``. - **width** (*Optional*, int): The "width" of a full-scale rainbow, unitless. Defaults to ``50``.
Addressable Color Wipe Effect Addressable Color Wipe Effect
***************************** *****************************
A light effect for individually-addressable LEDs that continuously introduces new colors at the beginning of A light effect for individually-addressable LEDs that continuously introduces new colors at the beginning of the strip
the strip and shifts them forward every ``add_led_interval``. and shifts them forward every ``add_led_interval``.
.. code-block:: yaml .. code-block:: yaml
@ -722,7 +738,7 @@ the strip and shifts them forward every ``add_led_interval``.
add_led_interval: 100ms add_led_interval: 100ms
reverse: false reverse: false
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. Defaults to ``Color Wipe``. - **name** (*Optional*, string): The name of the effect. Defaults to ``Color Wipe``.
- **colors** (*Optional*, list): The colors to shift in at the beginning of the strip. Defaults to shifting in random - **colors** (*Optional*, list): The colors to shift in at the beginning of the strip. Defaults to shifting in random
@ -733,18 +749,20 @@ Configuration variables:
- **blue** (*Optional*, percentage): The percentage the blue color channel should be on. Defaults to ``100%``. - **blue** (*Optional*, percentage): The percentage the blue color channel should be on. Defaults to ``100%``.
- **random** (*Optional*, boolean): If set to ``true``, will overwrite the RGB colors by a new, randomly-chosen - **random** (*Optional*, boolean): If set to ``true``, will overwrite the RGB colors by a new, randomly-chosen
color each time. Defaults to ``false``. color each time. Defaults to ``false``.
- **num_leds** (**Required**, positive int): The number of LEDs of this type to have before transitioning to the next color. If ``gradient`` is true, this will be the number of LEDs over which the color transition will occur. - **num_leds** (**Required**, positive int): The number of LEDs of this type to have before transitioning to the next
- **gradient** (*Optional*, boolean): If ``true`` the current color will transition with a gradient over ``num_leds`` to the next color. Defaults to ``false``. color. If ``gradient`` is true, this will be the number of LEDs over which the color transition will occur.
- **gradient** (*Optional*, boolean): If ``true`` the current color will transition with a gradient over ``num_leds``
to the next color. Defaults to ``false``.
- **add_led_interval** (*Optional*, :ref:`config-time`): The interval with which to shift in new leds at the - **add_led_interval** (*Optional*, :ref:`config-time`): The interval with which to shift in new LEDs at the beginning
beginning of the strip. Defaults to ``100ms``. of the strip. Defaults to ``100ms``.
- **reverse** (*Optional*, boolean): Whether to reverse the direction of the color wipe. Defaults to ``false``. - **reverse** (*Optional*, boolean): Whether to reverse the direction of the color wipe. Defaults to ``false``.
Addressable Scan Effect Addressable Scan Effect
*********************** ***********************
Create a single, fast-moving dot moving back and forth an individually-addressable LED strip. The color is chosen by the Creates a single, fast-moving dot "sliding" back and forth on the LED strip. The color is chosen by the currently
currently active light color. active light color.
.. code-block:: yaml .. code-block:: yaml
@ -758,20 +776,18 @@ currently active light color.
move_interval: 100ms move_interval: 100ms
scan_width: 1 scan_width: 1
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. Defaults to ``Scan``. - **name** (*Optional*, string): The name of the effect. Defaults to ``Scan``.
- **move_interval** (*Optional*, :ref:`config-time`): The interval with which to move the dot/line one LED forward. - **move_interval** (*Optional*, :ref:`config-time`): The interval with which to move the dot/line one LED forward.
Defaults to ``100ms``. Defaults to ``100ms``.
- **scan_width** (*Optional*, int): The number of LEDs to use. - **scan_width** (*Optional*, int): The number of LEDs to use. Defaults to ``1``.
Defaults to ``1``.
Addressable Twinkle Effect Addressable Twinkle Effect
************************** **************************
A light effect for individually-addressable LED strips that randomly chooses some LEDs and let's them bright Randomly chooses LEDs and brightens them for a moment, mimicking stars twinkling in the night sky. The color of the
up for a moment, like a stars twinkling in the night's sky. The color of the pixels will be chosen by the pixels is determined by the current light color.
currently active light color.
.. code-block:: yaml .. code-block:: yaml
@ -785,13 +801,13 @@ currently active light color.
twinkle_probability: 5% twinkle_probability: 5%
progress_interval: 4ms progress_interval: 4ms
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. Defaults to ``Twinkle``. - **name** (*Optional*, string): The name of the effect. Defaults to ``Twinkle``.
- **twinkle_probability** (*Optional*, percentage): The percentage with which, at any time step, a randomly-chosen - **twinkle_probability** (*Optional*, percentage): The percentage with which, at any time step, a randomly-chosen LED
LED should start its twinkle animation. should start its twinkle animation.
- **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This - **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This affects
affects the duration of a twinkle animation. Defaults to ``4ms``. the duration of a twinkle animation. Defaults to ``4ms``.
Addressable Random Twinkle Effect Addressable Random Twinkle Effect
********************************* *********************************
@ -810,14 +826,13 @@ A light effect similar to ``addressable_twinkle``, but using random colors for e
twinkle_probability: 5% twinkle_probability: 5%
progress_interval: 32ms progress_interval: 32ms
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. Defaults to ``Random Twinkle``. - **name** (*Optional*, string): The name of the effect. Defaults to ``Random Twinkle``.
- **twinkle_probability** (*Optional*, percentage): The percentage with which, at any time step, a randomly-chosen - **twinkle_probability** (*Optional*, percentage): The percentage with which, at any time step, a randomly-chosen LED
LED should start its twinkle animation. should start its twinkle animation.
- **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This - **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This affects
affects the duration of a twinkle animation. Defaults to ``4ms``. the duration of a twinkle animation. Defaults to ``4ms``.
Addressable Fireworks Effect Addressable Fireworks Effect
**************************** ****************************
@ -839,15 +854,15 @@ and lets the sparkles cascade over the LED strip.
use_random_color: false use_random_color: false
fade_out_rate: 120 fade_out_rate: 120
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. Defaults to ``Fireworks``. - **name** (*Optional*, string): The name of the effect. Defaults to ``Fireworks``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. - **update_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. Defaults to
Defaults to ``32ms``. ``32ms``.
- **spark_probability** (*Optional*, percentage): The probability to start a new firework spark at a randomly-chosen - **spark_probability** (*Optional*, percentage): The probability to start a new firework spark at a randomly-chosen
LED at any given time step. Defaults to ``10%``. LED at any given time step. Defaults to ``10%``.
- **use_random_color** (*Optional*, boolean): Whether to use random colors for new firework sparks. Defaults to - **use_random_color** (*Optional*, boolean): Whether to use random colors for new firework sparks. Defaults to using
using the currently active light color. the currently active light color.
- **fade_out_rate** (*Optional*, int): The rate with which to fade out the LED strip, unitless. Needs to be carefully - **fade_out_rate** (*Optional*, int): The rate with which to fade out the LED strip, unitless. Needs to be carefully
chosen so that the whole strip doesn't light up forever if the fade out rate is too low or that the firework chosen so that the whole strip doesn't light up forever if the fade out rate is too low or that the firework
sparks do not propagate for a long time. Defaults to ``120``. sparks do not propagate for a long time. Defaults to ``120``.
@ -855,8 +870,8 @@ Configuration variables:
Addressable Flicker Effect Addressable Flicker Effect
************************** **************************
An effect similar to the ``flicker`` effect, but for individually-addressable LED strips. This effect flickers An effect similar to the ``flicker`` effect, but for individually-addressable LED strips. This effect flickers each LED
each LED by its own random amount around the currently active light color. by its own random amount around the currently active light color.
.. code-block:: yaml .. code-block:: yaml
@ -870,11 +885,11 @@ each LED by its own random amount around the currently active light color.
update_interval: 16ms update_interval: 16ms
intensity: 5% intensity: 5%
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. Defaults to ``Addressable Flicker``. - **name** (*Optional*, string): The name of the effect. Defaults to ``Addressable Flicker``.
- **update_interval** (*Optional*, :ref:`config-time`): The time interval for updating the random offsets. - **update_interval** (*Optional*, :ref:`config-time`): The time interval for updating the random offsets. Defaults to
Defaults to ``16ms``. ``16ms``.
- **intensity** (*Optional*, percentage): The intensity of the effect, basically how much the random values can offset - **intensity** (*Optional*, percentage): The intensity of the effect, basically how much the random values can offset
the currently active light color. Defaults to ``5%``. the currently active light color. Defaults to ``5%``.
@ -887,7 +902,8 @@ Available variables in the lambda:
- **it** - :apiclass:`AddressableLight <light::AddressableLight>` instance (see API reference for more info). - **it** - :apiclass:`AddressableLight <light::AddressableLight>` instance (see API reference for more info).
- **current_color** - :apistruct:`ESPColor <light::ESPColor>` instance (see API reference for more info). - **current_color** - :apistruct:`ESPColor <light::ESPColor>` instance (see API reference for more info).
- **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when restarting an effect. - **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when
restarting an effect.
.. note:: .. note::
@ -946,19 +962,17 @@ Available variables in the lambda:
} }
Examples of this API can be found here: Examples of this API can be found
https://github.com/esphome/esphome/blob/dev/esphome/components/light/addressable_light_effect.h `here <https://github.com/esphome/esphome/blob/dev/esphome/components/light/addressable_light_effect.h>`__
(the built-in addressable light effects). (the built-in addressable light effects).
Automation Light Effect Automation Light Effect
*********************** ***********************
Additionally to the ``lambda`` and ``addressable_lambda`` light effects, effects can also In addition to the ``lambda`` and ``addressable_lambda`` light effects, effects can also be created with ESPHome's
be written through ESPHome's :ref:`Automation <automation>` system with the ``automation`` :ref:`Automation <automation>` system with the ``automation`` effect type.
effect type.
The automation given in the ``sequence`` block will be repeatedly executed until the effect The automation given in the ``sequence`` block will be repeatedly executed until the effect is stopped by the user.
is stopped by the user.
.. code-block:: yaml .. code-block:: yaml
@ -983,21 +997,20 @@ is stopped by the user.
green: 0% green: 0%
blue: 0% blue: 0%
Configuration variables: **Configuration variables:**
- **name** (*Optional*, string): The name of the effect. - **name** (*Optional*, string): The name of the effect.
- **sequence** (*Optional*, :ref:`Action <config-action>`): The actions to perform in sequence - **sequence** (*Optional*, :ref:`Action <config-action>`): The actions to perform in sequence until the effect is
until the effect is stopped. stopped.
.. _e131-light-effect: .. _e131-light-effect:
E1.31 Effect E1.31 Effect
************ ************
This effect enables controlling addressable lights using UDP-based This effect enables controlling addressable lights by way of the UDP-based E1.31_ protocol.
E1.31_ protocol.
For Example JINX_ or Hyperion.NG_ could be used to control E1.31_ enabled ESPHome. For example, when enabled, JINX_ or Hyperion.NG_ could be used to control the LEDs connected to the ESPHome device.
.. code-block:: yaml .. code-block:: yaml
@ -1012,11 +1025,11 @@ For Example JINX_ or Hyperion.NG_ could be used to control E1.31_ enabled ESPHom
universe: 1 universe: 1
channels: RGB channels: RGB
Configuration variables: **Configuration variables:**
- **universe** (**Required**, int): The value of universe, between 1 to 512. - **universe** (**Required**, int): The value of universe, between 1 to 512.
- **channels** (*Optional*): The type of data. This is used to specify if it is a ``MONO``, - **channels** (*Optional*): The type of data. This is used to specify if it is a ``MONO``, ``RGB`` or ``RGBW`` light
``RGB`` or ``RGBW`` light and in which order the colors are. Defaults to ``RGB``. and in which order the colors are. Defaults to ``RGB``.
There are three modes of operation: There are three modes of operation:
@ -1024,23 +1037,22 @@ There are three modes of operation:
- ``RGB``: this supports 3 channels per LED (RGB), up-to 170 LEDs (3*170 = 510 bytes) per universe - ``RGB``: this supports 3 channels per LED (RGB), up-to 170 LEDs (3*170 = 510 bytes) per universe
- ``RGBW``: this supports 4 channels per LED (RGBW), up-to 128 LEDs (4*128 = 512 bytes) per universe - ``RGBW``: this supports 4 channels per LED (RGBW), up-to 128 LEDs (4*128 = 512 bytes) per universe
If there's more LEDs than allowed per-universe, additional universe will be used. If there are more LEDs than allowed per universe, an additional universe will be used. In the above example of 189
In the above example of 189 LEDs, first 170 LEDs will be assigned to 1 universe, LEDs, first 170 LEDs will be assigned to universe 1, while the remaining 19 LEDs will be assigned to universe 2.
the rest of 19 LEDs will be automatically assigned to 2 universe.
It is possible to enable multiple light platforms to listen to the same universe concurrently, It is possible to enable multiple light platforms to concurrently listen to the same universe, allowing the behavior
allowing to replicate the behaviour on multiple strips. to be replicated on multiple strips.
E1.31 Component E1.31 Component
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
The :ref:`e131-light-effect` requires a component hub for the ``e131`` light effect. The :ref:`e131-light-effect` requires a component hub for the ``e131`` light effect.
Configuration variables: **Configuration variables:**
- **method** (*Optional*): Listening method, one of ``multicast`` or ``unicast``. Defaults to ``multicast``. - **method** (*Optional*): Listening method, one of ``multicast`` or ``unicast``. Defaults to ``multicast``.
The udp port esphome is listening on is 5568. ESPHome will listen on UDP port ``5568``.
.. _E1.31: https://www.doityourselfchristmas.com/wiki/index.php?title=E1.31_(Streaming-ACN)_Protocol .. _E1.31: https://www.doityourselfchristmas.com/wiki/index.php?title=E1.31_(Streaming-ACN)_Protocol
.. _JINX: http://www.live-leds.de/jinx-v1-3-with-resizable-mainwindow-real-dmx-and-sacne1-31/ .. _JINX: http://www.live-leds.de/jinx-v1-3-with-resizable-mainwindow-real-dmx-and-sacne1-31/
@ -1049,11 +1061,10 @@ The udp port esphome is listening on is 5568.
Adalight Effect Adalight Effect
*************** ***************
This effect enables controlling addressable lights using UART-based This effect enables controlling addressable lights using the serial Adalight_ protocol, allowing the creation of
Adalight_ protocol, allowing to create realtime ambient lighting effects. realtime ambient lighting effects.
Prismatik_ can be used to control addressable lights via Adalight_ protocol Prismatik_ can be used to control addressable lights via Adalight_ protocol on ESPHome.
on ESPHome.
.. code-block:: yaml .. code-block:: yaml
@ -1076,10 +1087,10 @@ on ESPHome.
- adalight: - adalight:
# uart_id: additional_uart # uart_id: additional_uart
Configuration variables: **Configuration variables:**
- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>` if you want - **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>`. Useful if
to use multiple UART buses. you've configured multiple UARTs.
.. _Adalight: https://learn.adafruit.com/adalight-diy-ambient-tv-lighting .. _Adalight: https://learn.adafruit.com/adalight-diy-ambient-tv-lighting
.. _Prismatik: https://github.com/psieg/Lightpack .. _Prismatik: https://github.com/psieg/Lightpack
@ -1087,12 +1098,11 @@ Configuration variables:
WLED Effect WLED Effect
*********** ***********
This effect enables controlling addressable lights using UDP-based This effect enables controlling addressable lights using the `UDP Realtime Control`_ protocol used by WLED_, allowing
`UDP Realtime Control`_ protocol used by WLED_, allowing to create realtime ambient creation of realtime ambient lighting effects.
lighting effects.
Prismatik_ can be used to control addressable lights over network on ESPHome. Prismatik_ and/or LedFx_ can be used to control addressable lights over the network on ESPHome. Use the connection type
It is also possible to use LedFx_ to control the lights. Please use the connection type ``udp`` on the default port and add the Data Prefix ``0201``. ``udp`` on the default port and add the data prefix ``0201``.
.. code-block:: yaml .. code-block:: yaml
@ -1107,19 +1117,25 @@ It is also possible to use LedFx_ to control the lights. Please use the connecti
# blank_on_start: True # blank_on_start: True
# sync_group_mask: 0 # sync_group_mask: 0
Configuration variables: **Configuration variables:**
- **port** (*Optional*, int): The port to run the UDP server on. Defaults to ``21324``. - **port** (*Optional*, int): The port to run the UDP server on. Defaults to ``21324``.
- **blank_on_start** (*Optional*, boolean): Whether or not to blank all LEDs when effect starts. Deaults to ``True``. - **blank_on_start** (*Optional*, boolean): Whether or not to blank all LEDs when effect starts. Deaults to ``True``.
- **sync_group_mask** (*Optional*, int): Used with WLED Notifier. The Sync Group mask value that specifies which WLED Sync Groups to listen to. Defaults to ``0`` (All Sync Groups). Sync Groups 1, 2, 3, 4, 5, 6, 7, 8 use masks 1, 2, 4, 8, 16, 32, 64, 128. Combine mask values to listen to multiple Sync Groups. - **sync_group_mask** (*Optional*, int): Used with WLED Notifier. The Sync Group mask value that specifies which WLED
Sync Groups to listen to. Defaults to ``0`` (All Sync Groups). Sync Groups 1, 2, 3, 4, 5, 6, 7, 8 use masks 1, 2, 4,
8, 16, 32, 64, 128. Combine mask values to listen to multiple Sync Groups.
.. note:: .. note::
You can also set the ``port`` to ``19446`` for compatibility with Hyperion Classic using a You can also set the ``port`` to ``19446`` for compatibility with Hyperion Classic using a UDP device with protocol 0.
UDP device with protocol 0.
Currently the following realtime protocols are supported: The following realtime protocols are supported:
WARLS, DRGB, DRGBW, DNRGB and WLED Notifier.
- WARLS
- DRGB
- DRGBW
- DNRGB
- WLED Notifier
.. _UDP Realtime Control: https://github.com/Aircoookie/WLED/wiki/UDP-Realtime-Control .. _UDP Realtime Control: https://github.com/Aircoookie/WLED/wiki/UDP-Realtime-Control
.. _WLED: https://github.com/Aircoookie/WLED/wiki/UDP-Realtime-Control .. _WLED: https://github.com/Aircoookie/WLED/wiki/UDP-Realtime-Control
@ -1132,9 +1148,3 @@ See Also
- :apiref:`light/light_state.h` - :apiref:`light/light_state.h`
- `WS2812FX library <https://github.com/kitesurfer1404/WS2812FX>`__ by `@kitesurfer1404 <https://github.com/kitesurfer1404>`__ - `WS2812FX library <https://github.com/kitesurfer1404/WS2812FX>`__ by `@kitesurfer1404 <https://github.com/kitesurfer1404>`__
- :ghedit:`Edit` - :ghedit:`Edit`
.. toctree::
:maxdepth: 1
:glob:
*