← pydevices docs

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

CircuitPython (board_configs/cp/) does not use board_peripherals.py or lazy PERIPHERALS. CP already exposes pins/buses via the native board module. CP board_config.py only constructs display_drv and eager UI hardware (touch, keypad, encoder, joystick) with neutral read aliases. Do not from board_config import … inside CP configs.

Specials (always these names)

Optional end-device roles

Omit the name entirely when the hardware is absent. Canonical symbols:

audio_out returns PCMOutput for sample playback or ToneOutput for PWM/buzzer hardware. audio_in returns PCMInput. PCM devices expose their 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. 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.

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 under drivers/ (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

Lazy factories import UI-shared buses from board_config when needed (e.g. IMU on the same I2C as touch).

Infrastructure names (for later sharing)

Rename consistently even before lazy devices exist:

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: eventsys.TouchDevice 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 Runtime — touch read contract and Touch drivers.

App usage

import board_config as board
from board_config import display_drv
import eventsys

runtime = eventsys.Runtime.from_board_config(board)

display_drv.fill(0)

# Eager UI — discover/use through runtime
if runtime is not None and runtime.touch_dev is not None:
    runtime.touch_dev.subscribe(...)

# Lazy extras — PERIPHERALS only (do not hasattr these)
if "sdcard" in board.PERIPHERALS:
    card = board.sdcard  # constructs now
if "wlan" in board.PERIPHERALS:
    wlan = board.wlan
    wlan.active(True)

Rollout

Board configs and drivers live in PyDevices/pydevices. MicroPython campaign + product boards use the split layout (board_config.py + board_peripherals.py). CircuitPython twins under cp/ stay single-file (eager UI only).

See also device-matrix.md and the other notes in this docs/ directory.

See also

• Board configs — how to pick and install a config
• Runtime — display_drv / runtime / touch read
• Architecture — how pieces fit together