Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/esp32-display-st77916

bm-lib MIT

ST77916 QSPI round display driver for ext-spi and ext-display (Baremetal\Spi\Driver\St77916, an Output\Display) over ESP-IDF's esp_lcd.

bus: spi

esp32-display-st77916 · PHP API

St77916

Baremetal\Spi\Driver\St77916: onboard(), the constructor that brings the panel up, fill(), and the Output\Display methods it gets from ext-display.

Baremetal\Spi\Driver\St77916 extends Baremetal\Spi\Device and implements Baremetal\Output\Display. Colours are RGB565 integers: 5 bits red, 6 green, 5 blue, 0x0000 black, 0xFFFF white; rgb() builds them.

Drawing goes to a framebuffer that ext-display keeps for the panel; flush() starts sending it to the panel and returns at once, while the driver's flush task moves the bytes (see Flush). The panel memory is not cleared at start-up, so draw the whole screen (or fill()) first.

REFRESH_HZ

St77916::REFRESH_HZ (60.0) is the panel's nominal refresh rate with this driver's init sequences, and what refreshRate() returns. The real rate drifts a little from it: on a Waveshare ESP32-S3-Touch-LCD-1.85B the panel's TE line (tearing effect, GPIO 18 on that board) pulses at 60.03 to 60.08 Hz, about 0.7 ms high per frame, measured over 3 s twice (2026-11-05). A timer at 60.0 Hz therefore slips one frame every 20 to 30 seconds; give the driver the TE pin ($te, or the board's te key) and use onVsync() to follow the panel's own frames.

onboard()

St77916::onboard(string $block = 'display', bool $buffered = false, bool $vsync = false): St77916

Public static method. Returns St77916.

Opens the panel described by a block of the board the firmware was built for. The block must be of type st77916, with the keys:

Key Meaning
sclk, d0, d1, d2, d3 The QSPI bus: clock and the four data lines.
cs, rst, bl Chip select, reset and backlight GPIOs (-1 for a line that is not wired).
width, height The drawing area in pixels.
gap-x, gap-y Optional, default 0: the constructor's $x_gap and $y_gap.
mirror-x, mirror-y, swap-xy Optional, default 0: the constructor's $mirror_x, $mirror_y and $swap_xy (1 for on).
te Optional: the panel's TE (tearing effect) GPIO, the constructor's $te; -1 when the key is missing.

onboard() opens new Bus(sclk, d0, d1, d2, d3) on SPI host 1, then constructs the panel on it, as new St77916($bus, cs, rst, bl, width, height, gap-x, gap-y, mirror-x, mirror-y, swap-xy, false, te, $buffered, $vsync) does. $buffered and $vsync are the constructor's options. The Waveshare ESP32-S3-Touch-LCD-1.85B has such a block (display, with te on GPIO 18). Pass another block name when a board describes more than one panel.

Throws \RuntimeException:

Message When
board '<id>' has no '<block>' block The board has no such block.
board '<id>' has a <block> of type '<type>', not 'st77916' The block describes another panel.
board '<id>': <block>.<key> is missing A required key is missing (or is not a number).

The errors of new Bus() and of the constructor pass through unchanged. $vsync on a block without te throws \ValueError Baremetal\Spi\Driver\St77916: vsync needs the TE pin (te:) before the bus is opened.

php the board's panel
<?php
use Baremetal\Spi\Driver\St77916;

$lcd = St77916::onboard();
$lcd->fill($lcd->rgb(0, 0, 0));

Constructor

new St77916(Bus $bus, int $cs = 21, int $rst = 3, int $bl = -1, int $width = 360, int $height = 360, int $x_gap = 0, int $y_gap = 0, bool $mirror_x = false, bool $mirror_y = false, bool $swap_xy = false, bool $invert = false, int $te = -1, bool $buffered = false, bool $vsync = false)

Public method.

Parameters

$bus Bus required

