mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-02-02 23:31:30 +01:00
Document new-style NeoPixelBus methods (#1658)
Co-authored-by: Otto winter <otto@otto-winter.com>
This commit is contained in:
Oxan van Leeuwen
GitHub
parent
b6e44d6206
commit
38aef25e79
@ -10,7 +10,7 @@ in ESPHome for an individually addressable lights like NeoPixel or WS2812.
|
||||
|
||||
It is very similar to the :doc:`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
|
||||
difference is that they use different libraries: while the fastled platform uses
|
||||
the `FastLED <https://github.com/FastLED/FastLED>`__ library, this integration uses
|
||||
the `NeoPixelBus <https://github.com/Makuna/NeoPixelBus/>`__ library internally.
|
||||
|
||||
@ -20,6 +20,7 @@ the `NeoPixelBus <https://github.com/Makuna/NeoPixelBus/>`__ library internally.
|
||||
light:
|
||||
- platform: neopixelbus
|
||||
type: GRB
|
||||
variant: WS2811
|
||||
pin: GPIO23
|
||||
num_leds: 60
|
||||
name: "NeoPixel Light"
|
||||
@ -31,53 +32,135 @@ Configuration variables:
|
||||
|
||||
- **name** (**Required**, string): The name of the light.
|
||||
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
||||
- **num_leds** (**Required**, int): The number of LEDs attached.
|
||||
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
|
||||
|
||||
**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 value and/or the colors are in the wrong order.
|
||||
- **variant** (**Required**, string): The chipset variant. You can read more about these
|
||||
`here <https://github.com/Makuna/NeoPixelBus/wiki/NeoPixelBus-object#neopixel-led-model-specific-methods>`__
|
||||
(some of the info on that page is not entirely correct).
|
||||
One of these values:
|
||||
``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.
|
||||
|
||||
- ``800KBPS``
|
||||
The following options are supported:
|
||||
|
||||
- ``800KBPS`` (generic option, recommended for chipsets without explicit support)
|
||||
- ``400KBPS``
|
||||
- ``WS2811``
|
||||
- ``WS2812``
|
||||
- ``WS2812X``
|
||||
- ``WS2813``
|
||||
- ``SK6812``
|
||||
- ``WS2813`` (same as ``WS2812X``)
|
||||
- ``WS2812`` (same as ``800KBPS``)
|
||||
- ``LC8812`` (same as ``SK6812``)
|
||||
- ``TM1814``
|
||||
- ``TM1829``
|
||||
- ``TM1914``
|
||||
- ``APA106``
|
||||
- ``LC8812``
|
||||
|
||||
- **method** (*Optional*, string): The method to transmit the data with. You can read
|
||||
more about these here: `ESP32 <https://github.com/Makuna/NeoPixelBus/wiki/ESP32-NeoMethods>`__,
|
||||
`ESP8266 <https://github.com/Makuna/NeoPixelBus/wiki/ESP8266-NeoMethods>`__
|
||||
Additionally the following two-wire chipsets (set ``data_pin`` and ``clock_pin``)
|
||||
are supported:
|
||||
|
||||
- ``ESP8266_DMA`` (default for ESP8266, only on pin GPIO3)
|
||||
- ``ESP8266_UART0`` (only on pin GPIO1)
|
||||
- ``ESP8266_UART1`` (only on pin GPIO2)
|
||||
- ``ESP8266_ASYNC_UART0`` (only on pin GPIO1)
|
||||
- ``ESP8266_ASYNC_UART1`` (only on pin GPIO2)
|
||||
- ``ESP32_I2S_0``
|
||||
- ``ESP32_I2S_1`` (default for ESP32)
|
||||
- ``BIT_BANG`` (can flicker a bit)
|
||||
- ``WS2801``
|
||||
- ``DotStar``
|
||||
- ``LPD6803``
|
||||
- ``LPD8806``
|
||||
- ``P9813``
|
||||
|
||||
- **num_leds** (**Required**, int): The number of LEDs attached.
|
||||
- **invert** (*Optional*, boolean): Invert data output, for use with n-type transistor. Defaults to ``no``.
|
||||
- **method** (*Optional*, string): The method used to transmit the data. By default, ESPHome will try to use the best method
|
||||
available for this chipset, ESP platform, and the given pin. See :ref:`methods <neopixelbus-methods>` for more information.
|
||||
|
||||
**Pin Options:** Some chipsets have two data pins to connect, others only have one.
|
||||
- **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** (**Required**, :ref:`config-pin`): The pin for the data line of the light.
|
||||
- **clock_pin** (**Required**, :ref:`config-pin`): The pin for the clock line of the light, for two-pin lights.
|
||||
- **data_pin** (**Required**, :ref:`config-pin`): The pin for the data line of the light, for two-pin lights.
|
||||
- **clock_pin** (**Required**, :ref:`config-pin`): The pin for the clock line of the light, for two-wire lights.
|
||||
- **data_pin** (**Required**, :ref:`config-pin`): The pin for the data line of the light, for two-wire lights.
|
||||
|
||||
**Advanced Options:**
|
||||
|
||||
- All other options from :ref:`Light <config-light>`.
|
||||
|
||||
.. warning::
|
||||
|
||||
On ESP8266 it's highly recommended to connect the light strip to pin
|
||||
GPIO3 to reduce flickering.
|
||||
|
||||
.. _neopixelbus-methods:
|
||||
|
||||
Methods
|
||||
-------
|
||||
|
||||
NeoPixelBus supports different methods to transmit the pixel data to the light strip depending
|
||||
on the chipset, ESP platform 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.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
light:
|
||||
- platform: neopixelbus
|
||||
# ...
|
||||
method:
|
||||
type: esp8266_uart
|
||||
bus: 0
|
||||
async: false
|
||||
|
||||
Use the ``type`` configuration variable to select the method used. The additional configuration
|
||||
settings vary by method:
|
||||
|
||||
- **bit_bang**: The simplest method and available on all platforms. However, it can produce quite a bit of flickering,
|
||||
and so is not recommended for use. On ESP8266, supports pins GPIO0-GPIO15, on ESP32 pins GPIO0-GPIO31.
|
||||
|
||||
- **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_rate`` option 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.
|
||||
|
||||
- **esp32_i2s**: The recommended method for ESP32. Available on all output pins. Additional options:
|
||||
|
||||
- **bus** (*Optional*): The I2S bus to use. The ESP32 has bus 0 or 1 available, but the ESP32-S2 only bus 0.
|
||||
One of ``0``, ``1``, ``dynamic``.
|
||||
|
||||
- **esp32_rmt**: An alternative method for ESP32 that uses the RMT peripheral to send data.
|
||||
Available on all output pins. Additional options:
|
||||
|
||||
- **channel** (*Optional*): The RMT channel to use. The ESP32 has channels 0-7, ESP32-S2 0-3 and ESP32-C3 0-1.
|
||||
Defaults to 6 on ESP32, and 1 on other ESP32 variants.
|
||||
|
||||
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. Available on both ESP platforms.
|
||||
Additional options:
|
||||
|
||||
- **bus** (*Optional*, string): On ESP32s the SPI bus to be used can be selected. One of ``vspi`` and ``hspi``.
|
||||
- **speed** (*Optional*, int): The frequency to send data with. Defaults to ``10MHz``. One of
|
||||
``40MHz``, ``20MHz``, ``10MHz``, ``5MHz``, ``2MHz``, ``1MHz``, ``500KHz``.
|
||||
|
||||
On ESP8266 only GPIO13 can be used for ``data_pin`` and only GPIO14 can be used for ``clock_pin``.
|
||||
|
||||
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`` (for ``esp8266_dma``)
|
||||
- ``ESP8266_UART0`` (for ``esp8266_uart`` on bus 0)
|
||||
- ``ESP8266_UART1`` (for ``esp8266_uart`` on bus 1)
|
||||
- ``ESP8266_ASYNC_UART0`` (for ``esp8266_uart`` on bus 0 with async enabled)
|
||||
- ``ESP8266_ASYNC_UART1`` (for ``esp8266_uart`` on bus 1 with async enabled)
|
||||
- ``ESP32_I2S_0`` (for ``esp32_i2s`` on bus 0)
|
||||
- ``ESP32_I2S_1`` (for ``esp32_i2s`` on bus 1)
|
||||
- ``BIT_BANG`` (for ``bit_bang``)
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user