Makuna/NeoPixelBus
1
0
Fork 1
mirror of https://github.com/Makuna/NeoPixelBus.git synced 2025-08-06 12:24:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

Updated ESP8266 NeoMethods (markdown)

Michael Miller
2023-04-03 16:33:01 -07:00
parent 859e61969d
commit 11256a2cfd
1 changed files with 23 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
ESP8266-NeoMethods.md

@@ -1,22 +1,22 @@
⚠️ **IMPORTANT** ⚠️
The ESP8266 requires hardware support to be able to reliably send the data stream. Due to this and the restrictions on which pins are used by each hardware peripheral, only I/O pins GPIO1, GPIO2, and GPIO3 can be used. The Pin argument is ignored and can be omitted.
The ESP8266 requires hardware support to be able to reliably send the data stream. While a bit bang method is provided, it is not recommended.
Due to this and the restrictions on which pins are used by each hardware peripheral, only I/O pins GPIO1, GPIO2, and GPIO3 can be used. The Pin argument is ignored and can be omitted.
The **DMA** methods will use **GPIO3**.
The **UART1** methods will use **GPIO2**.
The **UART0** methods will use **GPIO1**.
**NOTE:** All non-specifically named methods like NeoWs2812Method or NeoSk6812Method will use the DMA by default.
## NeoEsp8266Dma800KbpsMethod
The NeoEsp8266Dma800KbpsMethod is the underlying method that gets used if you use Neo800KbpsMethod on ESP8266 platforms. There should be no need to use it directly.
The NeoEsp8266Dma800KbpsMethod only supports the RXD0/GPIO3 pin. The Pin argument is omitted. See other ESP8266 methods below if you don't have this pin available.
NOTE: Due to the varied board layouts for ESP8266, even though the pin maybe exposed, it may not be usable due to some custom feature on the board you use. If you find it not working, you should review the hardware schematic of your board and confirm the pin is not used for other purposes that interferes with it being used for NeoPixelBus.
This method uses very little CPU for actually sending the data to NeoPixels but it requires an extra buffer for the DMA to read from. Thus there is a trade off of CPU use versus memory use. The extra buffer needed is four times the size of the primary pixel buffer.
All methods for the ESP8266 platform will follow this template for the methods name. The LED names are the same from the simple names and will not be listed in full below as we will focus on the hardware details on this page.
It also requires the use of the RDX0/GPIO3 pin. The normal feature of this pin is the "Serial" receive. Using this DMA method will not allow you to receive serial from the primary Serial object; but it will not stop you from sending output like this...
"NeoEsp8266\<insert hardware detail\>\<insert LED name\>Method"
## DMA (I2S)
The I2S hardware is used to send the data. This method uses very little CPU for actually sending the data to NeoPixels but it requires an extra buffer for the I2S DMA to read from. Thus, there is a tradeoff of CPU use versus memory use. The extra buffer needed is four times the size of the primary pixel buffer. Since the ESP8266 only supports I2S on the RXD0/GPIO3 pin. The Pin argument can be omitted when you construct a NeoPixelBus.
* Dma - An example would be NeoEsp8266**Dma**Ws2812xMethod.
NOTE: The DMA uses RDX0/GPIO3 pin and the normal feature of this pin is the "Serial" receive, you will not be able to recieve on Serial the primary serial object. But it will not stop you from sending output like this...
```
serial.println("I can still debug using serial println");
```
@@ -31,76 +31,29 @@ For more details on Serial and pins, refer to the [ESP8266 Arduino Reference](ht
_Thanks to g3gg0.de for porting the initial DMA support from the original which led to this work. The original was located at [github/cnlohr/esp8266ws2812i2s](https://github.com/cnlohr/esp8266ws2812i2s). The current work is no longer based on that but it gave me the direction I needed to provide a solution._
## NeoEsp8266Dma400KbpsMethod
Same as NeoEsp8266Dma800KbpsMethod but running at the older and slower data rate.
The NeoEsp8266Dma400KbpsMethod is the underlying method that gets used if you use Neo400KbpsMethod on ESP8266 platforms. There should be no need to use it directly.
## NeoEsp8266DmaWs2812xMethod & NeoEsp8266DmaWs2813Method
Same as NeoEsp8266Dma800KbpsMethod. The name is only more specific but they all use the longer delay as required by these chips.
## NeoEsp8266Uart1800KbpsMethod & NeoEsp8266Uart0800KbpsMethod
Use this instead of Neo800KbpsMethod to force your sketch to use the UART to send data.
NeoEsp8266Uart1800KbpsMethod only supports the TXD1/GPIO2 pin. NeoEsp8266Uart0800KbpsMethod only supports the TXD0/GPIO1 pin. The Pin argument is ignored and can be omitted.
NOTE: Due to the varied board layouts for ESP8266, even though the pin may be exposed, it may not be usable due to some custom feature on the board you use. If you find it not working, you should review the hardware schematic of your board and confirm the pin is not used for other purposes that interferes with it being used for NeoPixelBus.
These methods use the CPU to manage a small hardware-managed UART buffer to send the data to the NeoPixels. Thus, it requires more CPU overhead than the DMA method, but it does NOT require an extra buffer.
## UART
These methods use the CPU to manage a small hardware managed UART buffer to send the data to the NeoPixels. Thus, it requires more CPU overhead than the DMA method, but it does NOT require an extra buffer.
* Uart0 - Uses UART 0. An example would be NeoEsp8266**Uart0**Ws2812xMethod. Supports only TXD0/GPIO1 pin.
* Uart1 - Uses UART 1. An example would be NeoEsp8266**Uart1**Ws2812xMethod. Supports only TXD1/GPIO2 pin.
Because the UART FIFO size is limited, data for just a few (typically 10) pixels can be sent completely in the background. If you have more pixels than will fit into the UART FIFO, data sending will block (use the CPU) until only a few pixels are left to send, which can then be completed in the background while the CPU does other things. The exact number of pixels depends on how much bytes each pixel needs. The FIFO buffer is 128 bytes, of which 4 bytes are need for each byte transmitted to the pixel, so for a typical 3-bytes-per-pixel WS2812 you need 12 FIFO bytes per pixel and can drive 10 pixels without blocking).
If CPU cycles or blocking are an issue in your project, see NeoEsp8266AsyncUart1800KbpsMethod below.
If CPU cycles or blocking are an issue in your project, see AsyncUart below.
Due to using the hardware UART, the associated Serial or Serial1 objects can not be used. If you use UART1, Serial is still available and if you use UART0 then Serial1 is still available.
## NeoEsp8266Uart#400KbpsMethod
Same as 800Kbps method, but running at the older and slower data rate.
Use this instead of Neo400KbpsMethod to force your sketch to use the UART to send data.
## NeoEsp8266Uart#Ws2812xMethod & NeoEsp8266Uart#Ws2813Method
Same as NeoEsp8266Uart#800KbpsMethod but using a longer delay as required by these chips.
## NeoEsp8266AsyncUart#800KbpsMethod
Use this instead of Neo800KbpsMethod to force your sketch to use a UART to send data asynchronously.
NeoEsp8266AsyncUart1800KbpsMethod only supports the TXD1/GPIO2 pin. NeoEsp8266AsyncUart0800KbpsMethod only supports the TXD0/GPIO1 pin. The Pin argument is ignored and can be omitted.
**WARNING:** With this method, Serial and Serial1 cannot be used due to the ISR not being shareable.
## Asynchronous UART
These methods use the UART interrupt to read from a secondary buffer to send the data to the NeoPixels. It requires very little CPU overhead but does require an extra buffer similar to the DMA method.
* AsycUart0 - Uses UART 0. An example would be NeoEsp8266**AsycUart0**Ws2812xMethod. Supports only TXD0/GPIO1 pin.
* AsycUart1 - Uses UART 1. An example would be NeoEsp8266**AsycUart1**Ws2812xMethod. Supports only TXD1/GPIO2 pin.
**WARNING:** With this method, Serial and Serial1 cannot be used due to the ISR not being shareable.
**CAUTION:** With this method, the `Pixels()` method will return alternating pointers after each call to `Show()`; so the pointer returned should not be cached or retained between calls of `Show()`.
NOTE: Due to the varied board layouts for ESP8266, even though the pin may be exposed, it may not be usable due to some custom feature on the board you use. If you find it not working, you should review the hardware schematic of your board and confirm the pin is not used for other purposes that interferes with it being used for NeoPixelBus.
These methods uses the UART interrupt to read from a secondary buffer to send the data to the NeoPixels. It requires very little CPU overhead but does require an extra buffer similar to the DMA method.
If memory is an issue for your project, see the NeoEsp8266Uart#800KbpsMethod above.
_Thanks to unaiur for providing the original implementation._
## NeoEsp8266AsyncUart#400KbpsMethod
Same as NeoEsp8266AsyncUart#800KbpsMethod but running at the older and slower data rate.
Use this instead of Neo400KbpsMethod to force your sketch to use the UART to send data asynchronously.
## NeoEsp8266AsyncUart#Ws2812xMethod & NeoEsp8266AsyncUart#Ws2813Method
Same as NeoEsp8266AsyncUart800KbpsMethod but using a longer delay as required by these chips.
## NeoEsp8266BitBang800KbpsMethod
NeoEsp8266BitBang800KbpsMethod supports any available pin between 0 and 15.
This method uses only the CPU to send data to the NeoPixels. But due to Wi-Fi interrupts it is not stable when used with Wi-Fi features of the ESP8266.
## Bit Bang
This method uses only the CPU to send data to the NeoPixels. But due to Wi-Fi interrupts it is not stable when used with Wi-Fi features of the ESP8266. The bit bang methods only support pins between 0 and 15.
* BitBang - An example would be NeoEsp8266**BitBang**Ws2812xMethod.
It is not recommended to use this method except for comparing results with the other methods. For very short runs of pixels (no more than about 3) it may be possible to use this method without ill effects. If it fails, the pixels may not be correctly set.
Use this instead of Neo800KbpsMethod to force your sketch to use the Bit Banging to send data.
## NeoEsp8266BitBang400KbpsMethod
Same as NeoEsp8266BitBang800KbpsMethod but running at the older and slower data rate.
Use this instead of Neo400KbpsMethod to force your sketch to use the Bit Banging to send data.
## NeoEsp8266BitBangWs2812xMethod & NeoEsp8266BitBangWs2813Method
Same as NeoEsp8266BitBang800KbpsMethod but using a longer delay as required by these chips.