A Baremetal\Spi\Bus opened as QSPI: pass sclk, mosi (data 0), miso (data 1), data2 and data3.

$cs int optional, default 21

Chip-select GPIO.

$rst int optional, default 3

Reset GPIO, pulsed at construction and by wake(). -1 when the reset line is not wired to a GPIO.

$bl int optional, default -1

Backlight GPIO, driven high once the panel is on. -1 leaves the backlight alone; backlight() then does nothing.

$width int optional, default 360

Width of the drawing area in pixels, 1 to 4096: the panel's width, or its height with $swap_xy.

$height int optional, default 360

Height of the drawing area in pixels, 1 to 4096: the panel's height, or its width with $swap_xy.

$x_gap int optional, default 0

Column offset of the visible area in the controller's memory.

$y_gap int optional, default 0

Row offset of the visible area.

$mirror_x bool optional, default false

Mirror horizontally.

$mirror_y bool optional, default false

Mirror vertically.

$swap_xy bool optional, default false

Swap the axes; with a mirror this rotates the picture by 90 degrees. The driver does not swap $width and $height for you: the framebuffer and the drawing clip to them as given, which matters only on a panel that is not square.

$invert bool optional, default false

Invert colours, for panels wired with inverted polarity.

$te int optional, default -1

The GPIO of the panel's TE (tearing effect) output, -1 when it is not wired. The pin belongs to the display: ext-display attaches a falling-edge interrupt there (with $vsync, or at the first onVsync()), so a watch_gpio() on the same pin takes it away from the display.

$buffered bool optional, default false

A second framebuffer (width x height x 2 bytes, 259 200 bytes at 360 x 360, PSRAM on boards that have it): flush() copies the region there and the panel reads the copy, so drawing never waits for a flush.

$vsync bool optional, default false

Every region starts at the next TE pulse, so a region shorter than one frame is not torn. Needs $te.

On the first construction for a bus and CS, the driver:

  1. allocates its two ping-pong bands (width x 20 pixels each, DMA-capable internal RAM);
  2. pulses reset (20 ms low, then 120 ms wait) when $rst is not -1;
  3. reads the panel's ID register at 5 MHz to pick one of two init sequences (two silicon variants);
  4. opens the esp_lcd panel IO on the bus's host at 40 MHz in quad mode, sends a software reset and the init sequence;
  5. applies swap_xy, mirroring, gaps and inversion, turns the display on;
  6. starts its flush task on core 1, one priority above the task that constructs it, then drives the backlight high.

Every construction then gives the object its own framebuffer (width x height x 2 bytes, cleared to black). A later construction with the same bus and CS and the same arguments reuses the running panel; with any argument different it throws display on cs N already initialised with different parameters.

Throws \ValueError when $width or $height is outside 1 to 4096, or $cs, $rst, $bl or $te outside -1 to 255, \ValueError Baremetal\Spi\Driver\St77916: vsync needs the TE pin (te:) for $vsync with $te -1 (before the hardware is touched), and \Exception with cannot reserve st77916 (cs=N): ... (CS taken by another device, or no free device slot), st77916 init failed: ... (out of memory, or an esp_lcd error) or st77916: cannot attach the drawing surface (error 0x101) (no memory for the framebuffer, or for the copy of $buffered). After a failed init the next construction tries again.

fill()

St77916::fill(int $color): void

Public method. Returns void.

clear($color) followed by flush(): paints the whole screen with $color (the low 16 bits are used) and sends it.

Output\Display methods

The class has every method of Baremetal\Output\Display, implemented by ext-display; see its PHP API. On this panel:

