只想安装官方系统？
使用 网页烧录，按设备型号安装 GitHub 最新稳定固件，无需 ESP-IDF。数据保留方式见 烧录教程。下面的源码构建适合修改系统或驱动的开发者。
获取固件工作区
只开发 App 请继续使用 DevKit；修改系统、板级驱动或构建固件才需要此工作区。
git clone --branch v0.10.0 --recurse-submodules https://github.com/SmartArduino/pxa-workspace.git
cd pxa-workspace
本章所有 tools/ 命令均从此目录执行。先按对应板级 README 安装并激活 ESP-IDF；ESP32-S31 需要支持该芯片的 IDF main 工具链，不能沿用只支持 S3 的旧环境。用 idf.py --version 核对环境。
选择已有板级实现
工作区中已有 pai-touch、sensecap-watcher、esp32s31-korvo-1、esp-mosaico、doit-gamekit、doit-gamekit-1、doit-esp32s31-devkit 和 espp4-a 目录。这表示存在板级接入代码，不等于所有硬件能力已经完成相同程度的验证。以对应 README、原理图和实际硬件修订为准。
board.cmake 在 IDF 发现组件前选择芯片和板级 component；每块板子有独立 sdkconfig.defaults、分区与依赖 manifest。
编译、烧录与监视
先激活适合目标板的 ESP-IDF：
tools/firmware.sh pai-touch build
tools/firmware.sh pai-touch app-flash --port /dev/ttyACM0 --baud 2000000
tools/firmware.sh pai-touch monitor --port /dev/ttyACM0 --baud 115200
上面的 app-flash 用于分区和引导程序已经匹配的日常升级，只写应用分区。全新设备首次初始化使用 flash；改变分区表或首次挂载自动格式化可能影响原数据，请先核对板级配置。
工具使用 build/firmware/pai-touch/，其他板子只替换第一个参数。等效的直接构建入口是：
idf.py -C firmware -B build/firmware/pai-touch -DPXA_BOARD=pai-touch build
切换板子使用独立构建目录，避免残留芯片与驱动配置。首次解析生成 firmware/dependencies.lock.<board>，由组件管理器维护，不手工修改。
配置和数据分区
tools/firmware.sh pai-touch menuconfig
PXA 数据分区使用 data/littlefs；分区标签必须与 CONFIG_PXA_STORAGE_PARTITION_LABEL 完全一致，挂载点使用绝对路径。普通固件编译与烧录不负责构建或覆盖应用数据分区。
需要工厂预置时另用 tools/factory.sh image pai-touch 生成镜像。该镜像会替换整个 PXA 数据分区，不适用于需要保留用户 App 的日常升级。首次挂载失败是否格式化由 CONFIG_PXA_STORAGE_FORMAT_IF_MOUNT_FAILED 决定。
安装一个验证应用
关闭 monitor 后执行：
mkdir -p local/my-apps
pxa init local/my-apps/board-hello --id pxa-board-hello
pxa device info --port /dev/ttyACM0 --baud 2000000
pxa run local/my-apps/board-hello --device /dev/ttyACM0 --baud 2000000
这个 C++ Hello 使用 Core 2；不要从旧 apps/pxa/hello 的 C 示例复制包。pxa run 会读取设备目标。手动打包时，ESP32-S31 使用 --target esp32s31；其他板子若工具未定义默认 App target，就显式给出其真实芯片支持的 target。
验收结果
确认上电启动、显示方向、触控坐标、包安装、App 启停和重启后的持久状态。再逐项验证网络、音频、亮度和电源；失败时沿板子调试的顺序定位。
下载完整固件
八块板子的官方固件 0.10.0 内嵌 PXA 0.10.0，提供合并镜像、分区文件、应用分区镜像、刷写说明和 SHA-256。选择与板名完全一致的文件；Watcher 使用 32 MiB flash，DOIT ESP32-S31 DevKit 使用 8 MiB，其余六块使用 16 MiB。DOIT GameKit 没有触控，使用手柄。
合并固件包含字体与商城，用于首次安装，会覆盖应用和数据分区。保留原数据的升级只写 app 文件，并先核对现有分区表相同。ESP32-S31 手动进入 ROM 下载模式后使用 --before no-reset，串口出现并不能单独证明 ROM 已就绪；完整命令见对应 ZIP 的中文说明。
完整镜像预装商城 0.9.6；保留数据升级会保留原商城。升级后，旧商城可按 PXA Host 的实际能力查询并安装兼容的新版商城，操作见保留数据后更新商城。板级固件由 firmware/VERSION 编号，内嵌 PXA 由 deps/pxa-system/VERSION 编号；自定义整机发行号不会改变应用兼容性。
发行维护者可设置 PXA_FIRMWARE_BUILD_ROOT，使用独立构建树和新 sdkconfig，避免把本地实验配置带入发行包。tools/build_firmware_release.py 从构建产物读取 flash 参数和分区，检查越界/重叠，使用本轮发布的原始商城包生成文件系统，再合并镜像。
标准服务与板级扩展
文件和 SD 使用标准 Storage/FS，麦克风使用 Audio，已定义的物理量使用 Sensor， 振动使用 Haptics。没有对应硬件的板型应返回不可用，不用伪造数据填补。
标准尚未覆盖的接口复用仓库 extensions/ 的 pxa-ext SDK。
org.doit.peripherals 0.3 通过 UUID/版本协商发现逻辑端口，并按每个 scope
授权：Watcher 提供 indicator.rgb、grove.i2c、camera.jpeg 和
vision.inference，Korvo 提供 RGB 和 JPEG，GameKit 1 提供状态灯。
这是非标准扩展，不应将私有服务编号标成 PXA 标准能力。
DevKit 的 extensions/peripherals/README.md 包含协议、SDK CMake 接入与
examples/camera、examples/indicator；标准录音示例位于
sdk/guest-cpp/examples/capture。应用必须处理授权拒绝、设备忙、无摄像头或
无模型，后台与撤权时释放资源。视觉示例仅保存本地文件，不上传图像或刷写模型。
Watcher 与 Korvo 的 SD 按启动状态挂载；无卡继续启动，不自动格式化。插拔请
先关机。Watcher 的 SD 和 Himax 共用 SPI2，不能由应用重新初始化或释放总线。
Korvo 本版数据区从 0x700000 开始，旧 4 MiB 应用布局不能直接刷新版 app；
先导出私有数据、存档与设置，再完整迁移并按原签名身份恢复。
新增板级功能仍优先查询标准；标准缺项才定义自有扩展，并保留身份、版本、权限、 资源上限、取消与清理规则。未来标准覆盖时优先迁移，必要时在标准仓库提交 issue 并附公开的扩展合同，不静默改变已有编号的含义。