junlon2006 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,8 @@ Versioning and Conventional Commits.
 
 ### Added
 
+- Per-board hardware and usage documentation for all thirteen profiles, with a linked board
+  index, current build commands, and profile-specific feature and validation limits.
 - CoreS3-only process-gray pixel-glasses UI, with 23 expressions, four 9 px terminal rows,
   a 10 px signature and fixed 32 px six-digit pairing codes on its 320x240 display.
   Automatic faces follow READY/conversation phases; four MCP emotions use bounded holds,

diff --git a/README.md b/README.md
@@ -39,6 +39,9 @@ Circular-4 with XIAO ESP32S3, and SenseCAP Watcher.
 
 ## Supported Boards
 
+Per-board hardware notes and build instructions are listed in the
+[board documentation index](components/mybot_platform/boards/README.md).
+
 | Board profile | Audio | Display and input | Storage |
 | --- | --- | --- | --- |
 | `zhengchen-1.54tft-ml307` | I2S microphone and speaker | ST7789, Boot and volume buttons | 16 MB QIO Flash, 8 MB Octal PSRAM |

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -35,6 +35,8 @@ StickS3、M5Stack AtomEchoS3R、搭配 XIAO ESP32S3 的 ReSpeaker Flex XVF3800 C
 
 ## 支持的板卡
 
+各板型的硬件说明、构建方法及支持范围见[板卡说明索引](components/mybot_platform/boards/README.md)。
+
 | Board profile | 音频 | 显示与输入 | 存储 |
 | --- | --- | --- | --- |
 | `zhengchen-1.54tft-ml307` | I2S 麦克风和扬声器 | ST7789、Boot 与音量按键 | 16 MB QIO Flash、8 MB Octal PSRAM |

diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
@@ -37,6 +37,7 @@ It does not replace third-party terms. This file is informational and is not leg
 | CoreS3 pixel-glasses renderer, geometry/mask generators | MIT; expression helpers/policy retain their file-level Apache-2.0 notices | `components/mybot_platform/src/drivers/display/renderers/lvgl/pixel_glasses_view.cc`, pixel geometry/masks/generators and private expression support |
 | MyBot Terminal bitmap subsets derived from DejaVu Sans Mono Bold | Bitstream Vera font terms, with public-domain DejaVu changes | `components/mybot_platform/src/drivers/display/renderers/lvgl/pixel_fonts.c`, `TERMINAL_FONT_LICENSE.txt` |
 | Project-maintained shared LVGL panel adapters | Apache-2.0 unless file SPDX says otherwise | `components/mybot_platform/src/drivers/display/adapters/lvgl/st7789_lvgl_adapter.cc`, `components/mybot_platform/src/drivers/display/adapters/lvgl/shared_lvgl_adapter.cc` |
+| Board documentation adapted from xiaozhi-esp32 hardware references | MIT; project-maintained profile descriptions are Apache-2.0 | The board READMEs indexed in `components/mybot_platform/boards/README.md` |
 | M5Stack CoreS3-derived implementation | MIT | Paths listed under MIT Attributions |
 | ReSpeaker Flex XVF3800-derived implementation (`b060243`) | MIT | Paths listed under MIT Attributions |
 | SenseCAP Watcher-derived implementation | MIT | Paths listed under MIT Attributions |
@@ -74,6 +75,17 @@ supply an authorized package locally.
 
 ## MIT Attributions
 
+
+The board READMEs for AtomEchoS3R, ESP-VoCat, the Waveshare AMOLED profiles, CoreS3,
+StickS3, SenseCAP Watcher and the Zhengchen profiles adapt hardware material from the
+MIT-licensed xiaozhi-esp32 project. Their instructions describe this repository's current
+profiles and supported features. The original copyright and full MIT permission notice
+are retained in `components/mybot_platform/assets/LICENSE.xiaozhi-esp32`.
+The Bread Compact Wi-Fi LCD, Xingzhi Cube and ReSpeaker Flex descriptions are
+project-maintained documentation of the checked-in profiles. The board index links
+these documents and their actual configuration files.
+
+
 The adapted platform implementations listed below can be inspected at the published
 [ESP32 implementation baseline][esp32-platform-baseline]. This snapshot preserves the delivered
 code and its file-level notices; the original project and copyright attributions remain below.

