ESP32 WS2811 LED Strip Driver

A driver for WS2811 RGBIC LED strips on the ESP32, written for ESP-IDF. These are addressable LEDs that are controlled through a single data line, so you set the colour of every pixel from one GPIO. The driver uses the ESP32 RMT peripheral to produce the timing the LEDs need.

The functions

The header ws2811.h has five functions:

The component needs the driver component of ESP-IDF. Set the pixels first, then call refresh to show them.

Example

The example, from the README, runs a strip of 3 LEDs on GPIO 5 and cycles it through red, green and blue, one second each:

#define LED_STRIP_LENGTH 3
#define GPIO_NUM 5

void app_main(void)
{
    led_strip_t *strip = led_strip_init(RMT_CHANNEL_0, GPIO_NUM, LED_STRIP_LENGTH);

    if (!strip) {
        printf("Failed to initialize LED stripn");
        return;
    }

    while (1) {
        for (int i = 0; i < LED_STRIP_LENGTH; i++) {
            led_strip_set_pixel(strip, i, 255, 0, 0);  // Red
        }
        led_strip_refresh(strip);
        vTaskDelay(pdMS_TO_TICKS(1000));
        /* the same for green (0, 255, 0) and blue (0, 0, 255) */
    }
}

How the timing is done

The LEDs read their colour from a pulse train on the data line. The driver builds it with the RMT peripheral, with a clock divider of 2 and 42 ticks for every bit. A 0 bit is a pulse that is high for 14 ticks and low for 34, and a 1 bit is high for 34 ticks and low for 14. Every pixel takes 24 bits, and the driver keeps a buffer of that size for each pixel of the strip.

Hardware

The diagram at the top of this page shows an ESP32 development board, a breadboard and a barrel jack for the supply of the strip. The strip has connections for +24 V, ground and data, and two more for warm white and cool white. The driver in this repository handles the data line. For how addressable LEDs work, see the NeoPixels guide.

Good to know

• The repository is under the MIT licence.
• It has no releases. The driver is the ws2811.c and ws2811.h files, and the component is registered with CMake as ws2811.

Everything is in the esp32-ws2811 repository on GitHub.