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
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
-
$busBusrequired A
Baremetal\Spi\Busopened as QSPI: passsclk,mosi(data 0),miso(data 1),data2anddata3.-
$csintoptional, default21 Chip-select GPIO.
-
$rstintoptional, default3 Reset GPIO, pulsed at construction and by
wake().-1when the reset line is not wired to a GPIO.-
$blintoptional, default-1 Backlight GPIO, driven high once the panel is on.
-1leaves the backlight alone;backlight()then does nothing.-
$widthintoptional, default360 Width of the drawing area in pixels, 1 to 4096: the panel's width, or its height with
$swap_xy.-
$heightintoptional, default360 Height of the drawing area in pixels, 1 to 4096: the panel's height, or its width with
$swap_xy.-
$x_gapintoptional, default0 Column offset of the visible area in the controller's memory.
-
$y_gapintoptional, default0 Row offset of the visible area.
-
$mirror_xbooloptional, defaultfalse Mirror horizontally.
-
$mirror_ybooloptional, defaultfalse Mirror vertically.
-
$swap_xybooloptional, defaultfalse Swap the axes; with a mirror this rotates the picture by 90 degrees. The driver does not swap
$widthand$heightfor you: the framebuffer and the drawing clip to them as given, which matters only on a panel that is not square.-
$invertbooloptional, defaultfalse Invert colours, for panels wired with inverted polarity.
-
$teintoptional, default-1 The GPIO of the panel's TE (tearing effect) output,
-1when it is not wired. The pin belongs to the display: ext-display attaches a falling-edge interrupt there (with$vsync, or at the firstonVsync()), so awatch_gpio()on the same pin takes it away from the display.-
$bufferedbooloptional, defaultfalse A second framebuffer (
widthxheightx 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.-
$vsyncbooloptional, defaultfalse 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:
- allocates its two ping-pong bands (
widthx 20 pixels each, DMA-capable internal RAM); - pulses reset (20 ms low, then 120 ms wait) when
$rstis not-1; - reads the panel's ID register at 5 MHz to pick one of two init sequences (two silicon variants);
- opens the
esp_lcdpanel IO on the bus's host at 40 MHz in quad mode, sends a software reset and the init sequence; - applies
swap_xy, mirroring, gaps and inversion, turns the display on; - 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
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
- Errors, limits and sleep Reference
- Draw bars Recipe
- ext-display API Extension
- ext-spi Bus Extension