Method Behaviour
width(), height() $width and $height of the constructor.
rgb(), clear(), pixel(), line(), rect(), fillRect(), circle(), fillCircle(), text(), textWidth(), image() Draw into the framebuffer, clipped to the screen; nothing reaches the panel before flush(). rect() draws the outline, fillRect() the filled rectangle.
flush() Starts sending the changed region (or the region given) and returns at once; see Flush.
flushWait() Returns once nothing is in flight or pending.
onFlushed(), onVsync() Events at the end of each region and at each TE pulse; onVsync() needs $te.
backlight(int $level) Backlight pin on for $level 1 to 255, off for 0. There is no PWM, so no dimming. Nothing without a backlight pin.
sleep() Waits for the flush in flight (with vsync, a region still waiting for the TE pulse is dropped), then turns the display off (DISPOFF) and the backlight pin low.
wake() Re-initialises the panel (reset, init sequence, orientation, display on), puts the backlight back as the last backlight() left it (on by default) and marks the whole screen as changed, so the next flush() sends the full frame. Use it after a light sleep; see Errors, limits and sleep.

Flush

The driver has a FreeRTOS flush task on core 1, at a priority above the PHP task, that sends the regions ext-display gives it. A region at full width whose rows the DMA can read goes out from them as they are, 60 rows per transfer. Any other region goes through two ping-pong bands of 20 rows at full width in internal RAM: while one is in DMA, the task gathers the next. The bands (2 x 14 400 bytes on a 360-wide panel) are allocated by the first region that needs them and kept until the panel is closed; a renderer on the band path never flushes, so it never allocates them. Without the internal RAM for them that flush fails with ESP_ERR_NO_MEM, thrown at the next call on the display. With the framebuffer in PSRAM (the default on boards that have it) every region takes the bands. After each band the rows already sent are free to draw on again; ext-display makes a drawing wait only when it touches rows not sent yet. A band that does not finish within 1 second fails the flush, and the error is thrown at the next call on the display.

Band path

A renderer that holds the panel (ext-display's display_claim()) sends its picture through the band path of ext-display 1.1 instead of the surface's flush(). The driver advertises bands of 40 rows, at most 28 800 bytes (360 x 40 x 2), and own_ram: the panel keeps what it received. buf_alloc() returns DMA-capable internal RAM. push() hands the band to the flush task and returns; it blocks only when 3 bands are in flight. The flush task sends the bands in push order, waits for each transfer, then calls the band's done (always in the task, never in the DMA interrupt). end() does not wait for the bands. The band path never waits for the TE pulse: a renderer paces its frames on onVsync() itself. The driver tells the renderer the order of the panel's refresh (scan in the band path): the panel reads its memory from the first row after each TE pulse, so top to bottom in the default orientation, bottom to top with mirror_y, and across the columns with swap_xy. A renderer such as Slate uses it to write each band where the refresh is not reading, so that moving content does not tear. After a transfer timeout the panel is marked failed: every later begin and push returns ESP_ERR_INVALID_STATE (BM_ERR_INVALID_STATE of the band contract), and the renderer stops (Slate throws \RuntimeException Slate: the panel refused the bands (error 0x103)). sleep() and wake() wait for the bands already accepted first and hold the panel until they return (a push() meanwhile blocks, and gives up with ESP_ERR_TIMEOUT after 5 s); wake() re-initialises the panel and calls display_invalidate(), which tells the renderer holding the panel to send its whole frame again (Slate does).

Inherited methods

transfer(), write() and read() from Device throw SPI ... failed: ESP_ERR_INVALID_STATE on this class: the driver owns the wire through esp_lcd.

php a framed panel
<?php
use Baremetal\Spi\Driver\St77916;

$lcd = St77916::onboard();

$black = $lcd->rgb(0, 0, 0);
$teal  = $lcd->rgb(0, 128, 128);
$white = $lcd->rgb(255, 255, 255);

$lcd->clear($teal);
$lcd->fillRect(40, 40, 280, 280, $black);     // leaves a 40 px teal frame
$lcd->rect(60, 60, 240, 240, $white);         // a white outline inside it
$lcd->text(130, 170, 'ST77916', $white);
$lcd->flush();

Related