php-baremetal/php-esp32-sdk

SDK First-party

The esp32 SDK: boards, the PHP build recipe, runtimes, storages and the ESP-IDF toolchain for ESP32-P4 and ESP32-S3. phpbm downloads and drives it.

SDK · Modules

SPI and displays

Open a SPI host, talk to a chip by chip select, or drive the QSPI round display of the Waveshare ESP32-S3-Touch-LCD-1.85B. Two hosts exist, and microSD storage or a W5500 network already takes one.

ext-spi is a SPI master. Baremetal\Spi\Bus opens a SPI host on your pins (four data lines for QSPI), Baremetal\Spi\Device exchanges raw bytes with one chip on it, and driver packages add typed classes under Baremetal\Spi\Driver\.

bash
composer require php-baremetal/ext-spi                  # bus and raw devices
composer require php-baremetal/esp32-display-st77916    # ST77916 QSPI round display, ESP32 only

The display driver requires ext-spi, so it is enough on its own. The conductor adds the esp32 HAL (esp32-spi-hal).

Bus and raw devices

new Bus(int $sclk, int $mosi, int $miso = -1, int $data2 = -1, int $data3 = -1, int $host = 1) opens a host. miso of -1 makes a write-only bus; the bus is four-line only when both data2 and data3 are given. host 1 is SPI2_HOST and 2 is SPI3_HOST. A second new Bus() on the same host and pins returns the same bus.

Bus::device(int $cs, int $hz = 1000000, int $mode = 0): Device attaches the chip whose chip select is GPIO $cs. A Device has transfer(string $tx): string (full duplex, same length back), write(string $data) and read(int $length): string. CS stays active for the whole call.

php read the JEDEC id of a SPI flash chip
<?php
use Baremetal\Spi\Bus;

$bus   = new Bus(sclk: 12, mosi: 11, miso: 13);
$flash = $bus->device(cs: 10, hz: 10_000_000);

$rx = $flash->transfer("\x9F\x00\x00\x00");          // JEDEC ID command + 3 dummy bytes
printf("JEDEC id: %s\n", bin2hex(substr($rx, 1)));

The ST77916 display

esp32-display-st77916 adds Baremetal\Spi\Driver\St77916, a driver for 360 x 360 QSPI round panels (the size is a parameter, 1 to 4096 per side). Colours are RGB565 integers.

Method Meaning
new St77916(Bus $bus, int $cs = 21, int $rst = 3, int $bl = -1, int $width = 360, int $height = 360, ...) Bring the panel up; also x_gap, y_gap, mirror_x, mirror_y, swap_xy, invert for orientation
fill(int $color) Paint the whole panel
rect(int $x, int $y, int $w, int $h, int $color) Paint a solid rectangle, clipped to the panel; origin top-left
rgb(int $r, int $g, int $b): int Pack 8-bit components into RGB565
wake() Re-initialise the panel after a light sleep, then repaint

The example 06-display/display-hello runs on waveshare-esp32-s3-touch-lcd-1.85b with the init-loop runtime and requires ext-sys, ext-spi and esp32-display-st77916. It cycles the background colour:

php 06-display/display-hello/project-src/index.php
<?php
use Baremetal\Spi\Bus;
use Baremetal\Spi\Driver\St77916;
use Baremetal\Output\Display;

$bus = new Bus(sclk: 40, mosi: 46, miso: 45, data2: 42, data3: 41);   // QSPI: mosi=D0, miso=D1
$lcd = new St77916($bus, cs: 21, rst: 3, bl: 5, width: 360, height: 360);

printf("St77916 instanceof Output\\Display: %s\n", $lcd instanceof Display ? "yes" : "no");

function loop(int $tick): void
{
    global $lcd;
    $colors = [$lcd->rgb(255, 0, 0), $lcd->rgb(0, 255, 0), $lcd->rgb(0, 0, 255), $lcd->rgb(255, 255, 255)];
    $lcd->fill($colors[$tick % 4]);
    delay(1000);
}

Asynchronous flush

St77916 implements Baremetal\Output\Display (from ext-display): drawing calls write a framebuffer in memory and flush() sends the region that changed. flush() starts the transfer and returns at once, while the panel's DMA reads the framebuffer. On the Waveshare ESP32-S3-Touch-LCD-1.85B a full-frame flush() returns in about 1.5 ms and the transfer takes about 30 ms; a 60 x 60 square returns in about 0.6 ms and takes about 2 ms.

  • A drawing that touches rows not yet sent waits until they are; a drawing elsewhere does not wait.
  • A flush() while another is in flight is pending and starts when the first ends; at most one region is pending, and another flush() merges into it.
  • flushWait() returns when nothing is in flight or pending. Call it before anything that must see the frame on the panel. A wait longer than 2000 ms throws \RuntimeException St77916: flush timed out.
  • A transfer that fails throws its push failed error at the next call on the display.
  • onFlushed(string $event) raises a Baremetal\Display\Flushed subclass at the end of every region ($x0, $y0, $x1, $y1, $us). onVsync(string $event) raises a Baremetal\TimerEvent subclass at every pulse of the panel's TE pin, so the panel is the metronome of the animation. Both are event sources of ext-events.

