LED strips
Drive WS2812 and SK6812 LEDs, strips, rings or the RGB LED on a board, from a pixel buffer. Each strip takes one of the four RMT transmit channels of the chip.
ext-led drives addressable RGB LEDs: strips,
rings, and the single RGB LED many boards carry. You create one object per data pin, write colours into its pixel
buffer, then send the buffer with show().
You require a chip package; it requires ext-led, and the conductor adds the esp32 HAL (esp32-ledstrip-hal):
The first build downloads Espressif's led_strip component through the ESP-IDF component manager, so it needs
network access.
The classes
Each chip package adds one class in Baremetal\Led\Driver\. Both extend Baremetal\Led\Device:
| Class | Package | Colour order constants | Default order |
|---|---|---|---|
Ws2812 |
led-ws2812 | GRB, RGB |
GRB |
Sk6812 |
led-sk6812 | GRB, RGB, GRBW, RGBW |
GRBW |
The constructor is new Ws2812(int $pin, int $count = 1, ?int $order = null), and the same for Sk6812. The
strip is cleared (every pixel off) when the object is created, except while serving an HTTP request
(web-server), where the LEDs keep the last frame from the previous request.
| Method | Meaning |
|---|---|
pixel(int $i, int $r, int $g, int $b) |
Set pixel $i (from 0) in the buffer |
hsv(int $i, int $h, int $s, int $v) |
Set pixel $i from hue (degrees), saturation and value (0 to 255); $v is the brightness |
fill(int $r, int $g, int $b) |
Set every pixel in the buffer |
show() |
Send the buffer to the LEDs; nothing lights up before this |
set(int $r, int $g, int $b) |
fill() and show() in one call |
off() |
Clear the buffer and send it |
count(): int |
The number of pixels |
Colour components outside 0 to 255 are clamped, and hues wrap at 360.
A strip
If red and green come out swapped, the strip is not GRB: pass Ws2812::RGB. For an SK6812 with a white LED use
Sk6812::GRBW or Sk6812::RGBW (the white channel is always written as 0); for one without, Sk6812::GRB or
Sk6812::RGB.
The RGB LED on a board
Many boards carry one WS2812 on a data pin. The example 04-gpio-led/s3-rgb-show runs a rainbow on the LED of the
waveshare-esp32-s3-zero-n8r8, on GPIO 48. That LED is a single WS2812 in RGB order, so the order is passed
explicitly. The pin and the colour order differ between boards: the espressif-esp32-s3-devkitc-1-* and
freenove-esp32-s3-wroom-lite-* boards have a WS2812 on GPIO 48 in GRB order, and some ESP32-S3 boards use
GPIO 38. On a board whose file has a led block, Ws2812::onboard() takes the pin and the order from it;
otherwise check the schematic of yours. The composer.json requires ext-sys, ext-led and led-ws2812, with
the init-loop runtime.
What the ESP32 does
| Behaviour | Detail |
|---|---|
| RMT channels | Each strip is built on the RMT peripheral and takes one transmit channel; ESP32-S3 and ESP32-P4 have 4. When none is free the constructor throws cannot init ws2812 on GPIO N. |
| Timing | 10 MHz RMT resolution, no DMA. WS2812 or SK6812 timing is chosen by the class. |
show() |
Blocks the PHP task until the frame has gone out. A failed transfer throws LED refresh failed on GPIO N (error E). |
| Pixels | The buffer takes 3 or 4 bytes per pixel; memory is the practical limit on count. |
| Lifetime | The object owns its channel. Destroying it releases the channel and leaves the LEDs on their last frame. |
| One object per pin | A second object on a pin that a live object drives throws. To replace a strip, set the old variable to null first: $led = new Ws2812(8, 16) over an existing $led on GPIO 8 builds the new object before the old one is released. |
In the event-driven runtime keep the object in a variable that your handlers capture (or a global); in the
web-server runtime it lasts one request.
Full-brightness LEDs are very bright and draw a lot of current. Use a low $v (the example uses 10) and a
suitable power supply for long strips.
Common errors
| Message | Cause |
|---|---|
cannot init ws2812 on GPIO N (sk6812 for Sk6812) |
The pin cannot be an output, no RMT channel is free, or memory ran out |
Argument #2 ($count) must be at least 1 |
$count is 0 or negative |
Argument #3 ($order) must be one of the GRB, RGB constants |
An order the class does not support; Sk6812 lists its four constants |
Argument #1 ($i) is out of range for this strip |
pixel() or hsv() with an index outside 0 to count() - 1 |
cannot init ws2812: GPIO N is already used by another LED strip |
Another live object drives that pin; reuse it, or set it to null first |
LED write failed on GPIO N (error E) |
The driver refused a pixel in pixel(), fill(), hsv() or set() |
LED refresh failed on GPIO N (error E) |
The frame could not be sent by show(), set(), off() or the constructor |
Trying to clone an uncloneable object of class ... |
clone on a strip: keep one object per strip |
The full API is on the ext-led package page.