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

display_drv

yes

Display backend

host_read, touch_read, …

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

touch + touch_read

Eager raw driver plus neutral read callable

Keypad

keypad + keypad_read

All board buttons (not encoder click)

Encoder

encoder + encoder_read

Includes optional encoder_button_read

Joystick

joystick + joystick_driver

Separate from keypad

Addressable LEDs

pixels

NeoPixel / DotStar / APA102

Discrete LED

led

Primary user LED only

BOOT button

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 keypad. An app that wants it as a key wraps it in its own layer (for example keypad_gpio.GPIOButtons)

Motion

accelerometer, gyroscope, magnetometer

Separate; omit missing axes

Environment

temperature, humidity, pressure

Same driver may bind to several names

Audio

audio_out, pcm_out, pcm_in

One name, one return type — see below. MicroPython has no audio_in.

Audio (CircuitPython)

audio_out, audio_in

CircuitPython’s native player and recorder — see Audio on CircuitPython

Audio power

audio_power

audio_power(enable=True, *, volume=None): codec and amplifier up or down without opening a stream

Microphone power

audio_in_power

audio_in_power(enable=True, *, rate=None, gain=None): the microphone’s ADC up or down without opening a stream, for a recorder that drives I2S itself (audioi2sin.I2SIn); a factory role, listed in FACTORY_ROLES; omit when the microphone needs no setup

Real-time clock

rtc

A battery-backed clock chip with datetime() to read and datetime(t) to set, in machine.RTC’s 8-tuple; omit when the board has only the microcontroller’s own RTC

Haptics

haptic

A vibration motor driver: play(effect, …) plays effects from the chip’s library, stop() ends them; omit when absent

Infrared

ir

An IR LED with its carrier set: an esp32.RMT with tx_carrier on MicroPython, a pulseio.PulseOut on CircuitPython; send marks and spaces in microseconds (ir_nec.send(ir, address, command) for NEC remote codes); omit when absent

Storage

sdcard

Driver object only; no auto-mount

Camera

camera

Expansion I2C

i2c

Dedicated STEMMA/Qwiic/Grove only (not internal-only)

Power

battery

Field / PHY

can, rs485, ethernet

Dedicated board hardware

Wi‑Fi

wlan

Station/AP handle; leave high-level wifi for utils / CP

Bluetooth LE

ble

Omit when absent

Bluetooth Classic

bt

BR/EDR; omit when absent

RF co-processor

radio

AirLift/C6/etc.; may coexist with wlan/ble

LoRa transceiver

lora

A LoRa radio chip (SX1262, …) driven by the board’s own SPI: configure(freq_mhz, …), send(data), receive(timeout_ms), channel_active(); omit when absent

Sleep

sleep

sleep(ms=None, *, deep=False, wake=(…)): light or deep sleep until the time passes or a named wake source fires (the board lists them in WAKE_SOURCES); light sleep returns the source’s name. A factory role: list it in FACTORY_ROLES

Runtime USB device

usb_device

Non-tooling machine.USBDevice; omit tooling CDC bridge

USB MIDI device

usb_midi

(midi_in, midi_out) from midiports.usb_device.ports(): the board’s USB port as a MIDI device a computer plays, keeping the REPL’s serial port. List it only where an app may re-enumerate that port as MIDI on its own (Synth Station does)

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 in board_config with conventional neutral aliases. Applications hand those aliases to their chosen coordinator.

  • Lazy roles: PERIPHERALS lists only names constructed by board_peripherals. Apps check "name" in board_config.PERIPHERALS before access so probing does not allocate. (hasattr on 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 PERIPHERALS and FACTORY_ROLES, so an app that checks "audio_out" in board_config.PERIPHERALS finds it, and board_config.audio_out is the role itself, not one call of it;

  • board_config gets the same change if it’s already imported;

  • for an audio role, the capability follows the role. AUDIO_OUT becomes the new role’s capability, or None when it has none, once neither audio_out nor pcm_out is the board’s own; AUDIO_IN does the same for pcm_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 (display_drv, touch, keypad, encoder, joystick)

board_config

Only non-UI lazy devices (e.g. SPI for sdcard + radio)

board_peripherals (optional)

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

i2c

Primary shared SPI

spi

Extra SPI buses

role-qualified: touch_spi, sd_spi, …

Display protocol bus

display_bus (SPIBus / I80Bus / FourWire / MIPI Bus / …)

Primary IO expander

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.

  1. 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.

  2. Adapters: appdev.Touch rotates all points, emits primary-finger MOUSE*, exposes touch_dev.points. LVGL display_driver feeds gesture recognizers when those APIs exist. Non-LVGL apps keep using primary MOUSE*.

  3. Board wrappers: do not collapse multi-touch to points[0] in board_config. Keep only sequence-preserving maps (e.g. diagonal rescale).

  4. 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 (NotImplementedError)

CP eager UI parity (touch / keypad / encoder / joystick)

CP non-UI stays on board

Sequence-preserving touch_read

See also Board configs, which lists every board with its roles.

See also