灯光组件

在 ESPHome 中，light 组件允许您创建可从 Home Assistant 前端使用的灯光，并具有许多功能，如颜色、过渡甚至效果。

如果配置得当，此组件可以在重启/重置时恢复其状态。

基本灯光配置

所有灯光配置模式都继承这些选项。

light:
  - platform: ...

配置变量

platform (必需, 平台): 一个灯光平台。
id (可选, 字符串): 手动指定用于代码生成的 ID。id 和 name 中必须至少指定一个。
name (可选, 字符串): 灯光的名称。id 和 name 中必须至少指定一个。

NOTE

如果您为设备设置了 friendly_name，并且希望灯光使用该名称，可以设置 name: None。

icon (可选, 图标): 手动设置前端中灯光使用的图标。
effects (可选, 列表): 用于此灯的灯光效果列表。
gamma_correct (可选, 浮点数): 对灯光通道应用伽马校正因子。默认为 2.8。
default_transition_length (可选, 时间): 灯光调用中未设置过渡时间时使用的默认过渡长度。默认为 1s。
flash_transition_length (可选, 时间): 调用闪光时使用的过渡长度。默认为 0s。
initial_state (可选): 启动时灯光应设置的初始状态。当状态不是基于 restore_mode（如下）恢复时，将应用此状态。
- state (可选, 可模板化, 布尔值): 灯光的开/关状态。
- 来自灯光状态的所有其他选项。
restore_mode (可选): 控制灯光在启动时如何尝试恢复状态。
- RESTORE_DEFAULT_OFF - 尝试恢复状态，如果无法恢复则默认为关闭。
- RESTORE_DEFAULT_ON - 尝试恢复状态，默认为开启。
- RESTORE_INVERTED_DEFAULT_OFF - 尝试恢复与之前状态相反的状态，默认为关闭。
- RESTORE_INVERTED_DEFAULT_ON - 尝试恢复与之前状态相反的状态，默认为开启。
- RESTORE_AND_OFF - 尝试恢复状态但将灯光初始化为关闭。
- RESTORE_AND_ON - 尝试恢复状态但将灯光初始化为开启。
- ALWAYS_OFF（默认）- 启动时始终将灯光初始化为关闭。
- ALWAYS_ON - 启动时始终将灯光初始化为开启。
on_turn_on (可选, 动作): 灯光开启时执行自动化。参见 light.on_turn_on / light.on_turn_off 触发器。
on_turn_off (可选, 动作): 灯光关闭时执行自动化。参见 light.on_turn_on / light.on_turn_off 触发器。
on_state (可选, 动作): 灯光的设置状态更改时执行自动化。参见 light.on_state 触发器。

可寻址灯光的附加配置变量：

color_correct (可选, 浮点数列表): 对每个颜色通道应用颜色校正。这定义了每个通道的最大亮度。例如 [100%, 50%, 100%] 会将绿色通道设置为最多 50% 亮度。
power_supply (可选, ID): 要连接到此灯的电源。当灯光开启时，电源也会自动开启。

高级选项：

internal (可选, 布尔值): 将此组件标记为内部。内部组件不会暴露给前端（如 Home Assistant）。仅指定 id 而不指定 name 会隐式将其设置为 true。
disabled_by_default (可选, 布尔值): 如果为 true，则此实体不应添加到任何客户端的前端（通常是 Home Assistant），除非用户手动启用（通过 Home Assistant UI）。默认为 false。
entity_category (可选, 字符串): 实体的类别。有关可用选项列表，请参见此列表。设置为 "" 以删除默认实体类别。
如果启用了 MQTT，来自 MQTT 组件的所有其他选项。
如果启用了 Webserver 并选择了版本 3，来自 Web Server 的所有其他选项。

灯光状态：

某些动作/配置引用灯光状态。灯光状态可以包含以下任何配置变量：

