mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-01-24 22:02:04 +01:00
[light] Add `initial_state` documentation (#4331)
Co-authored-by: H. Árkosi Róbert <robreg@zsurob.hu>
This commit is contained in:
Keith Burzinski
GitHub
parent
ab9da0a1d8
commit
5bf9939729
@ -5,11 +5,10 @@ Light Component
|
||||
:description: Instructions for setting up lights and light effects in ESPHome.
|
||||
:image: folder-open.svg
|
||||
|
||||
The ``light`` domain in ESPHome lets you create lights that will
|
||||
automatically be shown in Home Assistant’s frontend and have many
|
||||
features such as RGB colors, transitions, flashing and effects.
|
||||
In ESPHome, ``light`` components allow you to create lights usable from Home Assistant's frontend and have many
|
||||
features such as colors, transitions and even 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:
|
||||
|
||||
@ -24,25 +23,39 @@ All light configuration schemas inherit these options.
|
||||
- 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.
|
||||
|
||||
.. note::
|
||||
|
||||
If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and
|
||||
you want the light to use that name, you can set ``name: None``.
|
||||
If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and you want the light
|
||||
to use that name, you can set ``name: None``.
|
||||
|
||||
- **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.
|
||||
- **gamma_correct** (*Optional*, float): Apply a `gamma correction
|
||||
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ to the light channels.
|
||||
Defaults to ``2.8``.
|
||||
- **default_transition_length** (*Optional*, :ref:`config-time`): The default transition length
|
||||
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. Defaults to ``0s``.
|
||||
- **gamma_correct** (*Optional*, float): Apply a `gamma correction factor
|
||||
<https://en.wikipedia.org/wiki/Gamma_correction>`__ to the light channels. Defaults to ``2.8``.
|
||||
- **default_transition_length** (*Optional*, :ref:`config-time`): The default transition length 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.
|
||||
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_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_ON`` - Always initialize the light as ON on bootup.
|
||||
|
||||
- **on_turn_on** (*Optional*, :ref:`Action <config-action>`): An automation to perform
|
||||
when the light is turned on. See :ref:`light-on_turn_on_off_trigger`.
|
||||
- **on_turn_off** (*Optional*, :ref:`Action <config-action>`): An automation to perform
|
||||
when the light is turned off. See :ref:`light-on_turn_on_off_trigger`.
|
||||
- **on_state** (*Optional*, :ref:`Action <config-action>`): An automation to perform
|
||||
when the light's set state is changed. See :ref:`light-on_state_trigger`.
|
||||
- **on_turn_on** (*Optional*, :ref:`Action <config-action>`): An automation to perform when the light is turned on. See
|
||||
:ref:`light-on_turn_on_off_trigger`.
|
||||
- **on_turn_off** (*Optional*, :ref:`Action <config-action>`): An automation to perform when the light is turned off.
|
||||
See :ref:`light-on_turn_on_off_trigger`.
|
||||
- **on_state** (*Optional*, :ref:`Action <config-action>`): An automation to perform when the light's set state is
|
||||
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.
|
||||
This defines the maximum brightness of each channel. For example ``[100%, 50%, 100%]`` would set the
|
||||
green channel to be at most at 50% brightness.
|
||||
- **power_supply** (*Optional*, :ref:`config-id`): The :doc:`/components/power_supply` to connect to
|
||||
this light. When the light is turned on, the power supply will automatically be switched on too.
|
||||
- **color_correct** (*Optional*, list of float): Apply a color correction to each color channel. This defines the
|
||||
maximum brightness of each channel. For example ``[100%, 50%, 100%]`` would set the green channel to be at most at
|
||||
50% brightness.
|
||||
- **power_supply** (*Optional*, :ref:`config-id`): The :doc:`/components/power_supply` to connect to this light. When
|
||||
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
|
||||
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
|
||||
a ``name`` will implicitly set this to true.
|
||||
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the
|
||||
frontend (like Home Assistant). Only specifying an ``id`` without 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,
|
||||
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
|
||||
Defaults to ``false``.
|
||||
- **entity_category** (*Optional*, string): The category of the entity.
|
||||
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
|
||||
for a list of available options.
|
||||
Set to ``""`` to remove the default entity category.
|
||||
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Defaults to ``false``.
|
||||
- **entity_category** (*Optional*, string): The category of the entity. See `this list
|
||||
<https://developers.home-assistant.io/docs/core/entity/#generic-properties>`__ 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 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:
|
||||
|
||||
@ -100,11 +160,11 @@ This action toggles a light with the given ID when executed.
|
||||
# Shorthand:
|
||||
- light.toggle: light_1
|
||||
|
||||
Configuration variables:
|
||||
**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.
|
||||
- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the
|
||||
transition if the light supports it.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -133,64 +193,25 @@ This action turns a light with the given ID on when executed.
|
||||
red: 100%
|
||||
green: 100%
|
||||
blue: 1.0
|
||||
|
||||
# Templated
|
||||
- light.turn_on:
|
||||
id: light_1
|
||||
brightness: !lambda |-
|
||||
// output value must be in range 0 - 1.0
|
||||
return id(some_sensor).state / 100.0;
|
||||
|
||||
# Shorthand
|
||||
- light.turn_on: light_1
|
||||
|
||||
Configuration variables:
|
||||
**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.
|
||||
- **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.
|
||||
- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the
|
||||
transition if the light supports it.
|
||||
- **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 other options from :ref:`light state <light-state_config>`.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -219,16 +240,15 @@ them to zero.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``red``, ``green`` and ``blue`` values only control the color of the light, not its
|
||||
brightness! If you assign ``50%`` to all RGB channels it will be interpreted as 100% on.
|
||||
Only use ``brightness`` or ``color_brightness`` to control the brightness of the light.
|
||||
The ``red``, ``green`` and ``blue`` values only control the color of the light, not its brightness! If you assign
|
||||
``50%`` to all RGB channels it will be interpreted as 100% on. Only use ``brightness`` or ``color_brightness`` to
|
||||
control the brightness of the light.
|
||||
|
||||
.. note::
|
||||
|
||||
The master brightness (``brightness``) and separate brightness controls for the color and
|
||||
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:
|
||||
The master brightness (``brightness``) and separate brightness controls for the color and 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
|
||||
|
||||
@ -251,15 +271,14 @@ This action turns a light with the given ID off when executed.
|
||||
then:
|
||||
- light.turn_off:
|
||||
id: light_1
|
||||
|
||||
# Shorthand
|
||||
- light.turn_off: light_1
|
||||
|
||||
Configuration variables:
|
||||
**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.
|
||||
- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the
|
||||
transition if the light supports it.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -278,8 +297,8 @@ Configuration variables:
|
||||
``light.control`` Action
|
||||
************************
|
||||
|
||||
This :ref:`Action <config-action>` is a generic call to change the state of a light - it
|
||||
is essentially just a combination of the turn_on and turn_off calls.
|
||||
This :ref:`Action <config-action>` is a generic call to change the state of a light - it is essentially just a
|
||||
combination of the turn_on and turn_off calls.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -289,20 +308,18 @@ is essentially just a combination of the turn_on and turn_off calls.
|
||||
id: light_1
|
||||
state: on
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **id** (**Required**, :ref:`config-id`): The ID of the light.
|
||||
- **state** (*Optional*, :ref:`templatable <config-templatable>`, boolean): Change the ON/OFF
|
||||
state of the light.
|
||||
- All other options from :ref:`light.turn_on <light-turn_on_action>`.
|
||||
- **state** (*Optional*, :ref:`templatable <config-templatable>`, boolean): Change the ON/OFF state of the light.
|
||||
- All other options from :ref:`light state <light-state_config>`.
|
||||
|
||||
.. _light-dim_relative_action:
|
||||
|
||||
``light.dim_relative`` Action
|
||||
*****************************
|
||||
|
||||
This :ref:`Action <config-action>` allows you to dim a light that supports brightness
|
||||
by a relative amount.
|
||||
This :ref:`Action <config-action>` allows you to dim a light that supports brightness by a relative amount.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -313,17 +330,18 @@ by a relative amount.
|
||||
id: light_1
|
||||
relative_brightness: 5%
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **id** (**Required**, :ref:`config-id`): The ID of the light.
|
||||
- **relative_brightness** (**Required**, :ref:`templatable <config-templatable>`, percentage):
|
||||
The relative brightness to dim the light by.
|
||||
- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the transition.
|
||||
- **relative_brightness** (**Required**, :ref:`templatable <config-templatable>`, percentage): The relative brightness
|
||||
to dim the light by.
|
||||
- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the
|
||||
transition.
|
||||
- **brightness_limits** (*Optional*): Limits in the brightness range.
|
||||
- **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%``.
|
||||
- **limit_mode** (*Optional*): What to do when the current brightness is outside of the limit range. Defaults to ``CLAMP``.
|
||||
Valid limit modes are:
|
||||
- **limit_mode** (*Optional*): What to do when the current brightness is outside of the limit range. Defaults to
|
||||
``CLAMP``. Valid limit modes are:
|
||||
|
||||
- ``CLAMP``: Clamp the brightness to 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
|
||||
********************************
|
||||
|
||||
This :ref:`Action <config-action>` allows you to manually set a range of LEDs on an addressable light
|
||||
to a specific color.
|
||||
This :ref:`Action <config-action>` allows you to manually set a range of LEDs on an addressable light to a specific
|
||||
color.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -371,24 +389,20 @@ to a specific color.
|
||||
green: 0%
|
||||
blue: 0%
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **id** (**Required**, :ref:`config-id`): The ID of the addressable light to control.
|
||||
- **range_from** (*Optional*, :ref:`templatable <config-templatable>`, int): The beginning
|
||||
of the range of LEDs to 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 of LEDs to control, inclusive, using zero-based indexing.
|
||||
Defaults to the end of the strip (``num_leds`` - 1).
|
||||
- **color_brightness** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The brightness to
|
||||
set the color channel to.
|
||||
- **red** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to
|
||||
set the red channel to.
|
||||
- **green** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to
|
||||
set the green channel 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.
|
||||
- **range_from** (*Optional*, :ref:`templatable <config-templatable>`, int): The beginning of the range of LEDs to
|
||||
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 of LEDs to control,
|
||||
inclusive, using zero-based indexing. Defaults to the end of the strip (``num_leds`` - 1).
|
||||
- **color_brightness** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The brightness to set the
|
||||
color channel to.
|
||||
- **red** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to set the red channel to.
|
||||
- **green** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to set the green channel 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_off_condition:
|
||||
@ -396,8 +410,8 @@ Configuration variables:
|
||||
``light.is_on`` / ``light.is_off`` Condition
|
||||
********************************************
|
||||
|
||||
This :ref:`Condition <config-condition>` checks if the given light is ON or OFF. OFF means
|
||||
that the light is completely OFF, and ON means that the light is emitting at least a bit of light.
|
||||
This :ref:`Condition <config-condition>` checks if the given light is ON or OFF. OFF means that the light is completely
|
||||
OFF, and ON means that the light is emitting at least a bit of light.
|
||||
|
||||
.. 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
|
||||
****************************************************
|
||||
|
||||
This trigger is activated each time the light is turned on or off. It is consistent
|
||||
with the behavior of the ``light.is_on`` and ``light.is_off`` condition above.
|
||||
This trigger is activated each time the light is turned on or off. It is consistent with the behavior of the
|
||||
``light.is_on`` and ``light.is_off`` condition above.
|
||||
|
||||
.. 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
|
||||
**************************
|
||||
|
||||
This trigger is activated each time the set light state is changed. It is not triggered
|
||||
based on current state, but rather, it triggers on the set state which can differ from
|
||||
the current state due to transitions. For example, the ``light.on_state`` trigger can
|
||||
be used for immediate action when the light is set to off; while ``light.on_turn_off``
|
||||
This trigger is activated each time the set light state is changed. It is not triggered based on current state, but
|
||||
rather, it triggers on the set state which can differ from the current state due to transitions. For example, the
|
||||
``light.on_state`` trigger can 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.
|
||||
|
||||
.. code-block:: yaml
|
||||
@ -451,13 +464,11 @@ does not trigger until the light actually achieves the off state.
|
||||
Light Effects
|
||||
-------------
|
||||
|
||||
ESPHome also offers a bunch of light effects you can use for your lights. The defaults for the
|
||||
effect parameters are made to work well on their own but of course ESPHome gives you the option to manually change
|
||||
these parameters.
|
||||
ESPHome has several built-in/pre-defined light effects you can use for your lights. The defaults for the effect
|
||||
parameters are made to work well on their own, but ESPHome also allows you to manually change these parameters.
|
||||
|
||||
With ESPHome's light effects system you're basically creating a bunch of entries for the effects dropdown in
|
||||
Home Assistant. If you wish to have several variants of the same effect you can of course also create multiple
|
||||
entries with each having a unique name like so:
|
||||
Each effect you define in ESPHome will appear as an entry in the effects dropdown for the light in Home Assistant. If
|
||||
you wish to have several variants of the same effect, you can create multiple entries, each having a unique name:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -479,12 +490,16 @@ entries with each having a unique name like so:
|
||||
|
||||
.. 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
|
||||
************
|
||||
|
||||
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
|
||||
|
||||
@ -501,7 +516,7 @@ This effect makes a pulsating light. The period can be defined by ``update_inter
|
||||
max_brightness: 100%
|
||||
- pulse:
|
||||
name: "Slow Pulse"
|
||||
# transition_length: 1s # defaults to 1s
|
||||
transition_length: 500ms
|
||||
update_interval: 2s
|
||||
- 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
|
||||
update_interval: 1.5s
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **name** (*Optional*, string): The name of the effect. Defaults to ``Pulse``.
|
||||
- **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition.
|
||||
Defaults to ``1s``. Can be a single time or split for on and off using these nested options.
|
||||
- **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. Defaults to ``1s``. Can be a
|
||||
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.
|
||||
- **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%``
|
||||
- **max_brightness** (*Optional*, percentage): The maximum brightness value. Defaults to ``100%``
|
||||
|
||||
|
||||
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
|
||||
|
||||
@ -540,12 +556,12 @@ This effect makes a transition (of length ``transition_length``) to a randomly-c
|
||||
transition_length: 5s
|
||||
update_interval: 7s
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **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``.
|
||||
- **update_interval** (*Optional*, :ref:`config-time`): The interval with which a new color is selected and transitioned
|
||||
to.
|
||||
- **update_interval** (*Optional*, :ref:`config-time`): The interval with which a new color is selected and
|
||||
transitioned to.
|
||||
|
||||
Strobe Effect
|
||||
*************
|
||||
@ -577,7 +593,7 @@ This effect cycles through a list of colors with specific durations.
|
||||
blue: 0%
|
||||
duration: 500ms
|
||||
|
||||
Configuration variables:
|
||||
**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.
|
||||
@ -590,13 +606,14 @@ Configuration variables:
|
||||
- **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*, 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%``.
|
||||
- **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.
|
||||
- **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
|
||||
**************
|
||||
@ -615,11 +632,11 @@ This effect "hovers" around the active color of the light and flickers each colo
|
||||
alpha: 95%
|
||||
intensity: 1.5%
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **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
|
||||
or less the "forget-factor" of an exponential moving average. Defaults to ``95%``.
|
||||
- **alpha** (*Optional*, percentage): The percentage that the last color value should affect the light. More or less
|
||||
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
|
||||
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:
|
||||
|
||||
- **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
|
||||
|
||||
@ -660,20 +678,19 @@ Available variable in the lambda:
|
||||
if (state == 4)
|
||||
state = 0;
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **name** (**Required**, string): The name of the custom effect.
|
||||
- **update_interval** (*Optional*, :ref:`config-time`): The interval with which the lambda code is executed.
|
||||
A value of ``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
|
||||
especially useful.
|
||||
|
||||
- **update_interval** (*Optional*, :ref:`config-time`): The interval with which the lambda code is executed. A value of
|
||||
``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 especially
|
||||
useful.
|
||||
|
||||
Addressable Rainbow Effect
|
||||
**************************
|
||||
|
||||
A light effect for individually-addressable LEDs that creates a moving rainbow over the whole LED strip using
|
||||
the HSV color wheel.
|
||||
A light effect for individually-addressable LEDs that creates a moving rainbow over the whole LED strip using the HSV
|
||||
color wheel.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -687,18 +704,17 @@ the HSV color wheel.
|
||||
speed: 10
|
||||
width: 50
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **name** (*Optional*, string): The name of the effect. Defaults to ``Rainbow``.
|
||||
- **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``.
|
||||
|
||||
|
||||
Addressable Color Wipe Effect
|
||||
*****************************
|
||||
|
||||
A light effect for individually-addressable LEDs that continuously introduces new colors at the beginning of
|
||||
the strip and shifts them forward every ``add_led_interval``.
|
||||
A light effect for individually-addressable LEDs that continuously introduces new colors at the beginning of the strip
|
||||
and shifts them forward every ``add_led_interval``.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -722,7 +738,7 @@ the strip and shifts them forward every ``add_led_interval``.
|
||||
add_led_interval: 100ms
|
||||
reverse: false
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **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
|
||||
@ -733,18 +749,20 @@ Configuration variables:
|
||||
- **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
|
||||
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.
|
||||
- **gradient** (*Optional*, boolean): If ``true`` the current color will transition with a gradient over ``num_leds`` to the next color. 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.
|
||||
- **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
|
||||
beginning of the strip. Defaults to ``100ms``.
|
||||
- **add_led_interval** (*Optional*, :ref:`config-time`): The interval with which to shift in new LEDs at the beginning
|
||||
of the strip. Defaults to ``100ms``.
|
||||
- **reverse** (*Optional*, boolean): Whether to reverse the direction of the color wipe. Defaults to ``false``.
|
||||
|
||||
Addressable Scan Effect
|
||||
***********************
|
||||
|
||||
Create a single, fast-moving dot moving back and forth an individually-addressable LED strip. The color is chosen by the
|
||||
currently active light color.
|
||||
Creates a single, fast-moving dot "sliding" back and forth on the LED strip. The color is chosen by the currently
|
||||
active light color.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -758,20 +776,18 @@ currently active light color.
|
||||
move_interval: 100ms
|
||||
scan_width: 1
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **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.
|
||||
Defaults to ``100ms``.
|
||||
- **scan_width** (*Optional*, int): The number of LEDs to use.
|
||||
Defaults to ``1``.
|
||||
- **scan_width** (*Optional*, int): The number of LEDs to use. Defaults to ``1``.
|
||||
|
||||
Addressable Twinkle Effect
|
||||
**************************
|
||||
|
||||
A light effect for individually-addressable LED strips that randomly chooses some LEDs and let's them bright
|
||||
up for a moment, like a stars twinkling in the night's sky. The color of the pixels will be chosen by the
|
||||
currently active light color.
|
||||
Randomly chooses LEDs and brightens them for a moment, mimicking stars twinkling in the night sky. The color of the
|
||||
pixels is determined by the current light color.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -785,13 +801,13 @@ currently active light color.
|
||||
twinkle_probability: 5%
|
||||
progress_interval: 4ms
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **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
|
||||
LED should start its twinkle animation.
|
||||
- **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This
|
||||
affects the duration of a twinkle animation. Defaults to ``4ms``.
|
||||
- **twinkle_probability** (*Optional*, percentage): The percentage with which, at any time step, a randomly-chosen LED
|
||||
should start its twinkle animation.
|
||||
- **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This affects
|
||||
the duration of a twinkle animation. Defaults to ``4ms``.
|
||||
|
||||
Addressable Random Twinkle Effect
|
||||
*********************************
|
||||
@ -810,14 +826,13 @@ A light effect similar to ``addressable_twinkle``, but using random colors for e
|
||||
twinkle_probability: 5%
|
||||
progress_interval: 32ms
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **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
|
||||
LED should start its twinkle animation.
|
||||
- **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This
|
||||
affects the duration of a twinkle animation. Defaults to ``4ms``.
|
||||
|
||||
- **twinkle_probability** (*Optional*, percentage): The percentage with which, at any time step, a randomly-chosen LED
|
||||
should start its twinkle animation.
|
||||
- **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This affects
|
||||
the duration of a twinkle animation. Defaults to ``4ms``.
|
||||
|
||||
Addressable Fireworks Effect
|
||||
****************************
|
||||
@ -839,15 +854,15 @@ and lets the sparkles cascade over the LED strip.
|
||||
use_random_color: false
|
||||
fade_out_rate: 120
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **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.
|
||||
Defaults to ``32ms``.
|
||||
- **update_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. Defaults to
|
||||
``32ms``.
|
||||
- **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%``.
|
||||
- **use_random_color** (*Optional*, boolean): Whether to use random colors for new firework sparks. Defaults to
|
||||
using the currently active light color.
|
||||
- **use_random_color** (*Optional*, boolean): Whether to use random colors for new firework sparks. Defaults to using
|
||||
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
|
||||
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``.
|
||||
@ -855,8 +870,8 @@ Configuration variables:
|
||||
Addressable Flicker Effect
|
||||
**************************
|
||||
|
||||
An effect similar to the ``flicker`` effect, but for individually-addressable LED strips. This effect flickers
|
||||
each LED by its own random amount around the currently active light color.
|
||||
An effect similar to the ``flicker`` effect, but for individually-addressable LED strips. This effect flickers each LED
|
||||
by its own random amount around the currently active light color.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -870,11 +885,11 @@ each LED by its own random amount around the currently active light color.
|
||||
update_interval: 16ms
|
||||
intensity: 5%
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **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.
|
||||
Defaults to ``16ms``.
|
||||
- **update_interval** (*Optional*, :ref:`config-time`): The time interval for updating the random offsets. Defaults to
|
||||
``16ms``.
|
||||
- **intensity** (*Optional*, percentage): The intensity of the effect, basically how much the random values can offset
|
||||
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).
|
||||
- **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::
|
||||
|
||||
@ -946,19 +962,17 @@ Available variables in the lambda:
|
||||
}
|
||||
|
||||
|
||||
Examples of this API can be found here:
|
||||
https://github.com/esphome/esphome/blob/dev/esphome/components/light/addressable_light_effect.h
|
||||
Examples of this API can be found
|
||||
`here <https://github.com/esphome/esphome/blob/dev/esphome/components/light/addressable_light_effect.h>`__
|
||||
(the built-in addressable light effects).
|
||||
|
||||
Automation Light Effect
|
||||
***********************
|
||||
|
||||
Additionally to the ``lambda`` and ``addressable_lambda`` light effects, effects can also
|
||||
be written through ESPHome's :ref:`Automation <automation>` system with the ``automation``
|
||||
effect type.
|
||||
In addition to the ``lambda`` and ``addressable_lambda`` light effects, effects can also be created with ESPHome's
|
||||
:ref:`Automation <automation>` system with the ``automation`` effect type.
|
||||
|
||||
The automation given in the ``sequence`` block will be repeatedly executed until the effect
|
||||
is stopped by the user.
|
||||
The automation given in the ``sequence`` block will be repeatedly executed until the effect is stopped by the user.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -983,21 +997,20 @@ is stopped by the user.
|
||||
green: 0%
|
||||
blue: 0%
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **name** (*Optional*, string): The name of the effect.
|
||||
- **sequence** (*Optional*, :ref:`Action <config-action>`): The actions to perform in sequence
|
||||
until the effect is stopped.
|
||||
- **sequence** (*Optional*, :ref:`Action <config-action>`): The actions to perform in sequence until the effect is
|
||||
stopped.
|
||||
|
||||
.. _e131-light-effect:
|
||||
|
||||
E1.31 Effect
|
||||
************
|
||||
|
||||
This effect enables controlling addressable lights using UDP-based
|
||||
E1.31_ protocol.
|
||||
This effect enables controlling addressable lights by way of the UDP-based 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
|
||||
|
||||
@ -1012,11 +1025,11 @@ For Example JINX_ or Hyperion.NG_ could be used to control E1.31_ enabled ESPHom
|
||||
universe: 1
|
||||
channels: RGB
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **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``,
|
||||
``RGB`` or ``RGBW`` light and in which order the colors are. Defaults to ``RGB``.
|
||||
- **channels** (*Optional*): The type of data. This is used to specify if it is a ``MONO``, ``RGB`` or ``RGBW`` light
|
||||
and in which order the colors are. Defaults to ``RGB``.
|
||||
|
||||
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
|
||||
- ``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.
|
||||
In the above example of 189 LEDs, first 170 LEDs will be assigned to 1 universe,
|
||||
the rest of 19 LEDs will be automatically assigned to 2 universe.
|
||||
If there are more LEDs than allowed per universe, an additional universe will be used. In the above example of 189
|
||||
LEDs, first 170 LEDs will be assigned to universe 1, while the remaining 19 LEDs will be assigned to universe 2.
|
||||
|
||||
It is possible to enable multiple light platforms to listen to the same universe concurrently,
|
||||
allowing to replicate the behaviour on multiple strips.
|
||||
It is possible to enable multiple light platforms to concurrently listen to the same universe, allowing the behavior
|
||||
to be replicated on multiple strips.
|
||||
|
||||
E1.31 Component
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
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``.
|
||||
|
||||
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
|
||||
.. _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
|
||||
***************
|
||||
|
||||
This effect enables controlling addressable lights using UART-based
|
||||
Adalight_ protocol, allowing to create realtime ambient lighting effects.
|
||||
This effect enables controlling addressable lights using the serial Adalight_ protocol, allowing the creation of
|
||||
realtime ambient lighting effects.
|
||||
|
||||
Prismatik_ can be used to control addressable lights via Adalight_ protocol
|
||||
on ESPHome.
|
||||
Prismatik_ can be used to control addressable lights via Adalight_ protocol on ESPHome.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -1076,10 +1087,10 @@ on ESPHome.
|
||||
- adalight:
|
||||
# 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
|
||||
to use multiple UART buses.
|
||||
- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>`. Useful if
|
||||
you've configured multiple UARTs.
|
||||
|
||||
.. _Adalight: https://learn.adafruit.com/adalight-diy-ambient-tv-lighting
|
||||
.. _Prismatik: https://github.com/psieg/Lightpack
|
||||
@ -1087,12 +1098,11 @@ Configuration variables:
|
||||
WLED Effect
|
||||
***********
|
||||
|
||||
This effect enables controlling addressable lights using UDP-based
|
||||
`UDP Realtime Control`_ protocol used by WLED_, allowing to create realtime ambient
|
||||
lighting effects.
|
||||
This effect enables controlling addressable lights using the `UDP Realtime Control`_ protocol used by WLED_, allowing
|
||||
creation of realtime ambient lighting effects.
|
||||
|
||||
Prismatik_ can be used to control addressable lights over network on ESPHome.
|
||||
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``.
|
||||
Prismatik_ and/or LedFx_ can be used to control addressable lights over the network on ESPHome. Use the connection type
|
||||
``udp`` on the default port and add the data prefix ``0201``.
|
||||
|
||||
.. 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
|
||||
# sync_group_mask: 0
|
||||
|
||||
Configuration variables:
|
||||
**Configuration variables:**
|
||||
|
||||
- **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``.
|
||||
- **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::
|
||||
|
||||
You can also set the ``port`` to ``19446`` for compatibility with Hyperion Classic using a
|
||||
UDP device with protocol 0.
|
||||
You can also set the ``port`` to ``19446`` for compatibility with Hyperion Classic using a UDP device with protocol 0.
|
||||
|
||||
Currently the following realtime protocols are supported:
|
||||
WARLS, DRGB, DRGBW, DNRGB and WLED Notifier.
|
||||
The following realtime protocols are supported:
|
||||
|
||||
- WARLS
|
||||
- DRGB
|
||||
- DRGBW
|
||||
- DNRGB
|
||||
- WLED Notifier
|
||||
|
||||
.. _UDP Realtime Control: 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`
|
||||
- `WS2812FX library <https://github.com/kitesurfer1404/WS2812FX>`__ by `@kitesurfer1404 <https://github.com/kitesurfer1404>`__
|
||||
- :ghedit:`Edit`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user