Light Component

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.

This component restores its state on reboot/reset.

Base Light Configuration

All light configuration schemas inherit these options.

light:
  - platform: ...

Configuration variables:

  • 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 friendly_name 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 light effects to use for this light.

  • gamma_correct (Optional, float): Apply a gamma correction factor to the light channels. Defaults to 2.8.

  • default_transition_length (Optional, Time): The default transition length to use when no transition length is set in the light call. Defaults to 1s.

  • flash_transition_length (Optional, Time): The transition length to use when flash is called. Defaults to 0s.

  • 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_ON - Attempt to restore state and default to ON.

    • RESTORE_INVERTED_DEFAULT_OFF - Attempt to restore state inverted from the previous state and default to OFF.

    • RESTORE_INVERTED_DEFAULT_ON - Attempt to restore state inverted from the previous state and default to ON.

    • RESTORE_AND_OFF - Attempt to restore state but initialize the light as OFF.

    • RESTORE_AND_ON - Attempt to restore state but initialize the light as ON.

    • 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, Action): An automation to perform when the light is turned on. See light.on_turn_on / light.on_turn_off Trigger.

  • on_turn_off (Optional, Action): An automation to perform when the light is turned off. See light.on_turn_on / light.on_turn_off Trigger.

  • on_state (Optional, Action): An automation to perform when the light’s set state is changed. See light.on_state Trigger.

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, ID): The Power Supply Component to connect to this light. When the light is turned on, the power supply will automatically be switched on too.

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.

  • 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.

  • If MQTT enabled, all other options from MQTT Component.

  • If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See Webserver Version 3.

light.toggle Action

This action toggles a light with the given ID when executed.

on_...:
  then:
    - light.toggle:
        id: light_1
    # Shorthand:
    - light.toggle: light_1

Configuration variables:

  • id (Required, ID): The ID of the light.

  • transition_length (Optional, Time, templatable): The length of the transition if the light supports it.

Note

This action can also be expressed in lambdas:

auto call = id(light_1).toggle();
// perform action:
call.perform();

light.turn_on Action

This action turns a light with the given ID on when executed.

on_...:
  then:
    - light.turn_on:
        id: light_1
        brightness: 100%
        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:

  • id (Required, ID): The ID of the light.

  • transition_length (Optional, Time, templatable): The length of the transition if the light supports it.

  • color_mode (Optional, 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, templatable): The master brightness of the light, that applies to all channels (both color and white) of the light.

  • color_brightness (Optional, percentage, templatable): The brightness of the color lights. Useful to control brightness of colored and white lights separately for RGBW lights.

  • red (Optional, percentage, templatable): The red channel of the light.

  • green (Optional, percentage, templatable): The green channel of the light.

  • blue (Optional, percentage, templatable): The blue channel of the light.

  • white (Optional, percentage, templatable): The brightness of the white channel.

  • color_temperature (Optional, float, templatable): The color temperature (in mireds or Kelvin) of the white channel.

  • cold_white (Optional, percentage, templatable): The brightness of the cold white channel. Cannot be used at the same time as color_temperature.

  • warm_white (Optional, percentage, templatable): The brightness of the warm white channel. Cannot be used at the same time as color_temperature.

  • flash_length (Optional, Time, templatable): If set, will flash the given color for this period of time and then go back to the previous state.

  • effect (Optional, string, templatable): If set, will attempt to start an effect with the given name.

All percentage options accept values in the range 0% to 100% or 0.0 to 1.0, and default to not changing the current value (which might be the value from before the light was last turned off). To reset values, explicitly set them to zero.

Note

This action can also be expressed in lambdas:

auto call = id(light_1).turn_on();
// set parameters (optional)
call.set_transition_length(1000); // in ms
call.set_brightness(1.0); // 1.0 is full brightness
call.set_color_mode(ColorMode::RGB_COLD_WARM_WHITE);
call.set_rgb(0.5, 0.25, 1.0); // color in RGB order, this example is purple
call.set_cold_white(0.5);
call.set_warm_white(0.75);
call.set_effect("The Effect");
// perform action:
call.perform();

Shorter example using auto call , call.set_brightness and call.perform.

id(light_1).turn_on().set_brightness(1.0).perform();

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.

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:

- light.turn_on:
    id: light_1
    brightness: 80%
    color_brightness: 50%
    white: 75%

light.turn_off Action

This action turns a light with the given ID off when executed.

on_...:
  then:
    - light.turn_off:
        id: light_1

    # Shorthand
    - light.turn_off: light_1

