Board peripherals contract
Normative end-device surface for board_config — CircuitPython-like discovery,
stable role names, and a clear split between eager UI devices and lazy extras.
This is the target contract for MicroPython boards. Board configs and
drivers live in
omnipython.
CircuitPython (board_configs/cp/) uses the same role names but leans on
its native board module. A CP board_config.py constructs display_drv and
the eager UI hardware (touch, keypad, encoder, joystick) with neutral
read aliases. A CP board_peripherals.py is optional: add one for roles that
need setup board doesn’t do (a codec or amplifier to configure, a power
chip to enable, a pin the config must own) and leave out anything board
already hands over ready to use. Do not from board_config import … inside CP
configs.
Specials (always these names)
Symbol |
Required |
Notes |
|---|---|---|
|
yes |
Display backend |
|
when present |
Neutral callables consumed by the app’s chosen coordinator |
Optional end-device roles
Omit the name entirely when the hardware is absent. Canonical symbols:
Role |
Symbol |
Wiring |
|---|---|---|
Touch |
|
Eager raw driver plus neutral read callable |
Keypad |
|
All board buttons (not encoder click) |
Encoder |
|
Includes optional |
Joystick |
|
Separate from keypad |
Addressable LEDs |
|
NeoPixel / DotStar / APA102 |
Discrete LED |
|
Primary user LED only |
BOOT button |
|
The BOOT/IO0 button as a raw input, where the board leaves it free for apps. Always this name: a config never also puts it in |
Motion |
|
Separate; omit missing axes |
Environment |
|
Same driver may bind to several names |
Audio |
|
One name, one return type — see below. MicroPython has no |
Audio (CircuitPython) |
|
CircuitPython’s native player and recorder — see Audio on CircuitPython |
Audio power |
|
|
Microphone power |
|
|
Real-time clock |
|
A battery-backed clock chip with |
Haptics |
|
A vibration motor driver: |
Infrared |
|
An IR LED with its carrier set: an |
Storage |
|
Driver object only; no auto-mount |
Camera |
|
|
Expansion I2C |
|
Dedicated STEMMA/Qwiic/Grove only (not internal-only) |
Power |
|
|
Field / PHY |
|
Dedicated board hardware |
Wi‑Fi |
|
Station/AP handle; leave high-level |
Bluetooth LE |
|
Omit when absent |
Bluetooth Classic |
|
BR/EDR; omit when absent |
RF co-processor |
|
AirLift/C6/etc.; may coexist with |
LoRa transceiver |
|
A LoRa radio chip (SX1262, …) driven by the board’s own SPI: |
Sleep |
|
|
Runtime USB device |
|
Non-tooling |
USB MIDI device |
|
|
The three audio roles
pcm_out(format=None, …) returns a PCMOutput; pcm_in(format=None, …)
returns a PCMInput; audio_out(format=None, …) returns an
audiodev.sample_out.AudioOut sample player. Each role always returns the
same kind of object, on every board and on every host.
There is deliberately no audio_in: output has a player layer above raw
PCM and capture has none, so a name implying one would be misleading. That
asymmetry is intentional, not an oversight.
pcm_out exists so a consumer that already has PCM bytes — a Spotify
Connect speaker, a USB sound card — never constructs an AudioOut and so
never needs audiodsp in firmware.
Boards with PWM/buzzer-only hardware expose a ToneOutput and declare
kind="tone"; they take no format.
Audio on CircuitPython
CircuitPython has its own audio stack, so on CircuitPython the audio roles
return its native objects, the same split as displayio for displays.
audio_out() returns a player such as audiobusio.I2SOut or
audiopwmio.PWMAudioOut, whose play(sample) takes any audiosample.
audio_in() returns CircuitPython’s native recorder (audiobusio.PDMIn, or
the audioi2sin.I2SIn that CircuitPython-compatible builds add), whose
record(buffer, n) fills a buffer. The name follows CircuitPython’s own
audio* modules; there’s no player layer on capture here either, and there
are no pcm_out/pcm_in roles on CircuitPython. A role that sets up a codec
calls audio_power(True) first, so an app can also bring the codec up on its
own.
Declaring what the board accepts
Audio roles are factories: list them in FACTORY_ROLES so first
attribute access binds the callable instead of constructing. Each publishes
an AudioCapability as a module constant (AUDIO_OUT / AUDIO_IN) and as
role.capability:
FACTORY_ROLES = frozenset({"audio_out", "pcm_out", "pcm_in"})
AUDIO_OUT = AudioCapability(
AudioFormat(24000, 1, 16), # default when format=None
rates=None, # None = continuous; or a tuple of exact rates
channels=(1, 2), # slot counts the WIRE will open
native_channels=1, # signals that reach a transducer
bits=(16,),
wire=I2SWire(0, sck=12, ws=10, sd=9, mck=13),
)
A board declares facts and calls audiodev.negotiate(); it does not write
its own validation. Declare only what has been measured on the hardware —
a capability is a promise the contract makes on the board’s behalf.
channels is not native_channels. The ESP32-P4’s ES8311 clocks two slots
into one speaker, so stereo content opens I2S.STEREO and is not mixed down.
wire is for a consumer that opens the peripheral itself and wants no Python
device — usbif’s C pump is the live example. Publishing it is what lets such
a consumer stop reaching into private names.
Every device exposes its format, capabilities, normalized volume/gain and
mute controls, synchronous I/O, and portable asynchronous I/O. When a codec
provides hardware controls, the device delegates to them and exposes the
codec as device.codec; otherwise volume or gain is applied to PCM samples
in software. On CircuitPython the audio roles return native objects instead;
see Audio on CircuitPython.
See Portable audio for backend, async, and board details.
Out of contract as board_config symbols: high-level wifi / bluetooth modules
and tooling USB / UART bridges. Apps may still use those stacks directly.
Discovery
Eager UI roles (
touch,keypad,encoder,joystick, …): constructed inboard_configwith conventional neutral aliases. Applications hand those aliases to their chosen coordinator.Lazy roles:
PERIPHERALSlists only names constructed byboard_peripherals. Apps check"name" in board_config.PERIPHERALSbefore access so probing does not allocate. (hasattron a lazy name may construct — do not use it for discovery.)
PERIPHERALS is authored in board_peripherals.PERIPHERALS only. board_config
re-exports that frozenset; eager UI names are not listed there.
Replacing a role at run time
You can put something else in place of any role, for every app, from
main.py. Do it before the app is imported:
import board_peripherals
import boarddev
from usb.host import audio
boarddev.replace_role(board_peripherals, "audio_out", audio.audio_out)
boarddev.replace_role(board_peripherals, "pcm_out", audio.pcm_out)
import my_app
This works because callers look a role up when they use it. An app that calls
board_peripherals.audio_out(), or boarddev.audio_out(), which finds the
same module, gets whatever is there at that moment. So an app must never bind
a role at import time: from board_peripherals import audio_out copies the
board’s own role into the app before main.py can replace it.
A plain assignment, board_peripherals.audio_out = audio.audio_out, is
enough for an app that only calls the role. replace_role also keeps the rest
of the board’s description true:
the name joins
PERIPHERALSandFACTORY_ROLES, so an app that checks"audio_out" in board_config.PERIPHERALSfinds it, andboard_config.audio_outis the role itself, not one call of it;board_configgets the same change if it’s already imported;for an audio role, the capability follows the role.
AUDIO_OUTbecomes the new role’scapability, or None when it has none, once neitheraudio_outnorpcm_outis the board’s own;AUDIO_INdoes the same forpcm_in.
The capability matters on a board with its own codec. Its AUDIO_OUT.wire
names the codec’s I2S pins, and an app that finds a wire drives those pins
itself, past audio_out. Once both output roles are replaced, AUDIO_OUT no
longer names the codec, so that app plays through the replacement too. Replace
audio_out and pcm_out together: the board’s own roles read AUDIO_OUT, so
it keeps describing the codec while either of them is left.
A USB sound card has no capability until it’s plugged in, so its roles carry
none. Ask the opened output’s format what the device took.
Pass what callers should get: a factory for an audio role, the object itself
for a role that is constructed, such as sdcard.
Boards with no display
board_configs/nodisplay/ holds boards that are only peripherals — an audio
DAC or amplifier on a QT Py, say. They ship a board_peripherals.py and no
board_config.py, because there is nothing eager to construct. Apps import
board_peripherals directly, which is the non-graphics idiom with nothing
else in the way.
Every other category is named for a display technology (busdisplay,
fbdisplay, pixeldisplay, …), so nodisplay is where a board with no
display lives.
Module layout (shape to prove)
Keep board_config.py. Sibling board_peripherals.py holds PERIPHERALS, zero-arg
factories, and load_peripherals. End of board_config.py:
from board_peripherals import PERIPHERALS, load_peripherals
load_peripherals(globals())
Shared boilerplate is boarddev,
a lib/ module shipped by the omnipython meta package (the name signals
devices, not board_config). Typical
board_peripherals.load_peripherals is a thin wrapper around boarddev.bind_lazy.
A board may replace load_peripherals and skip boarddev entirely.
There is no separate board_hardware module.
Bus ownership
Bus shared with… |
Lives in |
|---|---|
UI devices ( |
|
Only non-UI lazy devices (e.g. SPI for |
|
Lazy factories import UI-shared buses from board_config when needed
(e.g. IMU on the same I2C as touch).
Hand a driver the bus, not its pins
A peripheral hook gives a driver the bus object board_config already built.
Where a native driver can’t take the object, give it the port that bus is on.
Never give it the SDA/SCL (or SCK/MOSI/MISO) numbers of a bus something else
owns.
A driver handed pins opens its own controller on them. Two I2C masters on one pair of wires don’t raise an error: the new device works and the old one stops answering. On the Waveshare P4 panel the camera did this to the touchscreen, and it was reported as a slowdown somewhere else entirely (omnipython#22).
If a hook must work without board_config (a non-graphics app that must not
start the display), it may open the bus itself, but on the same port
board_config uses, once, and reuse that object after. The Waveshare P4 and
Tab5 board_peripherals.py files show the shape.
Infrastructure names (for later sharing)
Rename consistently even before lazy devices exist:
Kind |
Canonical name |
|---|---|
Primary shared I2C |
|
Primary shared SPI |
|
Extra SPI buses |
role-qualified: |
Display protocol bus |
|
Primary IO expander |
|
Touch duck-type
board_config.touch is the raw driver object; board_config.touch_read is
the neutral callable used by an application coordinator.
touch.read_points()→()when up, else a sequence of(x, y[, id[, …]]). Never a bare(x, y)from this method (ambiguous with a single 2-tuple point). Single-touch chips return()or a one-element sequence.Adapters:
appdev.Touchrotates all points, emits primary-fingerMOUSE*, exposestouch_dev.points. LVGLdisplay_driverfeeds gesture recognizers when those APIs exist. Non-LVGL apps keep using primaryMOUSE*.Board wrappers: do not collapse multi-touch to
points[0]inboard_config. Keep only sequence-preserving maps (e.g. diagonal rescale).Wire with
touch_read=touch.read_points(or a sequence-preserving wrapper).
See App and board config — touch read contract and Touch drivers.
App usage
import board_config as board
from board_config import display_drv
import appdev
app = appdev.App(board)
display_drv.fill(0)
# Eager UI — discover/use through the app
if app is not None and app.touch_dev is not None:
app.touch_dev.subscribe(...)
# Lazy extras — PERIPHERALS only (do not hasattr these)
if "sdcard" in board.PERIPHERALS:
card = board.sdcard # constructs on this access
if "wlan" in board.PERIPHERALS:
wlan = board.wlan
wlan.active(True)
Rollout
Board configs and drivers live in
PyDevices/omnipython.
MicroPython campaign + product boards use the split layout
(board_config.py + board_peripherals.py). CircuitPython twins under cp/ are
single-file (eager UI only), except the few that add an optional
board_peripherals.py.
In OmniPython |
Still to do |
|---|---|
MP split layout for matrix product boards |
Fill remaining lazy factories ( |
CP eager UI parity ( |
CP non-UI stays on |
Sequence-preserving |
See also Board configs, which lists every board with its roles.
See also
Board configs — how to pick and install a config
App and board config —
display_drv/app/ touch readArchitecture — how pieces fit together