color_mode (可选, 可模板化): 对于支持多种颜色模式的灯光，将激活的颜色模式。颜色模式决定灯光的哪些输出处于活动状态，以及可以使用哪些参数。例如，这可用于在彩色和白光之间切换。必须是灯光支持的颜色模式。有效的颜色模式有：
- ON_OFF : 仅开/关控制。
- BRIGHTNESS : 仅亮度控制。接受 brightness 参数。
- WHITE : 仅单白通道。接受 brightness 和 white 参数。
- COLOR_TEMPERATURE : 色温控制的白通道。接受 brightness 和 color_temperature 参数。
- COLD_WARM_WHITE : 冷白和暖白通道。接受 brightness、color_temperature、cold_white 和 warm_white 参数。
- RGB : RGB 颜色通道。接受 brightness、color_brightness、red、green 和 blue 参数。
- RGB_WHITE : RGB 颜色通道和单独的白通道。接受 RGB 和 WHITE 颜色模式的参数。
- RGB_COLOR_TEMPERATURE : RGB 颜色通道和单独的色温控制白通道。接受 RGB 和 COLOR_TEMPERATURE 颜色模式的参数。
- RGB_COLD_WARM_WHITE : RGB 颜色通道和两个单独的冷白和暖白通道。接受 RGB 和 COLD_WARM_WHITE 颜色模式的参数。
brightness (可选, 百分比, 可模板化): 灯光的主要亮度；应用于灯光的所有通道（颜色和白色）。
color_brightness (可选, 百分比, 可模板化): 彩色灯的亮度。用于分别控制 RGBW 灯的彩色和白光亮度。
red (可选, 百分比, 可模板化): 灯光的红色通道。
green (可选, 百分比, 可模板化): 灯光的绿色通道。
blue (可选, 百分比, 可模板化): 灯光的蓝色通道。
white (可选, 百分比, 可模板化): 白通道的亮度。
color_temperature (可选, 浮点数, 可模板化): 白通道的色温（以mireds或开尔文为单位）。
cold_white (可选, 百分比, 可模板化): 冷白通道的亮度。不能与 color_temperature 同时使用。
warm_white (可选, 百分比, 可模板化): 暖白通道的亮度。不能与 color_temperature 同时使用。

所有百分比选项接受 0% 到 100% 或 0.0 到 1.0 范围内的值，它们默认不更改当前值（可能是灯上次关闭前的值）。要重置值，请将它们显式设置为零。

灯光自动化

`light.toggle` 动作

此动作在执行时切换具有给定 ID 的灯光。

on_...:
  then:
    - light.toggle:
        id: light_1
    # 简写形式:
    - light.toggle: light_1

配置变量：

id (必需, ID): 灯光的 ID。
transition_length (可选, 时间, 可模板化): 如果灯光支持，过渡的长度。

NOTE

此动作也可以用 lambda 表达：

auto call = id(light_1).toggle();
// 执行动作:
call.perform();

`light.turn_on` 动作

此动作在执行时开启具有给定 ID 的灯光。

on_...:
  then:
    - light.turn_on:
        id: light_1
        brightness: 100%
        red: 100%
        green: 100%
        blue: 1.0
    # 模板化
    - light.turn_on:
        id: light_1
        brightness: !lambda |-
          // 输出值必须在 0 - 1.0 范围内
          return id(some_sensor).state / 100.0;
    # 简写形式
    - light.turn_on: light_1

配置变量：

id (必需, ID): 灯光的 ID。
transition_length (可选, 时间, 可模板化): 如果灯光支持，过渡的长度。
flash_length (可选, 时间, 可模板化): 如果设置，将闪烁给定颜色此时间段，然后返回之前的状态。
effect (可选, 字符串, 可模板化): 如果设置，将尝试启动具有给定名称的效果。
来自灯光状态的所有其他选项。

NOTE

此动作也可以用 lambda 表达：

auto call = id(light_1).turn_on();
// 设置参数（可选）
call.set_transition_length(1000); // 以 ms 为单位
call.set_brightness(1.0); // 1.0 是全亮度
call.set_color_mode(ColorMode::RGB_COLD_WARM_WHITE);
call.set_rgb(0.5, 0.25, 1.0); // 按 RGB 顺序的颜色，此示例为紫色
call.set_cold_white(0.5);
call.set_warm_white(0.75);
call.set_effect("The Effect");
// 执行动作:
call.perform();

使用 auto call、call.set_brightness 和 call.perform 的简短示例。

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

NOTE

red、green 和 blue 值只控制灯的颜色，不控制其亮度！如果将 50% 分配给所有 RGB 通道，它将被解释为 100% 开启。仅使用 brightness 或 color_brightness 控制灯光的亮度。

