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

Package · Extension

Addressable LEDs

Addressable RGB LEDs from PHP: one class per chip under Baremetal\Led\Driver, a pixel buffer you fill in RGB or HSV and send with show(). Neutral extension; conductor adds the LED-strip HAL for your platform.

ext-led drives addressable LEDs on one data pin: a strip, a ring, or the single RGB LED many boards carry. You construct the class for your chip (Baremetal\Led\Driver\Ws2812, Baremetal\Led\Driver\Sk6812) with the pin and the pixel count, write colours into its buffer by RGB or HSV, and send the buffer to the LEDs with show(). Every chip class extends Baremetal\Led\Device, which carries all the methods.

Requirements

Requires Why
php-baremetal/ledstrip-hal (virtual) The platform side: the strip driver and its timing. On ESP32 it is php-baremetal/esp32-ledstrip-hal (platform esp32, over Espressif's led_strip component on the RMT peripheral).

You never require the HAL yourself. Conductor reads the platform from extra.baremetal.sdk (esp32@^2.0 gives esp32) and adds php-baremetal/esp32-ledstrip-hal while Composer resolves. The ESP32 HAL depends on the ESP-IDF registry component espressif/led_strip ==3.1.0~1, which the first build downloads, so that build needs network access. The extension's PHP module is led.

A chip class comes from a chip package: ext-led alone gives Baremetal\Led\Device and no class you can construct. Require the chip package; it requires ext-led.

Install

  1. Install conductor once per machine

    composer global require php-baremetal/conductor

  2. Create the project

    phpbm init my-leds writes composer.json with conductor, the package registry, and the SDK, board, runtime and storage you pick.

  3. Require the chip package

    composer require php-baremetal/led-ws2812 (or php-baremetal/led-sk6812, or both).

  4. Build and flash

    phpbm flash, then phpbm monitor for the console.

The resulting composer.json, for a Waveshare ESP32-S3-Zero (N8R8), whose on-board RGB LED is a WS2812 on GPIO 48:

json composer.json
{
  "name": "acme/my-leds",
  "type": "project",
  "repositories": [
    { "type": "composer", "url": "https://repository.php-baremetal.com", "canonical": true }
  ],
  "require": {
    "php-baremetal/conductor": "^1.0",
    "php-baremetal/ext-sys": "^1.0",
    "php-baremetal/ext-led": "^1.0",
    "php-baremetal/led-ws2812": "^1.0"
  },
  "config": {
    "allow-plugins": { "php-baremetal/conductor": true },
    "platform": { "php": "8.5.11" }
  },
  "extra": {
    "baremetal": {
      "sdk": "esp32@^2.0",
      "board": "waveshare-esp32-s3-zero-n8r8",
      "runtime": "init-loop",
      "storage": "embedded"
    }
  }
}

Requiring ext-led next to the chip package is optional; it states that the script uses it directly. ext-sys provides delay() for the script below.

A first script

project-src/index.php for the init-loop runtime: the top level runs once, then loop($tick) runs repeatedly.

php project-src/index.php
<?php
use Baremetal\Led\Driver\Ws2812;

// the on-board LED of this board is a WS2812 in RGB byte order
$led = new Ws2812(48, 1, Ws2812::RGB);

function loop(int $tick): void
{
    global $led;

    $led->hsv(0, ($tick * 2) % 360, 255, 10);   // slow hue sweep, very dim
    $led->show();
    delay(25);
}

PHP API at a glance

Name Kind Meaning
Baremetal\Led\Device class The base of every chip class: pixel(), fill(), hsv(), set(), show(), off(), count().
Baremetal\Led\Driver\Ws2812 class From led-ws2812: 3 channels, GRB order by default. Constants GRB, RGB.
Baremetal\Led\Driver\Sk6812 class From led-sk6812: 4 channels (RGBW), GRBW order by default. Constants GRB, RGB, GRBW, RGBW.
Baremetal\Output\Led interface Capability marker implemented by Device, so by every chip class. No methods.

The extension defines no functions. Invalid arguments throw \ValueError; a strip that cannot be created throws \Exception. See LED devices and Errors and limits.

Drivers

ext-led declares the registry led_drivers (element type led_driver_desc_t, header led_driver_desc.h). Chip packages (bm-lib) register a descriptor into it with extra.baremetal.register, and at module startup ext-led registers one PHP class per descriptor. Available today:

Package Class Channels Default order
led-ws2812 Baremetal\Led\Driver\Ws2812 3 GRB
led-sk6812 Baremetal\Led\Driver\Sk6812 4 GRBW

See The led_drivers registry and Writing a driver.

Notes

  • A strip belongs to its PHP object: it is created by the constructor and released when the object is destroyed. Keep the object alive (a global, as above) for as long as you use the LEDs. In the web-server runtime an object created during a request is released at the end of it.
  • Releasing a strip does not turn the LEDs off: they keep the last frame. Call off() first.
  • pixel(), fill() and hsv() only write the buffer; show(), set() and off() send it.
  • There is no global brightness: scale the colours yourself (the $v of hsv() is the easy knob). A long strip at full white can draw more current than a USB port supplies; power it separately with a common ground.

Related