NeoPixelBus Light
CAUTION
ESP32 is no longer supported. The upstream NeoPixelBus library is no longer actively maintained, and it does not build on top of ESP-IDF 6. This platform now works on ESP8266 only.
Replacements on ESP32:
- Clockless lights (WS2811, WS2812, SK6812, etc.) → ESP32 RMT LED Strip or I2S Clockless LED Strip.
- 2-wire SPI lights (DotStar, WS2801, LPD8806, P9813) → SPI LED Strip.
The neopixelbus light platform allows you to create RGB lights
in ESPHome for individually addressable lights like NeoPixel or WS2812.
It is very similar to the Fastled platform. In fact, most addressable lights are supported through both light platforms. The difference is that they use different libraries: while the fastled platform uses the FastLED library, this component uses the NeoPixelBus library internally.
# Example configuration entrylight: - platform: neopixelbus type: GRB variant: WS2811 pin: GPIOXX num_leds: 60 name: "NeoPixel Light"Configuration variables
Section titled “Configuration variables”Base Options:
- num_leds (Required, int): The number of LEDs attached.
Type Options:
-
type (Optional, string): The type of light. This is used to specify if it is an RGBW or RGB light and in which order the colors are. Defaults to
GRB. Change this if you have lights with white channel and/or the colors are in the wrong order. -
variant (Required, string): The chipset of the light.
The following options are supported:
800KBPS(generic option, recommended for chipsets without explicit support)400KBPSWS2811WS2812WS2812XWS2813SK6812TM1814TM1829TM1914APA106LC8812
Additionally the following two-wire chipsets (set
data_pinandclock_pin) are supported:WS2801DotStarLPD6803LPD8806P9813
-
method (Optional, string): The method used to transmit the data. By default, ESPHome will try to use the best method available for this chipset and the given pin. See methods for more information.
-
invert (Optional, boolean): Invert data output, for use with n-type transistors. Defaults to
no.
Pin Options:
Some chipsets have two data pins to connect, others only have one.
If you have one line, only specify pin, otherwise specify both clock_pin and data_pin.
-
pin (Optional, Pin): The pin for the data line of the light.
-
clock_pin (Optional, Pin): The pin for the clock line of the light, for two-wire lights.
-
data_pin (Optional, Pin): The pin for the data line of the light, for two-wire lights.
-
All other options from Light.
WARNING
On ESP8266 it’s highly recommended to connect the light strip to pin GPIO3 to reduce flickering.
Methods
Section titled “Methods”NeoPixelBus supports different methods to transmit the pixel data to the light strip depending on the chipset and pin.
Each of these has their own advantages/disadvantages regarding stability and speed. By default
ESPHome will choose the best one that is available on the device. However, you can override this
by manually supplying the method option.
light: - platform: neopixelbus # ... method: type: esp8266_uart bus: 0 async: falseUse the type configuration variable to select the method used. The additional configuration
settings vary by method:
-
bit_bang: The simplest method. However, it can produce quite a bit of flickering, and so is not recommended for use. Supports pins GPIO0-GPIO15.
-
esp8266_dma: The recommended method for ESP8266s. Only available on pin GPIO3.
-
esp8266_uart: An alternative method for ESP8266s that uses the UART peripheral to send data. Available on pin GPIO1 for bus 0, and GPIO2 for bus 1. Additional options:
-
bus (Optional, int): The UART bus to use. If 0, the logger
baud_rateoption must be set to 0 and logs over USB/serial won’t work. -
async (Optional, boolean): Use an asynchronous transfer. Defaults to
false. If enabled, the logger must be disabled even if bus 1 is used.
-
The following method is available only for two-wire chips (specify data_pin and clock_pin ):
-
spi: Uses the hardware SPI interface to transmit the data. Additional options:
- speed (Optional, int): The frequency to send data with. Defaults to
10MHz. One of40MHz,20MHz,10MHz,5MHz,2MHz,1MHz,500KHz.
On ESP8266 only GPIO13 can be used for
data_pinand only GPIO14 can be used forclock_pin. - speed (Optional, int): The frequency to send data with. Defaults to
The method key also accepts a short-hand syntax consisting of a single value for historic reasons. Usage of
this method is no longer recommended, but documented here for reference purposes. Possible values were:
ESP8266_DMA(foresp8266_dma)ESP8266_UART0(foresp8266_uarton bus 0)ESP8266_UART1(foresp8266_uarton bus 1)ESP8266_ASYNC_UART0(foresp8266_uarton bus 0 with async enabled)ESP8266_ASYNC_UART1(foresp8266_uarton bus 1 with async enabled)BIT_BANG(forbit_bang)