NOTE

主亮度（brightness）和颜色与白通道的独立亮度控制（color_brightness、white、cold_white 和 warm_white）相乘。因此，这将导致颜色亮度为 40%，白色亮度为 60%：

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

`light.turn_off` 动作

此动作在执行时关闭具有给定 ID 的灯光。

on_...:
  then:
    - light.turn_off:
        id: light_1
    # 简写形式
    - light.turn_off: light_1

配置变量：

id (必需, ID): 灯光的 ID。
transition_length (可选, 时间, 可模板化): 如果灯光支持，过渡的长度。

NOTE

此动作也可以用 lambda 表达：

auto call = id(light_1).turn_off();
// 设置参数（可选）
call.set_transition_length(1000); // 以 ms 为单位
// 执行动作:
call.perform();

`light.control` 动作

此动作是更改灯光状态的通用调用 —— 它本质上只是 turn_on 和 turn_off 调用的组合。

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

配置变量：

id (必需, ID): 灯光的 ID。
state (可选, 可模板化, 布尔值): 更改灯光的开/关状态。
来自灯光状态的所有其他选项。

`light.dim_relative` 动作

此动作允许您按相对量调光支持亮度的灯光。

on_...:
  then:
    # 将亮度增加 5%
    - light.dim_relative:
        id: light_1
        relative_brightness: 5%

配置变量：

id (必需, ID): 灯光的 ID。
relative_brightness (必需, 可模板化, 百分比): 调光灯的相对亮度。
transition_length (可选, 时间, 可模板化): 过渡的长度。
brightness_limits (可选): 亮度范围的限制。
- min_brightness (可选, 百分比): 调光灯的最小亮度。默认为 0%。
- max_brightness (可选, 百分比): 调光灯的最大亮度。默认为 100%。
- limit_mode (可选): 当前亮度超出限制范围时要执行的操作。默认为 CLAMP。有效的限制模式有：
  - CLAMP : 将亮度限制在限制范围内。
  - DO_NOTHING : 如果亮度超出限制范围，则不调光。

NOTE

