WS2812 addressable LEDs

There is no clock line. A bit is a high pulse whose length is the bit, 0.4 microseconds for a 0 and 0.8 for a 1, twenty-four bits per LED, green first. The part decodes those pulses off the pin's own edges, with the same timing tolerance a real strip has.

Pins

Pin	What it does
VDD	Supply.
VSS	Ground.
DIN	The pulse-coded data line in.
DOUT	Whatever is left of the frame after this device's own LEDs, for chaining.

Properties

count: how many LEDs. layout: strip, ring or matrix. serpentine: whether a matrix is wired boustrophedon (every other row reversed), which the wiring decides and the data alone cannot say. rgbw: 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.

What the model gets right

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.

What it does not model

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.

Common mistakes

Driving it from digitalWrite: a call is far too slow for the 0.4 microsecond high of a bit, on every board. Use Adafruit_NeoPixel or FastLED, which time the bit on the AVR boards in assembly and on the ESP32, Pico and Uno R4 from the core's own cycle counter, as the simulated boards need.

Code

The Adafruit NeoPixel tutorial compiles as it stands on the AVR boards, the ESP32 family, the Pico and the Uno R4:

#include <Adafruit_NeoPixel.h>

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

void setup() {
  pixels.begin();
}

void loop() {
  pixels.clear();
  pixels.setPixelColor(0, pixels.Color(0, 150, 0));
  pixels.show();
  delay(500);
}

Adafruit_NeoPixel.h is Mokxi's own header on its WS2812 driver, with setPixelColor, Color, ColorHSV, fill, clear, setBrightness, gamma32 and rainbow. Every strip in a sketch shares one fixed pool of 1024 LEDs rather than taking its buffer from the heap. NEO_RGB and the other orders send the bytes in that order, so a WS2812B shows them swapped, as a real one does. On a board with no driver (the STM32 boards) the header stops with a message saying so.

See it in action

Ring Simon, Rainbow strip and Plasma panel all drive a WS2812 ring or matrix from an ESP32-C3. Open them at /templates, and read the parts games are made of for more on the protocol and the driver.

Rainbow to the pot of gold runs two strips from an Arduino Uno with Adafruit_NeoPixel, and the tutorial Arduino NeoPixel walks through it.

The WS2812 part page draws it live, with its pins and every project that uses one.