docs: add displayif newcomer guide

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/<mp-port>/`.
 
+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.
@@ -42,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/`:
@@ -88,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:

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 <your micropython checkout> 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 <your micropython checkout> 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

docs/newcomers.md

@@ -0,0 +1,79 @@
+# 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/<port>/` | 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. |
+| `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.
+
+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.