ESP32-P4 reference target

The Waveshare ESP32-P4-WIFI6-Touch-LCD-5 is the first fully supported hardware target and the current reference implementation. It is where PocketPi must prove standalone boot, local state, touch/display, Wi-Fi, provider transport and App lifecycle under real constraints.

Exact board composition

These are the board and firmware parameters used by the current host, not a generic list of everything the ESP32-P4 chip can support. The App-facing logical viewport is 720×1280. Compare the Waveshare board specification and the Espressif ESP32-P4 datasheet with the checked-in host configuration.

Toolchain

• Rust with rustup;
• the esp-rs/ESP-IDF development environment;
• Rust nightly-2026-05-01 used by the repository wrapper;
• espflash for port discovery, flashing and boot diagnostics;
• a PocketJS checkout only when regenerating the shared View SDK.

The refactored Python UART tools use POSIX serial APIs. macOS is the documented host path; they are not currently a native Windows workflow.

Find the board serial port

espflash list-ports
export DEVICE_PORT=/dev/cu.usbmodem...
espflash board-info --port "$DEVICE_PORT"

Choose the WCH USB serial device reported by espflash. Keep the variable in the same shell for the flash, provisioning, bridge and install commands below.

Build the release firmware

cargo xtask build esp32-p4

This builds the ESP32-P4 release firmware with the generated Pi Agent bundle and View SDK resources committed to the repository. It does not regenerate either asset. Ordinary Apps are not embedded in the firmware image.

Flash without erasing persistent configuration

espflash flash --baud 921600 --port "$DEVICE_PORT" \
  --partition-table firmware/esp32-p4/partitions.csv \
  firmware/esp32-p4/target/riscv32imafc-esp-espidf/release/pocket-pi-p4

A normal flash preserves NVS and existing LittleFS state. Do not erase the board unless a test explicitly requires destructive reprovisioning.

Provision standalone model and Wi-Fi configuration

python3 tools/uart-provision.py "$DEVICE_PORT" \
  --provider deepseek --provision-wifi

For DeepSeek, the tool reads account deepseek-api-key from the macOS Keychain service Pocket Pi Credentials when available; otherwise it prompts without echo. Other providers prompt for their key. Model provider, model, thinking level and API key are stored in native NVS. Wi-Fi uses the device's Wi-Fi NVS store. Normal boots load both stores without a Mac or UART bridge.

python3 tools/uart-provision.py "$DEVICE_PORT" \
  --provider openai --model gpt-5-mini

Development-only model bridge

python3 tools/uart-model-bridge.py "$DEVICE_PORT" \
  --provider codex \
  --prompt "Use write, read, schedule.set and schedule.list."

Use this only for bring-up on an unprovisioned development board. It does not become the device's stored standalone backend and is not part of normal startup.

Install an ordinary App

cargo xtask package app exa path/to/exa-credentials.json

python3 tools/uart-install.py "$DEVICE_PORT" \
  target/pocketapps/exa.pocketapp

Wait for the review screen and confirm on the touch display. The same package can be uploaded through http://<device-ip>/ when local peer access is available.

Serial monitor warning

On the board's WCH USB bridge, espflash monitor controls DTR/RTS. Opening it between App upload and physical confirmation can reset the board and discard the pending review. Use it for boot diagnostics, then restore a normal boot:

espflash monitor --port "$DEVICE_PORT"
espflash reset --port "$DEVICE_PORT" --non-interactive

Physical acceptance checklist

1. Cold boot reaches the resident Agent Root View.
2. LCD, touch and keyboard input work at the 720×1280 logical viewport.
3. Saved Wi-Fi associates and receives DHCP without a Mac bridge.
4. A fresh provider prompt returns through the configured standalone backend.
5. Workspace write/read and Agent wake persistence survive restart.
6. An App installs after touch review, exposes its Tool, writes SQLite and renders its View.
7. An update preserves data/credentials; uninstall removes all App-owned state.

Board-specific source and caveats: docs/esp32-p4-port.md ↗.