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

A driver for ST77916 QSPI round displays (360 x 360 by default), for ext-spi and ext-display. It adds Baremetal\Spi\Driver\St77916, a Baremetal\Spi\Device that implements Baremetal\Output\Display: the panel gets a framebuffer and every drawing method of ext-display (primitives, text, images, region flush), plus backlight and sleep. St77916::REFRESH_HZ (60 Hz, also refreshRate()) is the panel's nominal refresh rate; measured on a Waveshare ESP32-S3-Touch-LCD-1.85B, the panel runs at 60.03 to 60.08 Hz. It runs on ESP32 only (it uses ESP-IDF's esp_lcd).

Install

In a project created with phpbm init:

bash
composer require php-baremetal/esp32-display-st77916

The driver requires ext-spi and ext-display, so this line is enough.

It declares the board block display:st77916, so phpbm init and phpbm board offer it on boards with an on-board ST77916 panel.

Example

On a board whose description has the panel (the Waveshare ESP32-S3-Touch-LCD-1.85B), onboard() opens it with the board's pins:

php
<?php
use Baremetal\Spi\Driver\St77916;

$lcd = St77916::onboard();

$lcd->clear($lcd->rgb(0, 0, 64));                            // dark blue
$lcd->fillRect(130, 130, 100, 100, $lcd->rgb(255, 160, 0));  // orange square in the middle
$lcd->text(120, 250, 'Hello', $lcd->rgb(255, 255, 255));
$lcd->flush();                                               // drawing goes to the panel here

On another board, pass the bus and pins: new St77916(new Bus(sclk: 40, mosi: 46, miso: 45, data2: 42, data3: 41), cs: 21, rst: 3, bl: 5).

Asynchronous flush

flush() returns at once: a FreeRTOS flush task of the driver, on core 1 and one priority above the PHP task, sends the region through two ping-pong bands of 20 rows (in DMA-capable internal RAM, 14 400 bytes each at 360 wide): while one band is in DMA, the task gathers the next. A drawing waits only when it touches rows not sent yet; flushWait() waits for the whole flush.

Three constructor options go with it, after $invert:

Option Default Effect
te -1 The GPIO of the panel's TE (tearing effect) output. Needed by vsync and onVsync().
buffered 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 false Every region starts at the next TE pulse. Needs te: without it, \ValueError Baremetal\Spi\Driver\St77916: vsync needs the TE pin (te:).

onboard(string $block = 'display', bool $buffered = false, bool $vsync = false) takes the TE pin from the block's optional te key (GPIO 18 on the Waveshare ESP32-S3-Touch-LCD-1.85B):

php
$lcd = St77916::onboard(vsync: true);   // each flush() starts at the panel's next frame

The TE pin belongs to the display: ext-display attaches its interrupt there, so a watch_gpio() on the same pin takes it away from the display.

Band path

Since 1.2 the driver also offers the band path of ext-display 1.1, for renderers such as Slate that compose a picture outside the framebuffer and send it band by band (it requires php-baremetal/ext-display ^1.1). Bands are 40 rows of at most 360 pixels (28 800 bytes) in DMA-capable internal RAM that the driver allocates, and the panel keeps its picture, so a renderer sends only what changed. The flush task of the asynchronous flush sends them, in order, and runs each band's done once its transfer ended. The band path never waits for the TE pulse: a renderer paces its frames on onVsync() itself; the driver tells it the order of the panel's refresh (top to bottom, bottom to top with mirror_y, across the columns with swap_xy), so that it can write without tearing. After a transfer timeout the panel is marked failed: every later band op returns ESP_ERR_INVALID_STATE, which the renderer takes as final. sleep() and wake() run after the bands already accepted, and wake() tells the renderer to send its whole frame again. The surface's own flush() does not use this path, and it does not run while a renderer holds the panel.

Documentation

License

MIT. src/esp_lcd_st77916.c, src/esp_lcd_st77916.h and the init tables in src/st77916_init_cmds.h come from Espressif's ST77916 esp_lcd reference driver (Apache-2.0).

Read the full documentation