Configuration variables:

  • id (Required, ID): The ID of the light.

  • transition_length (Optional, Time, templatable): The length of the transition if the light supports it.

Note

This action can also be expressed in lambdas:

auto call = id(light_1).turn_off();
// set parameters (optional)
call.set_transition_length(1000); // in ms
// perform action:
call.perform();

light.control Action

This 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.

on_...:
  then:
    - light.control:
        id: light_1
        state: on

Configuration variables:

  • id (Required, ID): The ID of the light.

  • state (Optional, templatable, boolean): Change the ON/OFF state of the light.

  • All other options from light.turn_on.

light.dim_relative Action

This Action allows you to dim a light that supports brightness by a relative amount.

on_...:
  then:
    # Increases the brightness by 5%
    - light.dim_relative:
        id: light_1
        relative_brightness: 5%

Configuration variables:

  • id (Required, ID): The ID of the light.

  • relative_brightness (Required, templatable, percentage): The relative brightness to dim the light by.

  • transition_length (Optional, Time, 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:

      • CLAMP: Clamp the brightness to the limit range.

      • DO_NOTHING: No dimming if the brightness is outside the limit range.

Note

Example: dimming a light with a button press

binary_sensor:
  - platform: gpio
    # ...
    id: my_binary_sensor
    on_press:
      - while:
          condition:
            binary_sensor.is_on: my_binary_sensor
          then:
            - light.dim_relative:
                id: light_1
                relative_brightness: 5%
                transition_length: 0.1s
                brightness_limits:
                    max_brightness: 90%
            - delay: 0.1s

light.addressable_set Action

This Action allows you to manually set a range of LEDs on an addressable light to a specific color.

on_...:
  - light.addressable_set:
      id: my_light
      range_from: 0
      range_to: 50
      red: 100%
      green: 0%
      blue: 0%

Configuration variables:

  • id (Required, ID): The ID of the addressable light to control.

  • range_from (Optional, 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, 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, templatable, percentage): The brightness to set the color channel to.

  • red (Optional, templatable, percentage): The value to set the red channel to.

  • green (Optional, templatable, percentage): The value to set the green channel to.

  • blue (Optional, templatable, percentage): The value to set the blue channel to.

  • white (Optional, templatable, percentage): The brightness to set the white channel to.

light.is_on / light.is_off Condition

This 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.

# In some trigger:
on_...:
  if:
    condition:
      # Same syntax for is_off
      light.is_on: my_light

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.

light:
  - platform: binary # or any other platform
    # ...
    on_turn_on:
    - logger.log: "Light Turned On!"
    on_turn_off:
    - logger.log: "Light Turned Off!"

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 does not trigger until the light actually achieves the off state.

light:
  - platform: binary # or any other platform
    # ...
    on_state:
    - logger.log: "Light State Changed!"

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.

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:

light:
  - platform: ...
    # ...
    effects:
      # Use default parameters:
      - random:
      # Customize parameters
      - random:
          name: "My Slow Random Effect"
          transition_length: 30s
          update_interval: 30s
      - random:
          name: "My Fast Random Effect"
          transition_length: 4s
          update_interval: 5s

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.

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.

light:
  - platform: ...
    # ...
    effects:
      - pulse:
      - pulse:
          name: "Fast Pulse"
          transition_length: 0.5s
          update_interval: 0.5s
          min_brightness: 0%
          max_brightness: 100%
      - pulse:
          name: "Slow Pulse"
          # transition_length: 1s      # defaults to 1s
          update_interval: 2s
      - pulse:
          name: "Asymmetrical Pulse"
          transition_length:
            on_length: 1s
            off_length: 500ms
          update_interval: 1.5s

Configuration variables:

  • name (Optional, string): The name of the effect. Defaults to Pulse.

  • transition_length (Optional, 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, Time): The duration of the transition when the light is turned on.

    • off_length (Optional, Time): The duration of the transition when the light is turned off.

  • update_interval (Optional, 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.

light:
  - platform: ...
    # ...
    effects:
      - random:
      - random:
          name: Random Effect With Custom Values
          transition_length: 5s
          update_interval: 7s

Configuration variables:

  • name (Optional, string): The name of the effect. Defaults to Random.

  • transition_length (Optional, Time): The duration of each transition to start. Defaults to 5s.

  • update_interval (Optional, Time): The interval with which a new color is selected and transitioned to.

Strobe Effect

This effect cycles through a list of colors with specific durations.

light:
  - platform: ...
    # ...
    effects:
      - strobe:
      - strobe:
          name: Strobe Effect With Custom Values
          colors:
            - state: true
              brightness: 100%
              red: 100%
              green: 90%
              blue: 0%
              duration: 500ms
            - state: false
              duration: 250ms
            - state: true
              brightness: 100%
              red: 0%
              green: 100%
              blue: 0%
              duration: 500ms

Configuration variables:

  • name (Optional, string): The name of the effect. Defaults to Strobe.

  • colors (Optional, list): A list of colors to cycle through. Defaults to a quick cycle between ON and OFF.

    • state (Optional, boolean): The on/off state to show. Defaults to true.

    • color_mode (Optional, string): The color mode of the light. Defaults to the current color mode.

    • brightness (Optional, percentage): The brightness of the light. Defaults to 100%.

    • color_brightness (Optional, percentage): The brightness of the RGB lights, if applicable. Defaults to 100%.

    • red (Optional, percentage): The red channel of the light, if applicable. Defaults to 100%.

    • green (Optional, percentage): The green channel of the light, if applicable. Defaults to 100%.

    • blue (Optional, percentage): The blue channel of the light, if applicable. Defaults to 100%.

    • white (Optional, percentage): The white channel of the light, if applicable. Defaults to 100%.

    • color_temperature (Optional, float): The color temperature (in mireds 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, Time): The duration this color should be active.

    • transition_length (Optional, 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.

Flicker Effect

This effect “hovers” around the active color of the light and flickers each color channel a bit.

light:
  - platform: ...
    # ...
    effects:
      - flicker:
      - flicker:
          name: Flicker Effect With Custom Values
          alpha: 95%
          intensity: 1.5%

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%.

  • intensity (Optional, percentage): The intensity of the flickering, basically the maximum amplitude of the random offsets. Defaults to 1.5%.

Lambda Effect

This effect allows you to write completely custom light effects yourself using lambdas.

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.

light:
  - platform: ...
    # ...
    effects:
      - lambda:
          name: My Custom Effect
          update_interval: 1s
          lambda: |-
            static int state = 0;
            auto call = id(my_light).turn_on();
            // Transition of 1000ms = 1s
            call.set_transition_length(1000);
            if (state == 0) {
              call.set_rgb(1.0, 1.0, 1.0);
            } else if (state == 1) {
              call.set_rgb(1.0, 0.0, 1.0);
            } else if (state == 2) {
              call.set_rgb(0.0, 0.0, 1.0);
            } else {
              call.set_rgb(1.0, 0.0, 0.0);
            }
            call.perform();
            state += 1;
            if (state == 4)
              state = 0;

Configuration variables:

  • name (Required, string): The name of the custom effect.

  • update_interval (Optional, 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, 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.

light:
  - platform: ...
    # ...
    effects:
      - addressable_rainbow:
      - addressable_rainbow:
          name: Rainbow Effect With Custom Values
          speed: 10
          width: 50

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.

light:
  - platform: ...
    # ...
    effects:
      - addressable_color_wipe:
      - addressable_color_wipe:
          name: Color Wipe Effect With Custom Values
          colors:
            - red: 100%
              green: 100%
              blue: 100%
              num_leds: 5
              gradient: true
            - red: 0%
              green: 0%
              blue: 0%
              num_leds: 1
          add_led_interval: 100ms
          reverse: false

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 colors.

    • red (Optional, percentage): The percentage the red color channel should be on. Defaults to 100%.

    • green (Optional, percentage): The percentage the green 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 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.

  • add_led_interval (Optional, 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.

light:
  - platform: ...
    # ...
    effects:
      - addressable_scan:
      - addressable_scan:
          name: Scan Effect With Custom Values
          move_interval: 100ms
          scan_width: 1

Configuration variables:

  • name (Optional, string): The name of the effect. Defaults to Scan.

  • move_interval (Optional, 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.

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.

light:
  - platform: ...
    # ...
    effects:
      - addressable_twinkle:
      - addressable_twinkle:
          name: Twinkle Effect With Custom Values
          twinkle_probability: 5%
          progress_interval: 4ms

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, Time): The interval with which to progress the effect. This affects the duration of a twinkle animation. Defaults to 4ms.

Addressable Random Twinkle Effect

A light effect similar to addressable_twinkle, but using random colors for each twinkle animation.

light:
  - platform: ...
    # ...
    effects:
      - addressable_random_twinkle:
      - addressable_random_twinkle:
          name: Random Twinkle Effect With Custom Values
          twinkle_probability: 5%
          progress_interval: 32ms

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, Time): The interval with which to progress the effect. This affects the duration of a twinkle animation. Defaults to 4ms.

Addressable Fireworks Effect

A light effect for individually-addressable LED strips that randomly sparks some fireworks at random positions and lets the sparkles cascade over the LED strip.

light:
  - platform: ...
    # ...
    effects:
      - addressable_fireworks:
      - addressable_fireworks:
          name: Fireworks Effect With Custom Values
          update_interval: 32ms
          spark_probability: 10%
          use_random_color: false
          fade_out_rate: 120

Configuration variables:

  • name (Optional, string): The name of the effect. Defaults to Fireworks.

  • update_interval (Optional, 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.

  • 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.

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.

light:
  - platform: ...
    # ...
    effects:
      - addressable_flicker:
      - addressable_flicker:
          name: Flicker Effect With Custom Values
          update_interval: 16ms
          intensity: 5%

Configuration variables:

  • name (Optional, string): The name of the effect. Defaults to Addressable Flicker.

  • update_interval (Optional, 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%.

Addressable Lambda Effect

This effect allows you to access each LED individually in a custom light effect.

Available variables in the lambda:

  • it - AddressableLight instance (see API reference for more info).

  • current_color - 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.

    Note

    ESPColor has been migrated to Color. See Color for more information.

light:
- platform: ...
  effects:
    - addressable_lambda:
        name: "My Custom Effect"
        update_interval: 16ms
        lambda: |-
          // it.size() - Number of LEDs
          // it[num] - Access the LED at index num.
          // Set the LED at num to the given r, g, b values
          // it[num] = Color(r, g, b);
          // Get the color at index num (Color instance)
          // it[num].get();

          // Example: Simple color wipe
          for (int i = it.size() - 1; i > 0; i--) {
            it[i] = it[i - 1].get();
          }
          it[0] = Color::random_color();

          // Bonus: use .range() and .all() to set many LEDs without having to write a loop.
          it.range(0, 50) = Color::BLACK;
          it.all().fade_to_black(10);

light:
- platform: ...
  effects:
    - addressable_lambda:
        name: "My Custom Effect"
        update_interval: 16ms
        lambda: |-
          // Static variables keep their value even when
          // stopping and starting the effect again
          static uint16_t progress = 0;

          // normal variables lose their value after each
          // execution - basically after each update_interval
          uint16_t changes = 0;

          // To reset static when stopping and starting the effect
          // again you can use the initial_run variables
          if (initial_run) {
            progress = 0;
            it.all() = Color::BLACK;
            // optionally do a return so nothing happens until the next update_interval
            return;
          }

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 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.

light:
- platform: ...
  id: my_light
  effects:
    - automation:
        name: Custom Automation Effect
        sequence:
          - light.addressable_set:
              id: my_light
              red: 100%
              green: 100%
              blue: 100%
          - delay: 100ms
          - light.addressable_set:
              id: my_light
              range_from: 0
              range_to: 20
              red: 100%
              green: 0%
              blue: 0%

Configuration variables:

  • name (Optional, string): The name of the effect.

  • sequence (Optional, Action): The actions to perform in sequence until the effect is stopped.

E1.31 Effect

This effect enables controlling addressable lights using UDP-based E1.31 protocol.

For Example JINX or Hyperion.NG could be used to control E1.31 enabled ESPHome.

e131:
  method: multicast # default: register E1.31 to Multicast group

light:
  - platform: neopixelbus
    num_leds: 189
    effects:
      - e131:
          universe: 1
          channels: RGB

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.

There are three modes of operation:

  • MONO: this supports 1 channel per LED (luminance), up-to 512 LEDs 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

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.

It is possible to enable multiple light platforms to listen to the same universe concurrently, allowing to replicate the behaviour on multiple strips.

E1.31 Component

The E1.31 Effect requires a component hub for the e131 light effect.

Configuration variables:

  • method (Optional): Listening method, one of multicast or unicast. Defaults to multicast.

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.

Prismatik can be used to control addressable lights via Adalight protocol on ESPHome.

# Example configuration entry
# Disable logging over USB
logger:
  baud_rate: 0

# Adalight requires higher RX buffer size
# to operate without flickering
uart:
  rx_buffer_size: 1024

adalight:

light:
  - platform: neopixelbus
    ...
    effects:
      - adalight:
          # uart_id: additional_uart

Configuration variables:

  • uart_id (Optional, ID): Manually specify the ID of the UART Component if you want to use multiple UART buses.

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.

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.

wled:

light:
  - platform: neopixelbus
    ...
    effects:
      - wled:
          # port: 21324
          # blank_on_start: True
          # sync_group_mask: 0

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.

Note

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.

See Also