WS2812B NeoPixel with ESP32: Wiring, Code, Live Demo

At a glance

The Addressable RGB LEDs in brief

What it is, and every setting the properties panel gives it.

WS2812B LEDs, sold as NeoPixels, put a red, green and blue LED and a small controller in every pixel and chain them all on one data wire. There is no clock: each bit is a high pulse whose length is the bit, about 0.4 microseconds for a nought and 0.8 for a one, twenty-four bits a pixel, green first, and fifty microseconds of quiet makes every LED take up its new color at once. Mokxi’s part decodes those pulses from the pin’s own edges inside the datasheet’s timing windows, and abandons a frame it cannot read the way a real strip does. The same part is a strip, a ring or a matrix, up to 1024 LEDs. The WS2812 driver and the Adafruit_NeoPixel calls run on the AVR boards, the ESP32 family, the Pico and the Uno R4 here. Power draw is not modeled, so a long strip never browns out a board.

Family: Outputs
Pins: 4
count: 8; how many LEDs.
layout: strip (or ring, matrix); strip, ring or matrix.
serpentine: false; whether a matrix is wired boustrophedon (every other row reversed), which the wiring decides and the data alone cannot say.
rgbw: false; an SK6812 RGBW strip, four bytes an LED (green, red, blue, white), for a sketch that uses NEO_GRBW. The white byte shows added to the color, since the picture has no separate white emitter.

A circuit built around it, running and explained: the NeoPixel simulator.

Pins

4 pins

Named as the editor names them, so a wire lands where you expect it.

Role

What it does

VDD

Input or output

Supply.

VSS

Input or output

Ground.

DIN

Input

The pulse-coded data line in.

DOUT

Output

Whatever is left of the frame after this device's own LEDs, for chaining.

How to use it

How to use WS2812B NeoPixels with an ESP32

DIN to a GPIO, VDD to 5 V, VSS to GND, and a ground shared with the board. The Adafruit_NeoPixel calls compile as they stand: create the strip with its length and pin, set colors with setPixelColor(), and call show() to send them. Keep the brightness down on a real strip, because each pixel can draw up to 60 milliamps at full white.

The same sketch runs on an Arduino Uno: the library times the bits in assembly on the AVR boards, and on the core’s cycle counter on the ESP32 family, the Pico and the Uno R4. On a board with no WS2812 driver in Mokxi, such as the STM32 boards, the header says so when you build.

Part pin

Board pin

DIN

GPIO 5

VDD

5 V

VSS

GND

ESP32-C3: WS2812B rainbowlive0.000 s 0.00x

Click to open it in the editor

This is the simulator itself, running here. Click anything to open it in the editor.

Open this project in the editor Read the full tutorial

One green pixel

#include <Adafruit_NeoPixel.h>

Adafruit_NeoPixel pixels(8, 4, NEO_GRB + NEO_KHZ800);

void setup() {
  pixels.begin();
  pixels.setPixelColor(0, pixels.Color(0, 150, 0));
  pixels.show();
}

void loop() {}

How it is modeled

What is true about the Addressable RGB LEDs, here

In its help article’s own words: what the simulation gets right, and where it stops.

Modeled

layout = "ring" bends the same row of LEDs into a circle, LED 0 at twelve o'clock and the rest clockwise, exactly how the rings people buy are numbered. A ring is a strip electrically, so nothing about the wiring or the firmware changes, only the picture does. Nothing is shown until the latch: 50 microseconds of a quiet line ends the frame, and every LED takes up its new color at once, the way a real strip does.

Not modeled

No brightness curve beyond a straight RGB value, and no power draw per LED, so a strip here never browns out a board's supply the way a long real one can.

The decode is the datasheet's windows. A high pulse under 125 ns is a glitch and is ignored; from there to 600 ns is a zero and from 600 ns to 950 ns is a one, 950 ns being T1H at the top of its ±150 ns tolerance. The low between bits is checked too (at least 300 ns after a one and 700 ns after a zero, both the bottom of their tolerances), and a stream that breaks either rule abandons the frame, the way a real strip stops following one it cannot read. The total bit period is not checked on top of that: the datasheet's own figure is 1.25 us ±600 ns, which constrains nothing once both halves are, and real strips take faster streams than 1.25 us happily. The 300 ns of forward delay per device is modeled as a flat 150 ns.

The latch is 50 microseconds of quiet, which is the original WS2812B figure; a WS2812B-V5 wants 280 microseconds, so a driver written against this one can produce a frame that never latches on newer strips. The color order is fixed at GRB (there is no RGBW and no way to say a strip is wired otherwise), and there is no per-LED refresh, no gamma, no thermal limit and no maximum of anything except the 1024 LEDs one part will hold.

From WS2812 addressable LEDs, in full.

Projects