From da81864d2fe6010e8493e17cee4d5d6444b2918f Mon Sep 17 00:00:00 2001 From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com> Date: Wed, 23 Sep 2026 14:44:10 -0500 Subject: [PATCH 1/3] docs: add displayif newcomer guide --- README.md | 3 ++ docs/newcomers.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 docs/newcomers.md diff --git a/README.md b/README.md index 1954d32..644cfc7 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,9 @@ Native display **interface** modules for PyDevices `displaydev`. Portable code in `src/ports/common/`; SoC-specific code under `src/ports//`. +New here? Read the [newcomer's guide](docs/newcomers.md) for the board-to- +backend map, firmware integration boundary, and lifecycle rules. + MicroPython board configs in `pydevices` that raise `NotImplementedError` on import need firmware built with the matching displayif module. Native C modules register directly — **no Python re-export layer** in this repo. **CircuitPython** already has MCU display interfaces (`dotclockframebuffer`, `mipidsi`, `picodvi`, …) — use `pydevices/board_configs/cp/` with stock CP firmware for those. **Exception:** desktop `usdl2` (unix) is built from this repo via `./apply_cp_patches.sh` + CircuitPython unix. diff --git a/docs/newcomers.md b/docs/newcomers.md new file mode 100644 index 0000000..3615f26 --- /dev/null +++ b/docs/newcomers.md @@ -0,0 +1,80 @@ +# Newcomer's guide to displayif + +`displayif` supplies native display-interface modules for PyDevices +`displaydev` board configurations. It is source-integrated firmware code, not +a package: a board uses it only when its MicroPython firmware was built with +the required `USER_C_MODULES` backend. + +Start from a board configuration in [pydevices](https://github.com/PyDevices/pydevices), +then identify the matching interface in [the port matrix](port-matrix.md). +For example, an ESP32-P4 DSI board needs `mipidsi`, an RGB framebuffer may +need `dotclockframebuffer`, and a desktop MicroPython application uses +`usdl2`. + +## The mental model + +```text +pydevices board_config + | + v +displaydev backend (BusDisplay, FBDisplay, or SDLDisplay) + | + v +displayif native module for the selected MicroPython port + | + v +panel bus, framebuffer, DSI, DVI, RGB matrix, or SDL2 window +``` + +Python does not import a wrapper package from this repository. Native modules +register directly in firmware, so a board config that raises +`NotImplementedError` normally indicates firmware missing its required +displayif backend. + +## Choose the supported path + +CircuitPython already provides its MCU display interfaces; use its stock +firmware and the CircuitPython board configs for those targets. The exception +is desktop `usdl2`, which displayif can add to CircuitPython unix through +`apply_cp_patches.sh`. + +For MicroPython Make ports, `USER_C_MODULES` points at the workspace parent +containing this repository. For CMake ports such as ESP32 and RP2, it points +at this repository (or `micropython.cmake`). The root README gives the exact +commands and shows how to combine several CMake user modules. + +## Repository map + +| Path | Purpose | +|---|---| +| `src/ports/common/` | Shared buses, helpers, RGB matrix code, and lifecycle support. | +| `src/ports//` | SoC-specific backends for ESP32, RP2, SAMD, MIMXRT, and others. | +| `src/ports/desktop/usdl2/` | SDL2 desktop backend for MicroPython unix and Windows. | +| `src/jpegio/` | Platform-neutral JPEG decoder and optional LVGL decoder integration. | +| `src/include/displayif/` | Public native headers. | +| `micropython.mk`, `micropython.cmake` | Make/CMake user-module entrypoints. | +| `docs/port-matrix.md` | Module/port/board-config support matrix. | +| `docs/idempotent-lifecycle.md` | Required init, deinit, and soft-reset contract. | +| `docs/soft-reset-and-bring-up.md` | Evidence-based bring-up and debugging procedure. | +| `tests/`, `tools/` | API checks and hardware/desktop smoke tools. | + +## The important invariant + +Every accelerated interface must support safe, repeatable construction and +teardown. `deinit`, destructors, soft reset, and a second constructor call all +release the same non-GC resources. Do not work around failures with hard +resets or board-config special cases; follow +[the lifecycle contract](idempotent-lifecycle.md) and +[the bring-up guide](soft-reset-and-bring-up.md). + +## Contributor boundary + +This is native portability work. Read [AGENTS.md](../AGENTS.md) before +changing lifecycle, soft-reset, board bring-up, or QSTR definitions. A new +backend needs the appropriate port build, a real smoke test, then a soft reset +and successful second construction. Use `mpftp` for supported build/flash +workflows when available. + +For a safe first contribution, improve a port note, add a focused API test, or +clarify a matrix entry. Keep generated firmware artifacts and upstream +MicroPython/CircuitPython checkout changes out of this repository. From 168c30269ebd55aa884dfe38be126d554f925f20 Mon Sep 17 00:00:00 2001 From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com> Date: Wed, 23 Sep 2026 15:58:10 -0500 Subject: [PATCH 2/3] README, UPSTREAM: MicroPython v1.29.0 pin, drop the deleted cmods link --- README.md | 4 +--- UPSTREAM | 6 +++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 644cfc7..e3cbdcc 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ RGB and DSI framebuffers prefer **PSRAM** (`MALLOC_CAP_SPIRAM`). Ensure `CONFIG_ ## 🚀 Build -Tested against MicroPython v1.28.0, the CircuitPython 10.2.1 oracle, and SDL2 >= 2.0 +Tested against MicroPython v1.29.0, the CircuitPython 10.2.1 oracle, and SDL2 >= 2.0 (desktop `usdl2`) — see [UPSTREAM](UPSTREAM) for exact pins and how to verify them locally. Clone as a sibling of `micropython/`: @@ -91,8 +91,6 @@ cd micropython/ports/windows && make USER_C_MODULES=../../.. CircuitPython unix: `./apply_cp_patches.sh --apply --port unix --variant coverage`, then build the unix port. -See the [org's optional aggregator workspace](https://github.com/PyDevices/cmods) for an easier way to build this repo with other user C modules. - ### First run (unix `usdl2` smoke) Once the unix port above is built, prove it imports and can drive SDL2: diff --git a/UPSTREAM b/UPSTREAM index 0a24ef4..ec517e6 100644 --- a/UPSTREAM +++ b/UPSTREAM @@ -5,9 +5,9 @@ # and where the one vendored third-party source tree came from. ## MicroPython -Org-pinned upstream (matches the MicroPython checkout in the org's optional aggregator workspace): v1.28.0 - https://github.com/micropython/micropython @ v1.28.0 - Verify locally with: git -C describe --tags # expect v1.28.0 +Org-pinned upstream (the ref CI builds against): v1.29.0 + https://github.com/micropython/micropython @ v1.29.0 + Verify locally with: git -C describe --tags # expect v1.29.0 ## CircuitPython (usdl2 desktop path only, via apply_cp_patches.sh) Org oracle (same pin as audiodsp/CIRCUITPYTHON_ORACLE): 10.2.1 From 2adc9648c16a5412edd34d0af30ef1768c1ed195 Mon Sep 17 00:00:00 2001 From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com> Date: Wed, 23 Sep 2026 15:58:10 -0500 Subject: [PATCH 3/3] newcomers: stm32 builds portable buses only; drop the mpftp line --- docs/newcomers.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/newcomers.md b/docs/newcomers.md index 3615f26..e08f427 100644 --- a/docs/newcomers.md +++ b/docs/newcomers.md @@ -48,7 +48,7 @@ commands and shows how to combine several CMake user modules. | Path | Purpose | |---|---| | `src/ports/common/` | Shared buses, helpers, RGB matrix code, and lifecycle support. | -| `src/ports//` | SoC-specific backends for ESP32, RP2, SAMD, MIMXRT, and others. | +| `src/ports//` | SoC-specific backends for ESP32, RP2, SAMD, and MIMXRT; `stm32` builds the portable buses only. | | `src/ports/desktop/usdl2/` | SDL2 desktop backend for MicroPython unix and Windows. | | `src/jpegio/` | Platform-neutral JPEG decoder and optional LVGL decoder integration. | | `src/include/displayif/` | Public native headers. | @@ -72,8 +72,7 @@ resets or board-config special cases; follow This is native portability work. Read [AGENTS.md](../AGENTS.md) before changing lifecycle, soft-reset, board bring-up, or QSTR definitions. A new backend needs the appropriate port build, a real smoke test, then a soft reset -and successful second construction. Use `mpftp` for supported build/flash -workflows when available. +and successful second construction. For a safe first contribution, improve a port note, add a focused API test, or clarify a matrix entry. Keep generated firmware artifacts and upstream