displayif

August 12, 2026 · View on GitHub

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

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.

Status: Accelerated interfaces on esp32, mimxrt, samd, and rp2. See 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 and the port notes in docs/port-matrix.md.

Agents: start at AGENTS.md. Soft-reset / idempotent lifecycle (implemented): docs/idempotent-lifecycle.md. Bring-up / failure modes (P4 mipidsi, Qualia dotclockframebuffer.DotClockFramebuffer): docs/soft-reset-and-bring-up.md.

Native modules

ModulePort treedisplaydev backend
spibus / i2cbuscommonBusDisplay
dotclockframebufferesp32 (RGB LCD), mimxrt (1062 eLCDIF)FBDisplay
i80busesp32 (S3), rp2 (PIO+DMA), mimxrt (1062 FlexIO), samd (SAMD51 GPIO)BusDisplay
qspibusesp32 (S3 esp_lcd SPI quad_mode); stubs elsewhereBusDisplay
mipidsiesp32 (P4), mimxrt (1176)FBDisplay
picodvirp2 (RP2040 PIO / RP2350 HSTX)FBDisplay
rgbmatrixesp32 (S3) / mimxrt (1062) / samd (SAMD51) / rp2FBDisplay
usdl2desktop (MicroPython unix / windows; CircuitPython unix via apply_cp_patches.sh)SDLDisplay
stubssamd / rp2 / non-1062 mimxrt (dotclockframebuffer.DotClockFramebuffer, mipidsi); non-1176 mimxrt (mipidsi); non-S3 qspibusctor raises

Parallel dot-clock RGB uses dotclockframebuffer.DotClockFramebuffer (same module name as CircuitPython) — no RGBDisplay.

ESP32 large framebuffers

RGB and DSI framebuffers prefer PSRAM (MALLOC_CAP_SPIRAM). Ensure CONFIG_SPIRAM is enabled and sized in your board sdkconfig before building — see docs/port-matrix.md.

🚀 Build

Clone as a sibling of micropython/:

workspace/
  displayif/      ← this repo
  micropython/

Make ports (mimxrt, samd, …): USER_C_MODULES is the workspace parent (directory that contains displayif/ and any other */micropython.mk siblings):

cd micropython/ports/mimxrt && make USER_C_MODULES=../../.. BOARD=TEENSY41
cd micropython/ports/samd && make USER_C_MODULES=../../.. BOARD=ADAFRUIT_METRO_M4_EXPRESS

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

cd micropython/ports/esp32
make submodules BOARD=ESP32_GENERIC_S3
make BOARD=ESP32_GENERIC_S3 USER_C_MODULES=../../../displayif

cd micropython/ports/rp2
make BOARD=RPI_PICO USER_C_MODULES=../../../displayif

To build this module plus other usermods on a CMake port, pass a semicolon-separated list (no aggregator file required):

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 and SDL2_DEV pointing at its root (see tools/sdl2_dev_env.sh).

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=../../..

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

See the cmods workspace for an easier way to build this repo with other user C modules.