---
name: pxa-board-port
description: Adapt a new ESP32-S3/S31 board to the existing PXA board port, with hardware inventory, board-local scaffolding, boundary checks and staged device acceptance. Use for a new BSP or board bring-up, not app development or SDK/ABI changes.
---

# PXA board adaptation

Use a firmware workspace, separate from the app DevKit workspace. Run Agent Kit
`--workspace <firmware-root> board setup` to install the local tools and rules.
This does not install ESP-IDF. Read the workspace's build instructions for its
selected SDK/toolchain; do not reuse an app container as a firmware toolchain.

Read `firmware/components/pxa_board_api/include/pxa_board_api.h` and
`docs/zh-CN/adding-a-board.md` from that exact checkout. Adapt hardware to the
existing interface. Do not edit PXA ABI/spec, C/C++ SDK, runtime, shared board
components or another board. The allowed writes are
`firmware/boards/<id>/`, `simulator/profiles/<id>.toml` and
`firmware/dependencies.lock.<id>` generated by the dependency resolver.
Do not hand-edit dependency locks.

For a new board, `board init <id> --target esp32s3|esp32s31 --reference <id>`
creates the directory and starts its change scope. It deliberately contains a
compile-time bring-up gate, empty partitions and no guessed GPIO. For an
existing port, begin `scope begin --mode board --board <id>` before editing.
Reference drivers are for reading; copying their GPIO/power defaults is not
hardware verification. A new CPU backend or missing platform API is separate
platform work, not a reason to change SDK contracts in a BSP task.

Fill `board-port.json` from the schematic/datasheets: chip/Flash/PSRAM, panel
controller/bus/size/rotation/RGB565 order, pin map, input, power and storage.
Ask only for hardware facts that cannot be found in supplied materials. Record
unknowns explicitly. Do not energize an unknown rail or guess a backlight GPIO.

Implement the required callbacks with persistent port/context lifetime. Keep
pixel/DMA/PCM hot paths and buffer ownership in the board implementation.
Remove the gate only after real drivers and verified partitions exist.
Run `board check <id>`, then `board build <id>`. Static readiness does not
prove that drivers work. Missing ESP-IDF or a failing build is a real blocker;
do not suppress the failure or expand the edit boundary to make it pass.

For user-authorized device tests, identify the actual port/chip first and
preserve installed apps/saves. Validate boot/reset, solid colors and borders,
rotation, display completion FPS, input/release, app start/stop, memory and
storage recovery; then add optional audio/network. Cancel injected input.
Keep physical measurements separate from simulator results. Do not register
an untested board as officially supported or add it to stable firmware releases.

Finish with `scope check`, build evidence, measured hardware results and
remaining unknowns. Scope checking is a change audit, not a sandbox; preserve
and report violations rather than resetting files or replacing the baseline.