diff --git a/VENDORED_SOURCES.md b/VENDORED_SOURCES.md
@@ -41,6 +41,40 @@ also supplies the generated `include/mybot/mybot_version.h`. The official Git tr
 `git archive 32ac74bc59cb72db70e9a68337753561b59b13d0 include src | sha256sum` produces
 `6443be044e8210057b0291e53b8ea6dcb92664f54b78fd9c71ac2f10c34e292e`.
 
+## Board reference documents
+
+Per-board hardware notes and usage instructions are indexed in
+[the board documentation index](components/mybot_platform/boards/README.md).
+These pages describe the checked-in `board.cmake`, `board_config.h` and board defaults,
+using this repository's `MYBOT_BOARD` selector and `scripts/build_all.py` build entry.
+Firmware capabilities and validation limits follow the current profiles and the English
+and Chinese root READMEs.
+
+The AtomEchoS3R, ESP-VoCat, Waveshare AMOLED, CoreS3, StickS3, SenseCAP Watcher and Zhengchen
+pages adapt MIT-licensed xiaozhi-esp32 hardware reference material. The upstream MIT
+notice is retained in `components/mybot_platform/assets/LICENSE.xiaozhi-esp32`.
+Bread Compact Wi-Fi LCD, Xingzhi Cube and ReSpeaker Flex have project-maintained profile
+descriptions. The adapted pages are maintained for this firmware; they are not unchanged
+copies of another application's build or feature documentation.
+
+| Board profile | Delivered description |
+| --- | --- |
+| `atom-echos3r` | [README](components/mybot_platform/boards/atom-echos3r/README.md) |
+| `bread-compact-wifi-lcd` | [README](components/mybot_platform/boards/bread-compact-wifi-lcd/README.md) |
+| `esp-vocat` | [README](components/mybot_platform/boards/esp-vocat/README.md) |
+| `esp32-s3-touch-amoled-1.75` | [README](components/mybot_platform/boards/esp32-s3-touch-amoled-1.75/README.md) |
+| `esp32-s3-touch-amoled-1.75c` | [README](components/mybot_platform/boards/esp32-s3-touch-amoled-1.75c/README.md) |
+| `esp32-s3-touch-amoled-2.16` | [README](components/mybot_platform/boards/esp32-s3-touch-amoled-2.16/README.md) |
+| `m5stack-core-s3` | [README](components/mybot_platform/boards/m5stack-core-s3/README.md) |
+| `m5stack-stick-s3` | [README](components/mybot_platform/boards/m5stack-stick-s3/README.md) |
+| `respeaker-flex-xvf3800-circular4-xiao` | [README](components/mybot_platform/boards/respeaker-flex-xvf3800-circular4-xiao/README.md) |
+| `sensecap-watcher` | [README](components/mybot_platform/boards/sensecap-watcher/README.md) / [English](components/mybot_platform/boards/sensecap-watcher/README_en.md) |
+| `xingzhi-cube-1.54tft-wifi` | [README](components/mybot_platform/boards/xingzhi-cube-1.54tft-wifi/README.md) |
+| `zhengchen-1.54tft-ml307` | [README](components/mybot_platform/boards/zhengchen-1.54tft-ml307/README.md) |
+| `zhengchen-1.54tft-wifi` | [README](components/mybot_platform/boards/zhengchen-1.54tft-wifi/README.md) |
+
+## Platform implementation references
+
 The platform table identifies third-party derivation and hardware references separately from
 the delivered adaptations. [ESP32 implementation baseline][esp32-platform-baseline] refers to
 the listed paths at the published `agora-esp32-devkit` commit

