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 · Drivers

Writing a driver

A chip driver is a bm-lib package with one C file: a led_driver_desc_t naming the class, the LED model, the channel count and the default order. ext-led does the rest.

A chip driver gives one LED type a PHP class. It is a bm-lib package that requires ext-led and registers a descriptor symbol into the led_drivers registry. ext-led's shared code does the buffer, HSV and sending, so the descriptor and a constructor are all a driver needs. The C file includes only php_led.h: no ESP-IDF.

The LED timing comes from the HAL, which knows two models: BM_LED_MODEL_WS2812 and BM_LED_MODEL_SK6812. A new chip must be compatible with one of them.

The package

json composer.json
{
  "name": "acme/led-xyz",
  "description": "XYZ RGBW LED driver for ext-led (Baremetal\\Led\\Driver\\Xyz).",
  "version": "1.0.0",
  "type": "bm-lib",
  "license": "MIT",
  "require": {
    "php": ">=8.3",
    "php-baremetal/ext-led": "^1.0"
  },
  "extra": {
    "baremetal": {
      "register": { "led_drivers": ["xyz_driver_desc"] }
    }
  }
}

Sources default to src/*.c; no CMakeLists.txt. The symbol in register must be a non-static const led_driver_desc_t defined in those sources.

The C file

An RGBW chip with SK6812 timing in RGBW order, plus one method of its own that lights a pixel with its white channel, which the shared methods always leave at 0.

c src/xyz.c
#include "php_led.h"
#include "zend_exceptions.h"

extern const led_driver_desc_t xyz_driver_desc;

ZEND_BEGIN_ARG_INFO_EX(arginfo_xyz_ctor, 0, 0, 1)
    ZEND_ARG_TYPE_INFO(0, pin, IS_LONG, 0)
    ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, count, IS_LONG, 0, "1")
    ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, order, IS_LONG, 1, "null")
ZEND_END_ARG_INFO()

ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_xyz_white, 0, 2, IS_VOID, 0)
    ZEND_ARG_TYPE_INFO(0, i, IS_LONG, 0)
    ZEND_ARG_TYPE_INFO(0, level, IS_LONG, 0)
ZEND_END_ARG_INFO()

PHP_METHOD(Xyz, __construct)
{
    led_ctor(INTERNAL_FUNCTION_PARAM_PASSTHRU, &xyz_driver_desc);
}

/* white(int $i, int $level): pixel $i lit by its W channel only (R, G, B off), into the buffer */
PHP_METHOD(Xyz, white)
{
    zend_long i, level;
    ZEND_PARSE_PARAMETERS_START(2, 2)
        Z_PARAM_LONG(i)
        Z_PARAM_LONG(level)
    ZEND_PARSE_PARAMETERS_END();

    led_object *o = led_object_from(Z_OBJ_P(ZEND_THIS));
    if (!o->strip) {
        zend_throw_exception(zend_ce_exception, "Xyz is not initialised", 0);
        RETURN_THROWS();
    }
    if (i < 0 || (uint32_t) i >= o->count) {
        zend_argument_value_error(1, "is out of range for this strip");
        RETURN_THROWS();
    }
    uint8_t w = level < 0 ? 0 : (level > 255 ? 255 : (uint8_t) level);
    bm_ledstrip_set_pixel_rgbw(o->strip, (uint32_t) i, 0, 0, 0, w);
}

static const zend_function_entry xyz_methods[] = {
    PHP_ME(Xyz, __construct, arginfo_xyz_ctor,  ZEND_ACC_PUBLIC)
    PHP_ME(Xyz, white,       arginfo_xyz_white, ZEND_ACC_PUBLIC)
    PHP_FE_END
};

const led_driver_desc_t xyz_driver_desc = {
    .name = "xyz",
    .php_class = "Xyz",
    .model = BM_LED_MODEL_SK6812,
    .channels = 4,
    .default_order = LED_ORDER_RGBW,
    .methods = xyz_methods,
};

PHP then has Baremetal\Led\Driver\Xyz with white(), every Device method and the constants GRB, RGB, GRBW, RGBW. The led-ws2812 and led-sk6812 drivers are this file without the extra method.

Descriptor fields

led_driver_desc_t is declared in led_driver_desc.h. ext-led 1.0 reads every field:

Field Meaning
name Registry name, used in the constructor error cannot init NAME on GPIO N.
php_class Short class name; the class is Baremetal\Led\Driver\<php_class>. Must be unique among installed drivers.
model BM_LED_MODEL_WS2812 or BM_LED_MODEL_SK6812 (from bm_ledstrip_hal.h): the timing the HAL uses.
channels 3 (RGB) or 4 (RGBW). With 4, the class also gets GRBW and RGBW. The order passed to the constructor sets the bytes per pixel: with GRBW or RGBW the shared methods write pixels as RGBW with W at 0.
default_order LED_ORDER_GRB, LED_ORDER_RGB, LED_ORDER_GRBW or LED_ORDER_RGBW, used when $order is null. A 4-channel driver needs a 4-channel default.
methods The class's method table (zend_function_entry[]), at least __construct.

Functions a driver may call

From php_led.h and bm_ledstrip_hal.h:

Function Does
led_ctor(INTERNAL_FUNCTION_PARAM_PASSTHRU, &desc) The shared constructor: (int $pin, int $count = 1, ?int $order = null), validates, refuses a pin another strip drives, creates and clears the strip (not while serving an HTTP request), binds it to the object.
led_object_from(Z_OBJ_P(ZEND_THIS)) The object behind $this: strip (NULL before the constructor), count, channels (from the order), pin.
bm_ledstrip_set_pixel(s, i, r, g, b), bm_ledstrip_set_pixel_rgbw(s, i, r, g, b, w) Write one pixel into the buffer. Return 0 on success.
bm_ledstrip_refresh(s), bm_ledstrip_clear(s) Send the buffer; clear it and send. 0 on success.

All run on the PHP task.

Try it in a project

Keep the driver next to the project as a path repository; conductor links it into .phpbm/packages/.

json project composer.json
{
  "name": "acme/xyz-demo",
  "type": "project",
  "repositories": [
    { "type": "composer", "url": "https://repository.php-baremetal.com", "canonical": true },
    { "type": "path", "url": "extensions/led-xyz" }
  ],
  "require": {
    "php-baremetal/conductor": "^1.0",
    "acme/led-xyz": "^1.0"
  },
  "config": {
    "allow-plugins": { "php-baremetal/conductor": true },
    "platform": { "php": "8.5.11" }
  },
  "extra": {
    "baremetal": {
      "sdk": "esp32@^2.0",
      "board": "espressif-esp32-s3-devkitc-1-n8r8",
      "runtime": "init-loop",
      "storage": "embedded"
    }
  }
}
php project-src/index.php
<?php
use Baremetal\Led\Driver\Xyz;

$leds = new Xyz(pin: 5, count: 8);   // the pin your strip is wired to
$leds->fill(0, 0, 32);
$leds->white(0, 128);                // first pixel: white channel only
$leds->show();

Related