NeoPixelBus 灯光

CAUTION

ESP32 支持在 2026.6 中已弃用。 上游 NeoPixelBus 库不再积极维护，并且不能在 ESP-IDF 6 之上构建。ESP32 支持将在不晚于 2027.1 时移除，并且一旦 ESPHome 迁移到 ESP-IDF 6，可能会更早。ESP8266 不受影响。

ESP32 的迁移路径：

NeoPixelBus 不兼容 ESP-IDF（请使用上述迁移路径）。

neopixelbus 灯光平台允许你在 ESPHome 中为 NeoPixel 或 WS2812 等单独可寻址灯光创建 RGB 灯光。

它与 Fastled 平台非常相似。事实上，大多数可寻址灯光都通过两个灯光平台支持。两者的区别在于它们使用不同的库：fastled 平台使用 FastLED 库，此组件内部使用 NeoPixelBus 库。

# 示例配置条目
light:
  - platform: neopixelbus
    type: GRB
    variant: WS2811
    pin: GPIOXX
    num_leds: 60
    name: "NeoPixel Light"

配置变量

基础选项：

类型选项：

type（可选，string）：灯光的类型。用于指定它是 RGBW 还是 RGB 灯光以及颜色的顺序。默认为 GRB。如果你有带白色通道和/或颜色顺序错误的灯光，请更改此项。
variant（必选，string）：灯光的芯片组。

支持以下选项：
- 800KBPS（通用选项，推荐用于没有明确支持的芯片组）
- 400KBPS
- WS2811
- WS2812
- WS2812X
- WS2813
- SK6812
- TM1814
- TM1829
- TM1914
- APA106
- LC8812
此外支持以下两线芯片组（设置 data_pin 和 clock_pin ）：
- WS2801
- DotStar
- LPD6803
- LPD8806
- P9813
method（可选，string）：用于传输数据的方法。默认情况下，ESPHome 将尝试为此芯片组、ESP 平台和给定引脚使用最佳可用方法。更多信息请参见方法。
invert（可选，boolean）：反转数据输出，用于 n 型晶体管。默认为 no。

引脚选项：

一些芯片组有两个数据引脚需要连接，另一些只有一个。如果你只有一条线，只指定 pin；否则同时指定 clock_pin 和 data_pin。

WARNING

在 ESP8266 上，强烈建议将灯带连接到 GPIO3 引脚以减少闪烁。

NeoPixelBus 支持根据芯片组、ESP 平台和引脚的不同方法，将像素数据传输到灯带。

每种方法在稳定性和速度方面各有优劣。默认情况下 ESPHome 将选择设备上可用的最佳方法。但是，你可以通过手动提供 method 选项来覆盖此行为。

light:
  - platform: neopixelbus
    # ...
    method:
      type: esp8266_uart
      bus: 0
      async: false

使用 type 配置变量选择方法。其他配置设置因方法而异：

bit_bang：最简单的方法，在所有平台上可用。然而，它会产生相当多的闪烁，因此不推荐使用。在 ESP8266 上，支持引脚 GPIO0-GPIO15；在 ESP32 上支持引脚 GPIO0-GPIO31。
esp8266_dma：ESP8266 的推荐方法。仅在引脚 GPIO3 上可用。
esp8266_uart：ESP8266 的替代方法，使用 UART 外设发送数据。在总线 0 的引脚 GPIO1 和总线 1 的引脚 GPIO2 上可用。其他选项：
- bus（可选，int）：要使用的 UART 总线。如果为 0，logger baud_rate 选项必须设为 0，通过 USB/串口输出日志将无法工作。
- async（可选，boolean）：使用异步传输。默认为 false。如果启用，即使使用总线 1，也必须禁用 logger。
esp32_i2s：ESP32 的推荐方法，但在 ESP32-C3 或 ESP32-S3 上不可用。在所有输出引脚上可用。其他选项：
- bus（可选）：要使用的 I2S 总线。ESP32 有总线 0 或 1 可用，但 ESP32-S2 只有总线 0。 0、1、dynamic 之一。
esp32_rmt：ESP32 的替代方法，使用 RMT 外设发送数据。在所有输出引脚上可用。其他选项：
- channel（可选）：要使用的 RMT 通道。ESP32 有通道 0-7，ESP32-C3 为 0-1，ESP32-S2 为 0-3，ESP32-S3 为 0-3。 ESP32 默认为 6，其他 ESP32 变体默认为 1。

以下方法仅适用于双线芯片（指定 data_pin 和 clock_pin ）：

spi：使用硬件 SPI 接口传输数据。在两个 ESP 平台上均可用。其他选项：
- bus（可选，string）：在 ESP32 上可以选择要使用的 SPI 总线。vspi 或 hspi 之一。
- speed（可选，int）：发送数据的频率。默认为 10MHz。 40MHz、20MHz、10MHz、5MHz、2MHz、1MHz、500KHz 之一。
在 ESP8266 上，只有 GPIO13 可用于 data_pin，只有 GPIO14 可用于 clock_pin。

method 键还接受由历史原因组成的单值简写语法。不再推荐使用此方法，但在此记录以供参考。可能的值为：