zorxx/neopixel

ESP32 Neopixel Driver

ESP32 Neopixel Driver

High-performance low-level driver for WS2812B LEDs, allowing individual control of hundreds of LEDs via a single ESP32 GPIO.

Add this component to an esp-idf project with the following command:

idf.py add-dependency "zorxx/neopixel"

Source for this project lives at https://github.com/zorxx/neopixel

Overview

This library makes use of the ESP32 I2S peripheral bus to control "any" number of WS2812b LEDs, consuming minimal ESP32 resources.

Some of the highlights include:

• Simple abstract API
• Use of I2S DMA and double-buffering to minimize ESP32 CPU usage.
• A high-speed lookup table implementation for setting pixel colors.
• WS2812b data bus runs at maximum-supported data rate of 2.6 Mbps.

Performance

In order to perform a pixel update, the WS2812b protocol requires 9 bytes per pixel plus 50 bytes at the end of the transmission. For a string of 256 pixels, this equates to 2354 bytes per transfer and at 2.6 Mbps, each update requires approximately 7.3ms. With a configuration of 256 LEDs, this library supports refresh rates over 130 "frames" per second. With 512 LEDs, a refresh rate of nearly 70 "frames" per second is achieved.

With this library's double-buffer implementation, pixel buffer updates (via a neopixel_SetPixel function call) occur asynchronously and in a thread-safe manner with respect to the I2S hardware transfers. If a pixel update is in progress when the pixel buffer is updated, another update will begin immediately following the completion of the pixel update. If no pixel update is in progress when the pixel buffer is updated, the I2S hardware transfer will begin immediately.

Unlike other WS2812b pixel buffer update routines which make use of many expensive bitwise operations to build the pixel buffer for each update, this library utilizes a lookup table implementation to update colors for only the LEDs that have changed since the last update. The lookup table contains pre-computed values, indexed by a color's desired intensity (0-255). This requires only a copy of 9 bytes to change a pixel's RGB value.

Example Applications

See the examples directory of this repository for example Neopixel applications.

License

All files delivered with this library are copyright 2023 Zorxx Software and released under the MIT license. See the LICENSE file for details.

neopixel's Issues

First LED randomly turns green with full brightness

Hey, thank you for this amazing component!

I have a "little" problem and I'm not sure if it is a software issue.
So, I've a PCB with 13 WS2812B LEDs.

And here is my code (basically, just turn off everything):

static void led_task(void* arg)
{
    tNeopixelContext neopixel = neopixel_Init(PIXEL_COUNT, GPIO_WS2812B);

    for (;;) {
        uint8_t i = 0;
        tNeopixel pixel[] =
            {
                { i++, NP_RGB(0, 0, 0) }, // not copying everything here; 13 identical lines for now lmao
            };

        neopixel_SetPixel(neopixel, pixel, ARRAY_SIZE(pixel));
        vTaskDelay(pdMS_TO_TICKS(16));
    }
}

From my observations, each time I use neopixel_SetPixel, there is some (idk if random) probability that the first LED green value will end up with full brightness. Other LEDs are unaffected. Other colors of the 1st LED are unaffected.

I'm facing this issue with my 2nd circuit boards batch; for the 1st batch I thought that my problem was noise so I have added 510 Ohm resistor between the esp32-s3 pin and the 1st LED input. However, I still experience the problem.

I've tried to dig into the source code, but no luck so far due to lack of experience and equipment.
Also: sometimes that just doesn't happen at all and everything works as expected. Then I reconnect it to the power supply and it glitches again. A bypass cap is really close to the 1st LED.

[ESP32-C3] Led turning on in fixed green.

Hi there! Thanks for the effort on doing this library!

I've an issue where the first LED turns on in green no matter what. Hardware in question is a dev board with an ESP32-C3 on it.

My worskpace:

• ESP32-C3 dual USB-C board with onboard WS2812B LED.
• ESP-IDF v5.2.1-dirty (as VSCode extension)

Things I've tried so far:

• I used both LEDs: the onboard neopixel and a 8x8 matrix.
• Set LED to any other color than green. For example, red (rgb in decimal: 1048576).
• The fix stated in #2, but the library refused to compile.
• Your "test1" example.

The code so far (a bit trimmed):

    #include <inttypes.h>

    #define NEOPIXEL_PIN    GPIO_NUM_8    /* builtin ws2812b led */
    #define PIXEL_COUNT     1

    tNeopixelContext neopixel = neopixel_Init(PIXEL_COUNT, NEOPIXEL_PIN);
    
    while (true)
    {
        tNeopixel pixel[] =
        {
            { 0, NP_RGB(16, 0, 0) }, /* red */
        };

        ESP_LOGI(TAG, "[%s] Starting", __func__);
        if (neopixel_SetPixel(neopixel, &pixel[0], 1))
        {
            ESP_LOGW(TAG, "SetPixel was TRUE, [ %"PRIu32" ] [ %"PRIu32" ]", pixel[0].index, pixel[0].rgb);
        }
        else
        {
            ESP_LOGW(TAG, "SetPixel was FALSE");
        }
        vTaskDelay(pdMS_TO_TICKS(1000));
        ESP_LOGI(TAG, "[%s] Finished", __func__);
    }

Am I missing something here?

Thanks in advance!

Buffer lag (?)

Hello.
Thank you very much for the library! I tried to use it in a new project but I stumbled upon an issue.
The following code is supposed to set the pixel to the red color, then to green, then turn it off. But the last command is not executed. I played around with the code and figured out when calling neopixel_SetPixel, the command is sent out only on the next neopixel_SetPixel invocation. I looked through the source code and didn't manage to figure it out.
Any ideas what can be wrong?

void app_main(void)
{
  tNeopixelContext ctx = neopixel_Init(1, GPIO_NUM_7);
  tNeopixel pixel[] = {
    { 0, NP_RGB(50, 0, 0) },
    { 0, NP_RGB(0, 50, 0) },
    { 0, NP_RGB(0, 0, 0) },
  };
  neopixel_SetPixel(ctx, &pixel[0], 1); 
  vTaskDelay(pdMS_TO_TICKS(1000));
  neopixel_SetPixel(ctx, &pixel[1], 1); 
  vTaskDelay(pdMS_TO_TICKS(1000));
  neopixel_SetPixel(ctx, &pixel[2], 1); 
  vTaskDelay(portMAX_DELAY);
}

The controller is ESP32-C3.