Board configs
Every OmniPython app needs a board_config.py that describes its display and
input hardware without selecting an application event system. This page lists
every board that has one, what each exposes, and how to pick or write one.
For the stable end-device role names (touch, wlan, …), lazy PERIPHERALS
discovery, and the touch duck-type, see Board peripherals.
What board_config.py provides
Typically:
A
display_drvobject (BusDisplay, SDLDisplay, PGDisplay, FBDisplay, etc.)Neutral input callables when present:
host_read,touch_read,keypad_read,encoder_read, and related optionsRaw input hardware where useful (
touch,keypad,encoder,joystick)Optional setup (backlight pins, buses). On MicroPython, lazy extras move to
board_peripheralsunder the board peripherals contract. On CircuitPython,board_peripherals.pyis optional — the nativeboardmodule covers most non-UI peripherals.
Configs live in
PyDevices/omnipython
(board_configs/). Each MicroPython folder is a package named by the folder:
its manifest.py says what it installs, and requires the driver packages it
uses and omnipython, so one mip.install of the board brings everything. The
package.json beside it installs the same files from GitHub, and is written
from the manifest.
See the canonical commands and verification steps in Install. To add a board or a driver, or to mark one tested, see CONTRIBUTING.md.
CircuitPython configs live under board_configs/cp/ with the same bus layout and
directory names as MicroPython (no cp_ prefix; a board_peripherals.py is
optional and only a few configs have one). They have no manifest.py, but each
folder has a package.json, written from what its files import, so one
omip.install("github:PyDevices/omnipython/board_configs/cp/<folder>") brings
the config, the drivers it uses and the Adafruit libraries it imports.
MicroPython configs stay at the top level of board_configs/ (not under an
mp/ folder).
The CircuitPython console
CircuitPython shows its console on a board’s built-in screen, and every
print scrolls and redraws it. On an 800x480 panel, 50 short lines took
about four seconds with the console on the screen and a quarter of a second
without it, and a program that streams sound or network frames loses
whatever arrives during the stall.
So a OmniPython config keeps the console off the screen. A config that paints
the screen shows its own group in place of the console, one that drives the
panel itself releases the firmware’s display first, and any displaydev driver
takes the console off board.DISPLAY when it starts, if it’s still there.
What you print still reaches the serial console and the web workflow. A
config of your own that makes a framebufferio.FramebufferDisplay sets that
display’s root_group too, to its own group or to None.
A program that never imports board_config or makes a driver, such as a
headless app on a board with a screen, takes the console off itself:
import board
board.DISPLAY.root_group = None
displayio.release_displays() takes the console off as well, but it also
releases the screen the firmware set up, so use it only when nothing will
draw. To put the console back on the screen, for instance while you debug a
board with no serial cable:
import board
import displayio
board.DISPLAY.root_group = displayio.CIRCUITPYTHON_TERMINAL
Picking a config
Match in priority order:
Bus type — SPI vs I80 (parallel)
Display controller — ILI9341, ST7789, GC9A01, …
Touch controller — FT6X36, XPT2046, …
Microcontroller — ESP32-S3, RP2040, …
An exact match for all four is rare; bus + display controller is usually enough to adapt.
Installing a board’s config
import mip
mip.install(
"github:PyDevices/omnipython/board_configs/<path>"
)
Replace <path> with a directory from the tables below (for example
fbdisplay/esp32-p4-wifi6-touch-lcd-4b). The board package brings its drivers
and omnipython; its manifest.py lists them.
Every board
Config is a path under board_configs/, and a MicroPython tree: the ones with board_peripherals. CP says a CircuitPython twin exists under cp/ at the same path; those are eager-UI only (display_drv, app, touch, keypad, encoder, joystick), and the native board module covers the rest. display_drv, app and display_bus are part of every board’s surface and aren’t repeated in Eager UI. A blank role column means the config doesn’t list one, not that the board lacks the hardware. The roles a lazy factory names may still raise NotImplementedError until its chip driver lands: the set is the contract, not a promise of completeness. bt (Classic) is listed only where a board is known to have it.
SPI displays
Board |
Config |
CP |
Display and touch |
Eager UI |
Lazy |
|---|---|---|---|---|---|
DIY ESP32 + ILI9341 + XPT2046 |
|
||||
ESP32-WROVER-E ST7789 + joystick |
|
|
|
||
Adafruit FunHouse (no BLE on ESP32-S2) |
|
yes |
|
|
|
Adafruit HalloWing M4 |
|
yes |
— |
|
|
Ai-Thinker ESP32-Audio-Kit V2.2 + 2.8” ILI9341 IPS touch module |
|
||||
Adafruit QT Py ESP32 Pico + EyeSPI ILI9341 |
|
||||
Adafruit ESP32-S3 QT Py + EyeSPI ILI9341 |
|
||||
QT Py RP2040 + EyeSPI ILI9341 |
|
||||
Pico + UNO-style shield |
|
||||
M5Stack CoreS3 (AW88298/ES7210/BMI270 wired; camera stub) |
|
|
|
||
Adafruit Metro M7 + TFT shield 1947 |
|
240×320, ILI9341 SPI ( |
|
|
|
ST NUCLEO-H743ZI2 + TFT shield 1947 |
|
240×320, ILI9341 SPI ( |
|
|
|
ODROID-GO |
|
|
|
||
Pico LCD 1.8” |
|
||||
Waveshare Pico-OLED-2.23 and Pico-Audio on a Pico |
|
128×32, SSD1305 SPI |
|
||
3.5” TFT FeatherWing (HX8357D) (host-dependent STEMMA) |
|
yes |
|
|
|
3.5” TFT FeatherWing, HX8357D + STMPE610 on an Adafruit Feather ESP32 V2 |
|
||||
PiTFT ILI9341 FeatherWing (host-dependent STEMMA) |
|
yes |
|
|
|
Adafruit PyBadge |
|
yes |
|
|
|
Adafruit PyGamer |
|
yes |
|
|
|
Adafruit PyPortal (AirLift as |
|
yes |
|
|
|
Adafruit PyPortal Titano |
|
yes |
|
|
|
Waveshare RP2040-Touch-LCD-1.28 |
|
240×240 round, GC9A01A SPI ( |
|
|
|
GC9A01 round display on QT Py ESP32-S3 |
|
||||
GC9A01 on QT Py RP2040 |
|
||||
Seeed Round Display for XIAO (GC9A01, CHSC6X touch, microSD, PCF8563 clock) on a XIAO nRF52840, stock MicroPython |
|
yes |
|||
SSD1331 color OLED (MP) |
|
yes |
|||
SSD1351 color OLED (MP) |
|
yes |
|||
LILYGO T-Display-S3 Pro |
|
|
|
||
LILYGO T-Dongle-S3 |
|
— |
|
||
LILYGO T-Embed |
|
170×320, ST7789 SPI ( |
|
|
|
LILYGO T-QT Pro |
|
— |
|
||
LILYGO T-Watch S3 |
|
yes |
240×240, ST7789 SPI ( |
|
|
Wokwi ESP32-S3 + ILI9341 |
|
||||
Wokwi ESP32-S3 + ILI9341 + touch |
|
Parallel (I80) displays
Board |
Config |
CP |
Display and touch |
Eager UI |
Lazy |
|---|---|---|---|---|---|
BPI-Centi-S3 |
|
|
|
||
RP2040 + ILI9341 I80 |
|
||||
LILYGO T-Display-S3 |
|
yes |
— |
|
|
LILYGO T-HMI |
|
yes |
240×320, ST7789 I80 ( |
|
|
Teensy 4.1 + FlexIO ILI9341 (split layout; no onboard lazy extras) |
|
— |
(empty) |
||
WT32-SC01 Plus |
|
yes |
|
|
I2C OLEDs
Board |
Config |
CP |
Display and touch |
Eager UI |
Lazy |
|---|---|---|---|---|---|
SH1106 OLED 128×64 on the STEMMA QT port of a QT Py ESP32 Pico with an Audio BFF (MP + |
|
||||
SH1107 OLED 128×64 (MP + |
|
yes |
|||
FeatherWing OLED 128×32 (MP + |
|
yes |
Framebuffer, RGB, DSI and HDMI displays
Board |
Config |
CP |
Display and touch |
Eager UI |
Lazy |
|---|---|---|---|---|---|
Adafruit Feather RP2040 DVI (MP stub raises |
|
— |
— |
||
Metro RP2350 + Adafruit HSTX→DVI adapter |
|
||||
Arduino GIGA R1 WiFi + GIGA Display Shield |
|
480×800 (800×480 in LVGL), ST7701S MIPI DSI ( |
|
|
|
Waveshare ESP32-P4-WIFI6-DEV-KIT + KeDei 5” DSI |
|
800×480, ICN6211 bridge, MIPI DSI ( |
|
|
|
Waveshare ESP32-P4-WIFI6-Touch-LCD-4B |
|
720×720, ST7703 MIPI DSI ( |
|
|
|
Waveshare ESP32-S3-Touch-LCD-4.3 |
|
yes |
800×480, ST7262 RGB DotClock; touch GT911 @ |
|
|
Waveshare ESP32-S3-Touch-LCD-7 |
|
yes |
800×480, ST7262 RGB DotClock; touch GT911 @ |
|
|
Adafruit Feather RP2040 + RGB matrix wing (matrix is |
|
— |
|
||
M5Stack Tab5 (ILI9881C) (ES8388/ES7210 wired; camera stub) |
|
|
|
||
M5Stack Tab5 (ST7123) (same) |
|
|
|
||
Adafruit MatrixPortal M4 (HUB75 is |
|
yes |
— |
|
|
Adafruit MatrixPortal S3 |
|
yes |
— |
|
|
Olimex RP2350pc (onboard HDMI (HSTX); no adapter) |
|
— |
|
||
Pico 2 + DVI Sock / PiCowbell HSTX (Sock and PiCowbell share GP12–19) |
|
— |
(empty) |
||
Pico 2 W + DVI Sock / PiCowbell HSTX (same HSTX pins + CYW43) |
|
— |
|
||
Adafruit Qualia S3 + TL040HDS20 |
|
yes |
720×720, RGB-666→565 DotClock; touch FT6x36 @ |
|
|
Teensy 4.1 + RGB matrix featherwing |
|
— |
(empty) |
||
SparkFun IoT RedBoard RP2350 + HSTX→DVI (needs FPC + SparkFun HSTX→DVI breakout) |
|
— |
|
||
LILYGO T-RGB 2.1″ |
|
480×480, ST7701 RGB DotClock; touch CST820 ( |
|
|
Pixel and LED grids
Board |
Config |
CP |
Display and touch |
Eager UI |
Lazy |
|---|---|---|---|---|---|
DotStar 12×6 grid (MicroPython) |
|
yes |
|||
NeoPixel 8×4 grid (MicroPython) |
|
yes |
CircuitPython-only configs
Board |
Config |
|---|---|
CircuitPython USB Video |
|
Headless boards
A board with no display has no board_config.py, because there’s nothing to
construct up front; an app imports board_peripherals directly, and an app
that also runs with a display treats board_config as optional.
Directory |
Board |
|---|---|
|
QT Py ESP32 Pico + Adafruit Audio BFF (MicroPython; |
|
the same, on CircuitPython ( |
Desktop and browser
Directory |
Platform |
|---|---|
|
CPython / MicroPython Unix — SDL2 ( |
|
Linux KMS/DRM (no X11/Wayland) — |
|
CPython — PyGame ( |
|
Windows CPython — native Win32 ( |
|
Jupyter Notebook |
|
PyScript browser |
Notes on particular boards
What to know before you flash and wire one of these. The
Arduino GIGA R1 WiFi with the Display Shield
has its own page. Native display drivers come with
omnipython-builds’
displayif module.
The ESP32-S3 RGB boards (Qualia S3, the Waveshare 4.3 and 7 inch, T-RGB)
run on ESP32_GENERIC_S3 with SPIRAM_OCT: eight megabytes of octal PSRAM.
The two Waveshare boards have two USB ports: flash and use the REPL on the
UART port (CH343), because the native port may not show a serial port until the
firmware is up. The 4.3 inch panel runs at a 14 MHz pixel clock, because Wi-Fi
falls over beside the panel at 16. The 4.3 inch board’s touch needs its axes
reflected over the diagonal, which its config already does; the 7 inch
board’s doesn’t. For CircuitPython, use firmware built from the board’s own
definition (waveshare_esp32s3_touch_lcd_43 or _7): it wakes the panel
at boot and hands it over as board.DISPLAY.
Qualia S3 with the TL040HDS20 needs BGR 5/6/5 data-pin order and the
PCA9554 expander at 0x3f. On MicroPython the panel uses two framebuffers and
auto_refresh=False, because LVGL paints the panel directly; the CircuitPython
config paints a separate bitmap, so auto_refresh=True is right there.
T-RGB 2.1 inch uses its native USB: hold BOOT and press RESET to reach the ROM bootloader, then press RESET again after flashing for a clean serial port.
T-Embed is the same: BOOT plus RESET to flash ESP32_GENERIC_S3 with
SPIRAM_OCT, then RESET. The config passes explicit SPI pins on purpose,
because SPI(2)’s defaults land on the octal PSRAM pads. Don’t leave a Python
/lib/spibus.py on the board: it shadows the firmware’s native spibus.
T-HMI drives its panel over an 8-bit parallel bus with the native i80bus;
don’t install a Python bus fallback. Its resistive touch wants firm presses.
A thin noisy line left after a geometry test is usually stale display memory:
display_drv.fill(0) clears it.
Waveshare RP2040-Touch-LCD-1.28 enters the ROM UF2 bootloader (RPI-RP2);
the Adafruit TinyUF2 doesn’t ship for RP2040. The SPI runs at 10 MHz (60 MHz
was unreliable on a cold boot) and the backlight is a plain GPIO, because PWM
doesn’t survive a soft reset and looks like a blank panel. LVGL is too heavy
for this board’s RAM: use the Simon example, or the standalone CircuitPython
one. After heavy SPI use, recover with a cold boot rather than a soft reset.
On CircuitPython the official board build exposes LCD_* and IMU_* aliases
and no board.SPI() or board.I2C().
Metro M7 with the 2.8 inch TFT Touch Shield (1947) has one toggle in its
config, USE_SOFTSPI. The default is software SPI, which needs the shield’s
11/SO/SI pads soldered and its ICSP pads cut, at 2 MHz, because the Metro can’t
move hardware SPI onto D11 to D13. Set it to False for the opposite wiring
(ICSP soldered, 11/SO/SI cut) at 24 MHz, which shares the bus with the
AirLift. The board’s boot drive is METROM7BOOT. A custom MicroPython build
is needed; moving the filesystem offset wipes /flash, so redeploy the config
and secrets afterwards. Free memory is small (about 64 KiB of OCRAM), so
appdev, LVGL and a full set of .py files don’t fit: use the Simon example’s
slim path. On MicroPython the AirLift joins Wi-Fi and resolves names, but TCP
sockets fail with nina-fw 1.7.4; CircuitPython 10.2.1 gets HTTP and HTTPS
through adafruit_esp32spi, but its displaydev runs out of memory, so
prefer MicroPython for the display and CircuitPython for networking.
NUCLEO-H743ZI2 with the same shield uses hardware SPI (USE_SOFTSPI = False, 24 MHz): machine.SPI(1) is already on D13/D11/D12, so the shield’s
11/SO/SI jumpers work as they are. Stock MicroPython maps D13 to PA7, the
Ethernet pin; the firmware remaps it to PA5, and Pin("A5") is the analog pin,
not SPI SCK. Firmware is a custom NUCLEO_H743ZI2 build with displayif,
graphics and lvgl, flashed through the ST-Link drive. About 450 KiB of
heap is free at idle, and Simon and LVGL fit.
ESP32-P4-WIFI6-Touch-LCD-4B has no Ethernet PHY (Ethernet is a different
SKU), and its camera role is a CSI stub. M5Stack CoreS3 and Tab5 wire the
audio codecs and IMU, with camera stubs. Metro M7 and Nucleo rows are the
host board plus the shield, which carries the display and touch. Generic OLED
breakouts and EyeSPI stacks aren’t listed unless they expose roles beyond the
display.
Default config
board_configs/desktop/ — universal non-MCU
board_config for desktop, PyScript, and Jupyter. Host display selection is
displaydev.auto.AutoDisplay (PS / JN / Win→PG→SDL on Windows); the config
exports hardware only:
display_drv = AutoDisplay(...)
host_read = display_drv.get_events
An application opting into appdev then creates its own traffic controller:
import board_config
import appdev
app = appdev.App(board_config)
LVGL instead creates an independent coordinator in display_driver.
Panel size overrides (before import board_config): OMNIPYTHON_WIDTH,
OMNIPYTHON_HEIGHT, OMNIPYTHON_ROTATION, OMNIPYTHON_SCALE, and
OMNIPYTHON_MAXIMIZED=1 to open maximised with the panel the window’s whole
client area at scale 1 (WinDisplay, on Windows; see
Displays). Apps should read geometry from
display_drv, not module-level names on board_config.
Set the env vars before import board_config (or any import that loads
it). On a host with no environment, boarddev.env_set("OMNIPYTHON_WIDTH", 800)
does the same from Python. A script that wants a default size but should respect the user’s own
environment sets it only when nothing else has:
import boarddev
if boarddev.env_get("OMNIPYTHON_WIDTH") is None:
boarddev.env_set("OMNIPYTHON_WIDTH", 800)
import board_config
A value set with env_set wins over os.environ, so without the check it
would override the user. Parsing lives in
boarddev.env_int
and friends (env_get, env_float, env_bool, env_set).
Per-board configs under board_configs/ describe hardware; they never
construct an app.
Custom config
Copy the closest match, edit pin assignments and driver imports, and test with
import pydevices_demo. See the
pydevices_demo.py
for a walkthrough of the recommended smoke test.