Two options of St77916::onboard(string $block = 'display', bool $buffered = false, bool $vsync = false) (and of the constructor, with int $te = -1) change how the flush behaves:

Option Effect
vsync: true Every region starts at the next TE pulse, so a region shorter than one frame is not torn. Needs the TE pin: onboard() reads the te key of the board's display block (GPIO 18 on this board), and without it the constructor throws \ValueError vsync needs the TE pin (te:).
buffered: true A second framebuffer (259 200 bytes at 360 x 360): flush() copies the region there and the panel reads the copy, so drawing never waits. A full-frame flush() returns only after the copy (about 13.6 ms), so it pays off when drawing overlaps the transfer, not for clear() plus flush() of the whole screen (about 30 fps buffered against 34 fps without).

onVsync() needs the TE pin but not the vsync option. The example 06-display/display-vsync runs a rectangle on onVsync() frames and prints the transfer time from onFlushed(); 06-display/display-hello-event-driven uses onVsync() as its frame clock.

php the panel as metronome
<?php
use Baremetal\Events;
use Baremetal\Spi\Driver\St77916;
use Baremetal\TimerEvent;

final class Frame extends TimerEvent {}

$lcd = St77916::onboard(vsync: true);
$lcd->onVsync(Frame::class);
Events::listen(Frame::class, function (Frame $e) use ($lcd): void {
    $lcd->fillRect(0, 0, 60, 60, $lcd->rgb(255, 0, 0));
    $lcd->flush(0, 0, 60, 60);   // returns before the transfer ends
});

The panel memory is not cleared at start: call fill() first. The driver owns the wire, so transfer(), write() and read() on an St77916 always fail with ESP_ERR_INVALID_STATE.

OLED displays on I2C

The 06-display folder has two more examples, oled-ssd1306-ext and oled-ssd1306-fps. They drive an SSD1306 128 x 32 OLED over I2C (SDA on GPIO 7, SCL on GPIO 8) on waveshare-esp32-p4-pico, and neither uses ext-spi or a registry package. They show two ways to add a driver that is not in the registry:

Example How the driver is added
oled-ssd1306-fps Pure PHP. composer.json requires only ext-sys and ext-gpio; the driver is the class SSD1306 in project-src/SSD1306.php, loaded with require __DIR__ . '/SSD1306.php'. It bit-bangs I2C over two pins with gpio_write() and gpio_read() and reports the frames per second.
oled-ssd1306-ext A project-local C extension. The extension is a folder extensions/ssd1306 with its own composer.json (type bm-ext, module ssd1306) and a C file. The project's composer.json lists it as a path repository ("url": "extensions/ssd1306") and requires it as php-baremetal-examples/ssd1306; phpbm flash compiles it into the firmware and the script calls ssd1306_begin(), ssd1306_text(), ssd1306_flush() and the other ssd1306_* functions.

The first one needs no C and is the easier start; the second is faster because the I2C link, the framebuffer and the text rendering run in C. The example keeps the same panel in both so that you can compare the frame rates.

SPI hosts and the board

ESP32 chips give Bus two general-purpose hosts, and the firmware may already use them:

What Host it takes
microsd storage in SPI mode SPI3_HOST (host: 2)
w5500 network SPI2_HOST (host: 1)

Opening a host the firmware already uses fails with ESP_ERR_INVALID_STATE. With microSD storage keep the default host: 1; with a W5500 network pass host: 2. A board that uses both (waveshare-esp32-s3-eth with microsd and the network on) has no host left for Bus. Board wiring is in Supported boards.

What the ESP32 does

Behaviour Detail
Transfers One call blocks the PHP task until the transfer is done; no other task is involved
Size At most 32768 bytes per call; more fails with ESP_ERR_INVALID_SIZE, so split it
DMA Hosts use DMA on an automatic channel; PHP strings are copied through a bounce buffer
Limits 2 buses and 8 devices in all (each display takes one)
Clock 1 MHz by default; $hz and $mode (0 to 3) are not checked by ext-spi, and are ignored when the chip select is already attached
Display clock The ST77916 runs at 40 MHz in quad mode; a full-panel fill takes about 17 ms at 360 x 360
Light sleep With power-save on, or after sys_light_sleep(), the QSPI lines may be disturbed: call $lcd->wake(), then repaint
Lifetime Buses and devices stay open until the board restarts, across requests too

Common errors

Message Cause
cannot open SPI host N: ... The host or a pin is used by a bus on other pins, both bus slots are in use, or the firmware already uses the host
cannot add SPI device cs=N: ... The chip select is held by a driver, or all 8 device slots are in use
SPI transfer failed: ... The transfer failed, was too long, or the device is an St77916
display on cs N already initialised with different parameters The panel was already created on this bus and CS with other arguments
st77916 init failed: ... Out of internal RAM for the band buffer, or the panel did not initialise
st77916 fill failed: ... A band did not finish within 1 second (ESP_ERR_TIMEOUT)
st77916 failed: a display transfer never completed After a timeout the panel refuses to draw until the board restarts

The full API is on the ext-spi and esp32-display-st77916 package pages.

Last updated 2026-11-15 · v2.0.x Edit on GitHub Report issue