Skip to content

README: one include() line adds this module to your own build #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bdbarnett merged 1 commit into from
Sep 24, 2026
Merged

README: one include() line adds this module to your own build #40

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 37 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# displayif

**Status:** source-integrated component — built into firmware from source as a `USER_C_MODULES` usermod, not installed as a package. By design it has no versioned releases and is **not** in PyDevices' publishing set (unlike `pydevices` / `pydevices-desktop`). Maturity: **Alpha**. Issues: [PyDevices/displayif/issues](https://github.com/PyDevices/displayif/issues).
**Status:** source-integrated component — built into firmware from source as a user C module, not installed as a package. By design it has no versioned releases and is **not** in PyDevices' publishing set (unlike `pydevices` / `pydevices-desktop`). Maturity: **Alpha**. Issues: [PyDevices/displayif/issues](https://github.com/PyDevices/displayif/issues).

Native display **interface** modules for PyDevices `displaydev`. Portable code in `src/ports/common/`; SoC-specific code under `src/ports/<mp-port>/`.

Expand All @@ -13,7 +13,7 @@ MicroPython board configs in `pydevices` that raise `NotImplementedError` on imp

**Status:** Accelerated interfaces on esp32, mimxrt, samd, and rp2. See [docs/port-matrix.md](docs/port-matrix.md).

Use this repo when a `pydevices` board config needs a native display interface that is not available in the stock MicroPython port. In practice, you usually start with the target board’s port and the relevant display backend (for example `mipidsi`, `dotclockframebuffer`, or `picodvi`), then build the firmware with the matching `USER_C_MODULES` path. If you are debugging a bring-up problem, begin with [docs/soft-reset-and-bring-up.md](docs/soft-reset-and-bring-up.md) and the port notes in [docs/port-matrix.md](docs/port-matrix.md).
Use this repo when a `pydevices` board config needs a native display interface that is not available in the stock MicroPython port. In practice, you usually start with the target board’s port and the relevant display backend (for example `mipidsi`, `dotclockframebuffer`, or `picodvi`), then build the firmware with this module in it (see [Build](#-build)). If you are debugging a bring-up problem, begin with [docs/soft-reset-and-bring-up.md](docs/soft-reset-and-bring-up.md) and the port notes in [docs/port-matrix.md](docs/port-matrix.md).

**Agents:** start at [AGENTS.md](AGENTS.md). Soft-reset / idempotent lifecycle
(**implemented**): [docs/idempotent-lifecycle.md](docs/idempotent-lifecycle.md). Bring-up /
Expand Down Expand Up @@ -48,47 +48,60 @@ RGB and DSI framebuffers prefer **PSRAM** (`MALLOC_CAP_SPIRAM`). Ensure `CONFIG_
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/`:
On MicroPython 1.29 or later, clone this repository anywhere and add one line
to the manifest your build already uses:

```
workspace/
displayif/ ← this repo
micropython/
```python
include("/path/to/displayif/manifest.py")
```

**Make ports** (mimxrt, samd, …): `USER_C_MODULES` is the **workspace parent** (directory that contains `displayif/` and any other `*/micropython.mk` siblings):
On unix that manifest is `ports/unix/variants/standard/manifest.py`; on esp32
and rp2 it is usually `ports/<port>/boards/manifest.py`, unless your board
brings its own. Then build as usual:

```bash
cd micropython/ports/mimxrt && make USER_C_MODULES=../../.. BOARD=TEENSY41
cd micropython/ports/samd && make USER_C_MODULES=../../.. BOARD=ADAFRUIT_METRO_M4_EXPRESS
# esp32, after sourcing ESP-IDF's export.sh
cd micropython/ports/esp32 && make BOARD=ESP32_GENERIC_S3
# or unix
cd micropython/ports/unix && make submodules && make
```

**CMake ports** (esp32, rp2): `USER_C_MODULES` points at **this repo** (or `displayif/micropython.cmake`). CMake does not scan siblings the way Make does:

```bash
cd micropython/ports/esp32
make submodules BOARD=ESP32_GENERIC_S3
make BOARD=ESP32_GENERIC_S3 USER_C_MODULES=../../../displayif
The manifest freezes no Python; it only names the C module, and the build glue
picks the modules your port supports (see [docs/port-matrix.md](docs/port-matrix.md)).
On unix that is `usdl2` and `jpegio`; the bus and framebuffer modules are
MCU-only. Tested on the unix port against MicroPython v1.29.0.

cd micropython/ports/rp2
make BOARD=RPI_PICO USER_C_MODULES=../../../displayif
```
If you would rather not edit the MicroPython tree, write a manifest of your own
and pass it as `FROZEN_MANIFEST=`. That replaces the port's default, so include
the default too (`include("$(PORT_DIR)/variants/standard/manifest.py")` on
unix, `include("$(PORT_DIR)/boards/manifest.py")` on esp32) or you lose
`asyncio` and the port's other frozen modules.

To build this module **plus** other usermods on a CMake port, pass a semicolon-separated list (no aggregator file required):
**Older than 1.29?** Manifests there have no `c_module()`; use
`USER_C_MODULES` instead. On esp32 and rp2 point it at this repository:

```bash
make BOARD=ESP32_GENERIC_S3 USER_C_MODULES=/abs/path/to/displayif
make BOARD=ESP32_GENERIC_S3 \
USER_C_MODULES="/abs/path/to/displayif;/abs/path/to/lvgl-micropython"
```

**Desktop SDL (`usdl2`):** builds automatically on MicroPython `unix` / `windows` when this repo is on the `USER_C_MODULES` scan path. Unix needs `libsdl2-dev`. Windows (MinGW) needs an unpacked [SDL2 MinGW development ZIP](https://github.com/libsdl-org/SDL/releases) and `SDL2_DEV` pointing at its root (see [`tools/sdl2_dev_env.sh`](tools/sdl2_dev_env.sh)).
On Make ports (unix, windows, mimxrt, samd) point it at the directory that
*contains* this repository, which builds every module in that directory:

```bash
cd micropython/ports/unix && make USER_C_MODULES=../../..
# windows: export SDL2_DEV=/path/to/SDL2-2.x.x first
cd micropython/ports/windows && make USER_C_MODULES=../../..
cd micropython/ports/samd && make USER_C_MODULES=../../.. BOARD=ADAFRUIT_METRO_M4_EXPRESS
```

**Desktop SDL (`usdl2`)** builds automatically on the `unix` and `windows`
ports. Unix needs `libsdl2-dev`. Windows (MinGW) needs an unpacked
[SDL2 MinGW development ZIP](https://github.com/libsdl-org/SDL/releases) and
`SDL2_DEV` pointing at its root (see [`tools/sdl2_dev_env.sh`](tools/sdl2_dev_env.sh)).

For several PyDevices modules at once,
[micropython-pydevices](https://github.com/PyDevices/micropython-pydevices)
keeps ready-made manifests, variants and boards.

CircuitPython unix: `./apply_cp_patches.sh --apply --port unix --variant coverage`, then build the unix port.

### First run (unix `usdl2` smoke)
Expand Down
Loading