Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/ext-led

bm-ext MIT

Baremetal\Led\Device and the addressable-LED driver framework. Chips are packages registering into the led_drivers registry; the platform side is a ledstrip-hal package.

bus: led

ext-led · Reference

Errors and limits

Every exception ext-led throws, what it does not report, and the limits that come from the platform.

ext-led throws \ValueError for invalid arguments, plain \Exception when a strip cannot be created, and \RuntimeException for a board block onboard() cannot use; it defines no exception classes of its own.

Exceptions

Message Thrown by Cause
board '<id>' has no '<block>' block onboard() The board does not describe that block.
board '<id>' has a <block> of type '<type>', not '<chip>' onboard() The block describes another chip.
board '<id>': <block>.pin is missing onboard() The block has no pin.
board '<id>': <block>.order must be grb, rgb, grbw or rgbw onboard() The block's order is another word.
board '<id>': <block>.pin must be a valid GPIO onboard() The block's pin is negative.
board '<id>': <block>.order '<order>' is not supported by <chip> onboard() The order is grbw or rgbw on a three-channel chip (ws2812).
Cannot instantiate abstract class Baremetal\Led\Device Device::onboard() Called on the abstract base: call it on a chip class.
...: Argument #1 ($pin) must be a valid GPIO constructor $pin is negative.
...: Argument #2 ($count) must be at least 1 constructor $count is 0 or negative.
...: Argument #3 ($order) must be one of the GRB, RGB constants Ws2812 constructor $order is not GRB or RGB.
...: Argument #3 ($order) must be one of the GRB, RGB, GRBW, RGBW constants Sk6812 constructor $order is not one of the four.
cannot init NAME on GPIO N constructor The HAL could not create the strip: the pin cannot be an output, no transmit channel is free, or no memory.
cannot init NAME: GPIO N is already used by another LED strip constructor Another live object drives that pin. Reuse it, or drop it first.
cannot init NAME on GPIO N: 16 LED strips are already open constructor ext-led's table of strips is full (the transmit channels usually run out first).
LED write failed on GPIO N (error E) pixel(), fill(), hsv(), set() The HAL refused the pixel.
LED refresh failed on GPIO N (error E) show(), set(), off(), constructor The frame could not be sent (the transmit channel is busy or failed).
...: Argument #1 ($i) is out of range for this strip pixel(), hsv() $i is negative or not below count().
Trying to clone an uncloneable object of class ... clone A copy would not own the strip: keep one object per strip.
Led\Device is not initialised any method but count() The object has no strip: a subclass whose constructor did not run. Baremetal\Led\Device is abstract: new on it throws Error.

NAME is the driver name (ws2812, sk6812).

Not reported

  • Colour components out of 0 to 255 are clamped, and hues wrap modulo 360.

Limits

Limit Value Source
Strips at once one RMT transmit channel each: 4 on ESP32-S3 and ESP32-P4, minus any the firmware uses esp32-ledstrip-hal
Pixels per strip count as given; memory is the practical limit (3 or 4 bytes per pixel in the buffer) esp32-ledstrip-hal
LED models WS2812 timing and SK6812 timing esp32-ledstrip-hal
Channels 3 or 4, from the order (GRB, RGB or GRBW, RGBW); the white channel is always 0 ext-led
RMT resolution 10 MHz (0.1 microsecond per tick), no DMA esp32-ledstrip-hal

Lifetime

Each object owns its strip, its transmit channel and its pin, and destroying the object releases all three; ext-led only remembers which pins are taken, to refuse a second strip on one. The LEDs keep their last frame. Calling a chip constructor again on the same object replaces its strip. In the event-driven runtime keep the object in a variable the handlers capture (or a global); in the web-server runtime it lasts one request, and the constructor does not clear the strip there, so the LEDs keep what the previous request showed.

Frames are sent from the calling PHP task, which waits until the frame is out. ext-led does nothing special for the power-save option.

Related