diff --git a/components/mybot_platform/boards/README.md b/components/mybot_platform/boards/README.md
@@ -0,0 +1,37 @@
+# Board documentation / 板卡说明
+
+All 13 supported board profiles have documentation for the hardware configuration and firmware
+features implemented by `agora-esp32-devkit`. See the [English build guide](../../../README.md#build)
+or [中文构建说明](../../../README.zh-CN.md#构建) for environment setup and build options.
+
+各板型说明按本仓库的 `board.cmake`、`board_config.h` 和 `sdkconfig.defaults` 整理。
+`MYBOT_BOARD` 是手动构建时的板型选择入口；自动脚本在工程根目录运行：
+
+```sh
+python3 scripts/build_all.py --board <board-id> --language both
+```
+
+默认生成目录为 `build/build-<板型>-<语言>[-video]/`，合并产物位于 `releases/`。
+CoreS3 默认启用视频并带 `-video` 后缀，其余板型关闭视频。Watcher 必须保留工厂 NVS，
+使用其说明中的分段烧录步骤。脚本的目录清理和归属检查见根构建指南。
+
+| Board profile | 文档 | 当前配置说明 |
+| --- | --- | --- |
+| `atom-echos3r` | [README](atom-echos3r/README.md) | ES8311、GPIO41 按键、无屏 |
+| `bread-compact-wifi-lcd` | [README](bread-compact-wifi-lcd/README.md) | ST7789、独立 I2S、Boot 按键 |
+| `esp-vocat` | [README](esp-vocat/README.md) | ES7210/ES8311、ST77916 与触摸 |
+| `esp32-s3-touch-amoled-1.75` | [README](esp32-s3-touch-amoled-1.75/README.md) | CO5300 AMOLED 与触摸 |
+| `esp32-s3-touch-amoled-1.75c` | [README](esp32-s3-touch-amoled-1.75c/README.md) | 独立 1.75C profile |
+| `esp32-s3-touch-amoled-2.16` | [README](esp32-s3-touch-amoled-2.16/README.md) | 480×480 CO5300 AMOLED |
+| `m5stack-core-s3` | [README](m5stack-core-s3/README.md) | 像素眼镜 UI，默认摄像头视频 |
+| `m5stack-stick-s3` | [README](m5stack-stick-s3/README.md) | ST7789、ES8311 与主按键 |
+| `respeaker-flex-xvf3800-circular4-xiao` | [README](respeaker-flex-xvf3800-circular4-xiao/README.md) | Circular-4、XVF3800 与 AIC3104，无屏 |
+| `sensecap-watcher` | [中文](sensecap-watcher/README.md) / [English](sensecap-watcher/README_en.md) | SPD2010、编码器与工厂数据保护 |
+| `xingzhi-cube-1.54tft-wifi` | [README](xingzhi-cube-1.54tft-wifi/README.md) | ST7789、独立 I2S 与音量按键 |
+| `zhengchen-1.54tft-ml307` | [README](zhengchen-1.54tft-ml307/README.md) | ST7789、独立 I2S，当前使用 Wi-Fi |
+| `zhengchen-1.54tft-wifi` | [README](zhengchen-1.54tft-wifi/README.md) | ST7789、独立 I2S 与音量按键 |
+
+硬件参考资料及文档来源见
+[VENDORED_SOURCES.md](../../../VENDORED_SOURCES.md#board-reference-documents)，许可归属见
+[THIRD_PARTY_NOTICES.md](../../../THIRD_PARTY_NOTICES.md)。构建结果与实机验证状态分别记录在
+[平台移植说明](../../../docs/BOARD_PORTING.zh-CN.md)中。
diff --git a/components/mybot_platform/boards/atom-echos3r/README.md b/components/mybot_platform/boards/atom-echos3r/README.md
@@ -0,0 +1,45 @@
+# M5Stack AtomEchoS3R
+
+本目录是 agora-esp32-devkit 的 `atom-echos3r` 板级 profile，面向
+ESP32-S3-PICO-1-N8R8 与 ES8311 音频硬件。该 profile 无屏幕，不编入 LVGL。
+
+## 硬件与当前 profile
+
+| 项目 | 当前配置 |
+| --- | --- |
+| 存储 | 8 MB QIO Flash、80 MHz 8 MB Octal PSRAM |
+| 分区 | 根目录 `partitions/v2/8m.csv` |
+| ES8311 I2C0 | SDA GPIO45、SCL GPIO0；7 位地址 `0x18` |
+| I2S 音频 | MCLK GPIO11、BCLK GPIO17、WS GPIO3、DIN GPIO4、DOUT GPIO48 |
+| 扬声器功放 | GPIO18 使能 |
+| 用户按键 | GPIO41，当前按低电平有效配置 |
+
+音频接口使用 16 kHz、单声道、signed 16-bit PCM。引脚定义见
+[board_config.h](board_config.h)，构建约束见 [board.cmake](board.cmake) 与
+[sdkconfig.defaults](sdkconfig.defaults)。
+
+## 构建
+
+在工程根目录激活 ESP-IDF v5.5.2 后构建中英文固件：
+
+```sh
+. /path/to/esp-idf/export.sh
+test "$(idf.py --version)" = "ESP-IDF v5.5.2"
+python3 scripts/build_all.py --board atom-echos3r --language both
+```
+
+中间构建目录为 `build/build-atom-echos3r-<语言>/`，默认生成根目录 `releases/atom-echos3r-zh-CN.bin` 与
+`releases/atom-echos3r-en-US.bin`。构建器默认清理所选构建/输出根目录，详情与烧录入口见
+[根目录构建说明](../../../../README.zh-CN.md#构建)。本板不支持视频构建。
+
+## 使用与验证边界
+
+未保存 Wi-Fi 凭据时，设备创建配置热点并播放对应语言的配网提示音。短按 GPIO41 用户按键
+开始或结束对话，长按 3 秒先停止 SDK，再进入配网。当前未接入本地唤醒词，不要求通过
+语音唤醒操作设备。
+
+GPIO41 用户按键映射、极性及 16 kHz 双向音频质量仍需真机验证。构建成功不代表已经完成
+这些硬件验证；无屏状态可结合串口日志与语音提示确认。
+
+板级集成约定见 [板级移植](../../../../docs/BOARD_PORTING.zh-CN.md)，
+相关上游许可见 [MIT 许可文本](../../assets/LICENSE.xiaozhi-esp32)。
diff --git a/components/mybot_platform/boards/bread-compact-wifi-lcd/README.md b/components/mybot_platform/boards/bread-compact-wifi-lcd/README.md
@@ -0,0 +1,34 @@
+# Bread Compact Wi-Fi LCD
+
+本说明根据本工程的 [board.cmake](board.cmake)、[board_config.h](board_config.h) 和
+[sdkconfig.defaults](sdkconfig.defaults) 整理；参考工程没有该板型的独立 README。
+
+## 硬件配置
+
+| 项目 | 当前 profile |
+| --- | --- |
+| MCU | ESP32-S3，N16R8 配置 |
+| Flash | 16 MB，QIO |
+| PSRAM | 8 MB，Octal，80 MHz |
+| 显示 | ST7789，240×320，SPI；GPIO42 PWM 背光 |
+| 音频 | 麦克风与扬声器使用独立 I2S，16 kHz 单声道 |
+| 输入 | GPIO0 Boot 按键，无独立音量键、无触摸 |
+| 网络 | Wi-Fi |
+| 分区 | `partitions/v2/16m.csv` |
+
+麦克风 WS/BCLK/DIN 分别为 GPIO4/5/6，扬声器 DOUT/BCLK/WS 分别为 GPIO7/15/16。
+显示引脚及方向配置见 `board_config.h`。当前 profile 没有摄像头支持。
+
+## 构建
+
+在工程根目录激活 ESP-IDF v5.5.2 后执行：
+
+```sh
+python3 scripts/build_all.py --board bread-compact-wifi-lcd --language both
+```
+
+默认合并产物为 `releases/bread-compact-wifi-lcd-zh-CN.bin` 和
+`releases/bread-compact-wifi-lcd-en-US.bin`。
+
+构建与烧录的完整说明见[项目文档](../../../../README.zh-CN.md#构建)。当前板型的
+实机验证状态见[平台移植文档](../../../../docs/BOARD_PORTING.zh-CN.md)。
diff --git a/components/mybot_platform/boards/esp-vocat/README.md b/components/mybot_platform/boards/esp-vocat/README.md
@@ -0,0 +1,51 @@
+# Espressif ESP-VoCat 喵伴
+
+本目录是 agora-esp32-devkit 的 `esp-vocat` 板级 profile。硬件资料见
+[ESP-VoCat 开源硬件项目](https://oshwhub.com/esp-college/echoear)；硬件具备的器件与算法能力
+不等于本固件已实现的功能。
+
+## 硬件与当前 profile
+
+| 项目 | 当前配置 |
+| --- | --- |
+| 主控与存储 | ESP32-S3、16 MB QIO Flash、80 MHz Octal PSRAM |
+| 分区 | 根目录 `partitions/v2/16m.csv` |
+| 音频 | ES7210 采集、ES8311 播放，16 kHz 单声道 signed 16-bit PCM |
+| 公共 I2C0 | SDA GPIO2、SCL GPIO1；ES8311 `0x18`、ES7210 `0x40`、CST816S `0x15` |
+| I2S | MCLK GPIO42、BCLK GPIO40、WS GPIO39、DOUT GPIO41 |
+| 显示 | 360 × 360 ST77916 QSPI 圆屏，共享 LVGL UI |
+| 输入 | CST816S 触摸中断 GPIO10、Boot GPIO0 |
+| 控制台 | USB Serial/JTAG，避免 UART0 与板载外设引脚冲突 |
+
+初始化时探测兼容的 PCB 版本：V1.0 使用 DIN GPIO15、PA GPIO4、GPIO3 低有效 LCD reset；
+V1.2 使用 DIN GPIO3、PA GPIO15、GPIO47 高有效 LCD reset。无法探测 ES8311 时初始化失败，
+不会盲选引脚。完整定义见 [board_config.h](board_config.h)、[board.cmake](board.cmake) 与
+[sdkconfig.defaults](sdkconfig.defaults)。发布设备仍需确认实际 PSRAM 容量和 PCB 引脚映射。
+
+## 构建
+
+在工程根目录激活 ESP-IDF v5.5.2 后构建中英文固件：
+
+```sh
+. /path/to/esp-idf/export.sh
+test "$(idf.py --version)" = "ESP-IDF v5.5.2"
+python3 scripts/build_all.py --board esp-vocat --language both
+```
+
+中间构建目录为 `build/build-esp-vocat-<语言>/`，默认生成根目录 `releases/esp-vocat-zh-CN.bin` 与
+`releases/esp-vocat-en-US.bin`。构建器默认清理所选构建/输出根目录，详情与烧录入口见
+[根目录构建说明](../../../../README.zh-CN.md#构建)。本板不支持视频构建。
+
+当前 UI 由板级配置自动启用，无需下载额外 UI 资源包。
+
+## 使用与验证边界
+
+短触屏幕或短按 Boot 开始/结束对话；长触或长按 3 秒进入配网。当前只向 SDK 提供主麦克风
+采集通道，未接入第二麦克风、播放参考通道、本地 AEC、本地唤醒词或声源定位。
+
+电量、IMU、PCB 电容控制、SD 卡、LED、摄像头扩展、关机与低功耗尚未接入。PCB V1.0 有固件
+无法修复的已知硬件供电稳定性问题。本 profile 尚未完成真机验证，编译成功不能替代电源、
+触摸、显示和双向音频验证。
+
+板级集成约定见 [板级移植](../../../../docs/BOARD_PORTING.zh-CN.md)，
+相关上游许可见 [MIT 许可文本](../../assets/LICENSE.xiaozhi-esp32)。
diff --git a/components/mybot_platform/boards/esp32-s3-touch-amoled-1.75/README.md b/components/mybot_platform/boards/esp32-s3-touch-amoled-1.75/README.md
@@ -0,0 +1,49 @@
+# Waveshare ESP32-S3-Touch-AMOLED-1.75
+
+本目录是 agora-esp32-devkit 的 `esp32-s3-touch-amoled-1.75` 板级 profile，面向
+[Waveshare ESP32-S3-Touch-AMOLED-1.75](https://www.waveshare.com/esp32-s3-touch-amoled-1.75.htm)。
+本版本与 1.75C 引脚不同，需按实际板型选择固件。
+
+## 硬件与当前 profile
+
+| 项目 | 当前配置 |
+| --- | --- |
+| 主控与存储 | ESP32-S3、16 MB QIO Flash、80 MHz 8 MB Octal PSRAM |
+| 分区 | 根目录 `partitions/v2/16m.csv` |
+| 音频 | ES7210 采集、ES8311 播放，16 kHz 单声道 signed 16-bit PCM |
+| 公共 I2C0 | SDA GPIO15、SCL GPIO14；AXP2101 `0x34`、ES8311 `0x18`、ES7210 `0x40`、CST9217 `0x5a` |
+| I2S | MCLK GPIO42、BCLK GPIO9、WS GPIO45、DIN GPIO10、DOUT GPIO8；PA GPIO46 |
+| 显示 | 466 × 466 CO5300 QSPI AMOLED，显示偏移 (6, 0)，共享 LVGL UI |
+| 显示 reset / 触摸 reset | GPIO39 / GPIO40 |
+| 输入 | CST9217 中断 GPIO11、Boot GPIO0 |
+| TCA9554 | 在 `0x20` 可选探测 |
+
+完整引脚与配置见 [board_config.h](board_config.h)、[board.cmake](board.cmake) 与
+[sdkconfig.defaults](sdkconfig.defaults)。此 profile 与 1.75C 复用公共板级生命周期、音频和
+输入实现，但分别保留自身的 MCLK、reset 与器件配置。
+
+## 构建
+
+在工程根目录激活 ESP-IDF v5.5.2 后构建中英文固件：
+
+```sh
+. /path/to/esp-idf/export.sh
+test "$(idf.py --version)" = "ESP-IDF v5.5.2"
+python3 scripts/build_all.py --board esp32-s3-touch-amoled-1.75 --language both
+```
+
+中间构建目录为 `build/build-esp32-s3-touch-amoled-1.75-<语言>/`，默认生成根目录 `releases/esp32-s3-touch-amoled-1.75-zh-CN.bin` 与
+`releases/esp32-s3-touch-amoled-1.75-en-US.bin`。构建器默认清理所选构建/输出根目录，详情与烧录入口见
+[根目录构建说明](../../../../README.zh-CN.md#构建)。本板不支持视频构建。
+
+## 使用与验证边界
+
+短触屏幕或短按 Boot 开始/结束对话，长触或长按 3 秒进入配网。采集只提供主麦 slot，保留
+Cloud AEC；未向 SDK 提供播放参考通道或本地 AEC。RTC、IMU、TF 卡、电池状态、自动休眠与
+关机手势尚未接入，硬件产品页列出的器件不代表这些功能已在本固件启用。
+
+本 profile 尚未完成真机验证，需确认电源时序、显示方向和颜色、触摸及 16 kHz 双向音频。
+编译成功不代表完成上述验证。
+
+板级集成约定见 [板级移植](../../../../docs/BOARD_PORTING.zh-CN.md)，
+相关上游许可见 [MIT 许可文本](../../assets/LICENSE.xiaozhi-esp32)。