示例：通过按钮按下调光灯

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` 动作

此动作允许您手动将可寻址灯上的一系列 LED 设置为特定颜色。

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

配置变量：

id (必需, ID): 要控制的可寻址灯光的 ID。
range_from (可选, 可模板化, 整数): 要控制的 LED 范围的起始位置，包含，使用零基索引。默认为 0（灯带的开头）。
range_to (可选, 可模板化, 整数): 要控制的 LED 范围的结束位置，包含，使用零基索引。默认为灯带的末尾（num_leds - 1）。
color_brightness (可选, 可模板化, 百分比): 设置颜色通道的亮度。
red (可选, 可模板化, 百分比): 设置红色通道的值。
green (可选, 可模板化, 百分比): 设置绿色通道的值。
blue (可选, 可模板化, 百分比): 设置蓝色通道的值。
white (可选, 可模板化, 百分比): 设置白通道的亮度。

灯光条件

`light.is_on` / `light.is_off` 条件

此条件检查给定的灯光是否为开或关。关意味着灯光完全关闭，开意味着灯光至少发出一点光。

# 在某个触发器中:
on_...:
  if:
    condition:
      # is_off 语法相同
      light.is_on: my_light

灯光触发器

`light.on_turn_on` / `light.on_turn_off` 触发器

此触发器在每次灯光开启或关闭时激活。它与上面的 light.is_on 和 light.is_off 条件的行为一致。

light:
  - platform: binary # 或任何其他平台
    # ...
    on_turn_on:
    - logger.log: "Light Turned On!"
    on_turn_off:
    - logger.log: "Light Turned Off!"

`light.on_state` 触发器

此触发器在每次设置的灯光状态更改时激活。它不是基于当前状态触发，而是根据设置状态触发，由于过渡，设置状态可能与当前状态不同。例如，当灯光设置为关闭时，light.on_state 触发器可用于立即操作；而 light.on_turn_off 直到灯光实际达到关闭状态才触发。

light:
  - platform: binary # 或任何其他平台
    # ...
    on_state:
    - logger.log: "Light State Changed!"

灯光效果

ESPHome 有几个内置/预定义的灯光效果可供您使用。效果参数的默认值可以独立工作，但 ESPHome 也允许您手动更改这些参数。

您在 ESPHome 中定义的每个效果都将作为 Home Assistant 中灯光效果下拉菜单中的一个条目出现。如果您希望同一效果有多个变体，可以创建多个条目，每个都有唯一的名称：

light:
  - platform: ...
    # ...
    effects:
      # 使用默认参数:
      - random:
      # 自定义参数
      - 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

设置灯光效果后，可以通过在通过 Home Assistant 或直接在设备上调用时将 effect 设置为 none 来将正在使用的效果重置为静态灯光。

脉冲效果

此效果使灯光产生脉冲。周期可以由 update_interval 定义，过渡长度由 transition_length 定义。transition_length 应设置为小于 update_interval，将 transition_length 设置为 1s，update_interval 设置为 2s 将导致从 0% 到 100% 的过渡持续 1 秒，全亮 1 秒，从 100% 到 0% 的过渡 1 秒，关闭 1 秒。

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: 500ms
          update_interval: 2s
      - pulse:
          name: "Asymmetrical Pulse"
          transition_length:
            on_length: 1s
            off_length: 500ms
          update_interval: 1.5s

配置变量：

name (可选, 字符串): 效果的名称。默认为 Pulse。
transition_length (可选, 时间): 每次过渡的持续时间。默认为 1s。可以是单个时间，也可以使用以下嵌套选项分开设置开启和关闭。
- on_length (可选, 时间): 灯光开启时过渡的持续时间。
- off_length (可选, 时间): 灯光关闭时过渡的持续时间。
update_interval (可选, 时间): 开始新过渡的间隔。默认为 1s。
min_brightness (可选, 百分比): 最小亮度值。默认为 0%
max_brightness (可选, 百分比): 最大亮度值。默认为 100%

随机效果

此效果每隔 update_interval 过渡（长度为 transition_length）到随机选择的颜色和/或亮度（对于单色灯）。

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

配置变量：

name (可选, 字符串): 效果的名称。默认为 Random。
transition_length (可选, 时间): 每次开始过渡的持续时间。默认为 5s。
update_interval (可选, 时间): 选择新颜色并过渡到该颜色的间隔。

频闪效果

此效果以特定持续时间循环显示颜色列表。

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

配置变量：

name (可选, 字符串): 效果的名称。默认为 Strobe。
colors (可选, 列表): 要循环的颜色列表。默认为开和关之间的快速循环。
- state (可选, 布尔值): 要显示的开/关状态。默认为 true。
- color_mode (可选, 字符串): 灯光的颜色模式。默认为当前颜色模式。
- brightness (可选, 百分比): 灯光的亮度。默认为 100%。
- color_brightness (可选, 百分比): RGB 灯的亮度（如适用）。默认为 100%。
- red (可选, 百分比): 灯光的红色通道（如适用）。默认为 100%。
- green (可选, 百分比): 灯光的绿色通道（如适用）。默认为 100%。
- blue (可选, 百分比): 灯光的蓝色通道（如适用）。默认为 100%。
- white (可选, 百分比): 灯光的白通道（如适用）。默认为 100%。
- color_temperature (可选, 浮点数): 灯光的色温（以mireds或开尔文为单位）（如适用）。
- cold_white (可选, 百分比): 灯光的冷白通道（如适用）。默认为 100%。
- warm_white (可选, 百分比): 灯光的暖白通道（如适用）。默认为 100%。
- duration (必需, 时间): 此颜色应激活的持续时间。
- transition_length (可选, 时间): 每次过渡的持续时间。默认为 0s。

有关各种颜色字段的更多信息，请参见灯光状态。

闪烁效果

此效果对亮度和所有颜色通道应用随机变化，这些变化”悬浮”在灯光的活动颜色周围。默认值模拟温和的蜡烛闪烁，但使用不同的设置，它可以产生微妙的颜色偏移或混乱的闪烁噪声。

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

配置变量：

name (可选, 字符串): 效果的名称。默认为 Flicker。
alpha (可选, 百分比): 控制闪烁有多少”记忆”的平滑因子。高值使闪烁的下一步与其最后一步非常相似，从而平滑变化。低值混合更多新值，导致快速变化。默认为 95%。
intensity (可选, 百分比): 每一步应用的随机变化的幅度。由于变化应用于颜色通道，较高的值产生更明显的偏移。默认为 1.5%。

Lambda 效果

此效果允许您使用 lambda 自己编写完全自定义的灯光效果。

lambda 中可用的变量：

initial_run - 一个布尔值，在 lambda 的第一次执行时为 true。用于在重新启动效果时重置静态变量。

light:
  - platform: ...
    # ...
    effects:
      - lambda:
          name: My Custom Effect
          update_interval: 1s
          lambda: |-
            static int state = 0;
            auto call = id(my_light).turn_on();
            // 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;

配置变量：

name (必需, 字符串): 自定义效果的名称。
update_interval (可选, 时间): lambda 代码执行的间隔。值为 0ms 意味着 lambda 始终执行，没有冷却时间。默认为 0ms。
lambda (必需, lambda): 要执行的代码。static 变量特别有用。

访问效果名称

您可以使用 get_name() 方法访问灯光效果的名称，该方法返回一个 StringRef：

// 获取灯光的所有效果
auto &effects = id(my_light).get_effects();
for (auto *effect : effects) {
  StringRef name = effect->get_name();
  // 与字符串字面量比较
  if (name == "My Custom Effect") {
    ESP_LOGI("light", "Found my effect!");
  }
  // 使用显式大小进行安全日志记录
  ESP_LOGI("light", "Effect: %.*s", (int) name.size(), name.c_str());
}

您还可以使用 get_effect_name() 从灯光状态获取当前活动的效果名称：

// 获取当前活动的效果
StringRef current = id(my_light).get_effect_name();
if (current == "None") {
  ESP_LOGI("light", "No effect active");
} else {
  ESP_LOGI("light", "Active effect: %.*s", (int) current.size(), current.c_str());
}

可寻址彩虹效果

一种用于可单独寻址 LED 的灯光效果，使用 HSV 色轮在整个 LED 灯带上创建移动的彩虹。

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

配置变量：

name (可选, 字符串): 效果的名称。默认为 Rainbow。
speed (可选, 整数): 效果的速度，无单位。默认为 10。
width (可选, 整数): 全尺寸彩虹的”宽度”，无单位。默认为 50。

可寻址颜色擦除效果

一种用于可单独寻址 LED 的灯光效果，每隔 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

配置变量：

name (可选, 字符串): 效果的名称。默认为 Color Wipe。
colors (可选, 列表): 在灯带开头移入的颜色。默认为移入随机颜色。
- red (可选, 百分比): 红色通道应开启的百分比。默认为 100%。
- green (可选, 百分比): 绿色通道应开启的百分比。默认为 100%。
- blue (可选, 百分比): 蓝色通道应开启的百分比。默认为 100%。
- random (可选, 布尔值): 如果设置为 true，将用新的随机选择的颜色覆盖 RGB 颜色。默认为 false。
- num_leds (必需, 正整数): 过渡到下一个颜色之前此类型的 LED 数量。如果 gradient 为 true，这将是颜色过渡发生的 LED 数量。
- gradient (可选, 布尔值): 如果为 true，当前颜色将在 num_leds 上以渐变过渡到下一个颜色。默认为 false。
add_led_interval (可选, 时间): 在灯带开头移入新 LED 的间隔。默认为 100ms。
reverse (可选, 布尔值): 是否反转颜色擦除的方向。默认为 false。

可寻址扫描效果

创建一个在 LED 灯带上前后”滑动”的单个快速移动点。颜色由当前活动的灯光颜色选择。

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

配置变量：

name (可选, 字符串): 效果的名称。默认为 Scan。
move_interval (可选, 时间): 将点/线向前移动一个 LED 的间隔。默认为 100ms。
scan_width (可选, 整数): 要使用的 LED 数量。默认为 1。

可寻址闪烁效果

随机选择 LED 并将其瞬间变亮，模仿夜空中闪烁的星星。像素的颜色由当前灯光颜色决定。

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

配置变量：

name (可选, 字符串): 效果的名称。默认为 Twinkle。
twinkle_probability (可选, 百分比): 在任何时间步骤，随机选择的 LED 应开始其闪烁动画的百分比。
progress_interval (可选, 时间): 推进效果的间隔。这会影响闪烁动画的持续时间。默认为 4ms。

可寻址随机闪烁效果

类似于 addressable_twinkle 的灯光效果，但每次闪烁动画使用随机颜色。

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

配置变量：

name (可选, 字符串): 效果的名称。默认为 Random Twinkle。
twinkle_probability (可选, 百分比): 在任何时间步骤，随机选择的 LED 应开始其闪烁动画的百分比。
progress_interval (可选, 时间): 推进效果的间隔。这会影响闪烁动画的持续时间。默认为 4ms。

可寻址烟花效果

一种用于可单独寻址 LED 灯带的灯光效果，在随机位置随机点燃烟花，让火花在 LED 灯带上级联。

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

配置变量：

name (可选, 字符串): 效果的名称。默认为 Fireworks。
update_interval (可选, 时间): 推进效果的间隔。默认为 32ms。
spark_probability (可选, 百分比): 在任何给定时间步骤在随机选择的 LED 处开始新烟花火花的概率。默认为 10%。
use_random_color (可选, 布尔值): 是否为新烟花火花使用随机颜色。默认为使用当前活动的灯光颜色。
fade_out_rate (可选, 整数): LED 灯带淡出的速率，无单位。需要仔细选择，以免整个灯带如果淡出速率太低会永远亮着，或烟花火花不会传播很长时间。默认为 120。

可寻址闪烁效果

类似于 flicker 效果的效果，但用于可单独寻址的 LED 灯带。此效果使每个 LED 在当前活动的灯光颜色周围以各自的随机量闪烁。

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

配置变量：

name (可选, 字符串): 效果的名称。默认为 Addressable Flicker。
update_interval (可选, 时间): 更新随机偏移的时间间隔。默认为 16ms。
intensity (可选, 百分比): 效果的强度，基本上是随机值可以偏移当前活动灯光颜色的程度。默认为 5%。

可寻址 Lambda 效果

此效果允许您在自定义灯光效果中单独访问每个 LED。

lambda 中可用的变量：

it - API Reference: AddressableLight 实例（更多信息请参见 API 参考）。
current_color - API Reference: ESPColor 实例（更多信息请参见 API 参考）。
initial_run - 一个布尔值，在 lambda 的第一次执行时为 true。用于在重新启动效果时重置静态变量。

NOTE

ESPColor 已迁移到 Color。更多信息请参见 API Reference: Color。

light:
- platform: ...
  effects:
    - addressable_lambda:
        name: "My Custom Effect"
        update_interval: 16ms
        lambda: |-
          // it.size() - LED 数量
          // it[num] - 访问索引 num 处的 LED
          // 将索引 num 处的 LED 设置为给定的 r, g, b 值
          // it[num] = Color(r, g, b);
          // 获取索引 num 处的颜色（Color 实例）
          // it[num].get();

          // 示例：简单的颜色擦除
          for (int i = it.size() - 1; i > 0; i--) {
            it[i] = it[i - 1].get();
          }
          it[0] = Color::random_color();

          // 额外：使用 .range() 和 .all() 设置许多 LED 而无需编写循环
          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 uint16_t progress = 0;

          // 普通变量在每次执行后丢失其值
          // 基本上在每个 update_interval 之后
          uint16_t changes = 0;

          // 要在停止并再次启动效果时重置静态变量
          // 可以使用 initial_run 变量
          if (initial_run) {
            progress = 0;
            it.all() = Color::BLACK;
            // 可选地执行 return，这样在下一个 update_interval 之前不会发生任何事情
            return;
          }

此 API 的示例可以在源代码（内置可寻址灯光效果）中找到。

自动化灯光效果

除了 lambda 和 addressable_lambda 灯光效果外，还可以使用 ESPHome 的自动化系统通过 automation 效果类型创建效果。

sequence 块中给出的自动化将重复执行，直到用户停止效果。

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%

配置变量：

name (可选, 字符串): 效果的名称。
sequence (可选, 动作): 按顺序执行直到效果停止的动作。

E1.31 效果

此效果允许通过基于 UDP 的 E1.31 协议控制可寻址灯光。

例如，启用后，可以使用 JINX 或 Hyperion.NG 来控制连接到 ESPHome 设备的 LED。

e131:
  method: multicast # 默认：将 E1.31 注册到多播组

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

配置变量：

universe (必需, 整数): universe 值，在 1 到 512 之间。
channels (可选): 数据类型。用于指定它是 MONO、RGB 还是 RGBW 灯以及颜色的顺序。默认为 RGB。

有三种操作模式：

MONO: 这支持每个 LED 1 个通道（亮度），每个 universe 最多 512 个 LED
RGB: 这支持每个 LED 3 个通道（RGB），每个 universe 最多 170 个 LED（3*170 = 510 字节）
RGBW: 这支持每个 LED 4 个通道（RGBW），每个 universe 最多 128 个 LED（4*128 = 512 字节）

如果 LED 数量超过每个 universe 允许的数量，将使用额外的 universe。在上面的 189 个 LED 示例中，前 170 个 LED 将分配给 universe 1，而剩余的 19 个 LED 将分配给 universe 2。

可以启用多个灯光平台同时监听同一个 universe，从而允许在多个灯带上复制行为。

E1.31 组件

E1.31 效果需要一个组件集线器用于 e131 灯光效果。

配置变量：

method (可选): 监听方法，multicast 或 unicast 之一。默认为 multicast。

ESPHome 将监听 UDP 端口 5568。

Adalight 效果

此效果允许使用串口 Adalight 协议控制可寻址灯光，从而创建实时环境照明效果。

Prismatik 可用于通过 ESPHome 上的 Adalight 协议控制可寻址灯光。

# 配置示例
# 禁用通过 USB 的日志记录
logger:
  baud_rate: 0

# Adalight 需要更大的 RX 缓冲区大小
# 以无闪烁操作
uart:
  rx_buffer_size: 1024

adalight:

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

配置变量：

uart_id (可选, ID): 手动指定 UART 组件的 ID。如果您配置了多个 UART，这很有用。

WLED 效果

此效果允许使用 UDP Realtime Control WLED 使用的协议控制可寻址灯光，从而创建实时环境照明效果。

Prismatik 和/或 LedFx 可用于在 ESPHome 上通过网络控制可寻址灯光。在默认端口上使用连接类型 udp 并添加数据前缀 0201。

wled:

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

配置变量：

port (可选, 整数): 运行 UDP 服务器的端口。默认为 21324。
blank_on_start (可选, 布尔值): 效果开始时是否清空所有 LED。默认为 True。
sync_group_mask (可选, 整数): 与 WLED Notifier 一起使用。指定要监听哪些 WLED 同步组的同步组掩码值。默认为 0（所有同步组）。同步组 1、2、3、4、5、6、7、8 使用掩码 1、2、4、8、16、32、64、128。组合掩码值以监听多个同步组。

NOTE

您也可以将 port 设置为 19446 以便与使用协议 0 的 UDP 设备的 Hyperion Classic 兼容。

支持以下实时协议：

WARLS
DRGB
DRGBW
DNRGB
WLED Notifier

灯光组件

基本灯光配置

配置变量

灯光自动化

light.toggle 动作

light.turn_on 动作

light.turn_off 动作

light.control 动作

light.dim_relative 动作

light.addressable_set 动作

灯光条件

light.is_on / light.is_off 条件

灯光触发器

light.on_turn_on / light.on_turn_off 触发器

light.on_state 触发器

灯光效果

脉冲效果

随机效果

频闪效果

闪烁效果

Lambda 效果

访问效果名称

可寻址彩虹效果

可寻址颜色擦除效果

可寻址扫描效果

可寻址闪烁效果

可寻址随机闪烁效果

可寻址烟花效果

可寻址闪烁效果

可寻址 Lambda 效果

自动化灯光效果

E1.31 效果

E1.31 组件

Adalight 效果

WLED 效果

另见

`light.toggle` 动作

`light.turn_on` 动作

`light.turn_off` 动作

`light.control` 动作

`light.dim_relative` 动作

`light.addressable_set` 动作

`light.is_on` / `light.is_off` 条件

`light.on_turn_on` / `light.on_turn_off` 触发器

`light.on_state` 触发器