小智 AI 自定义开发板
官方板指南开头的「重要提示」是建自定义板前必须先记住的边界：对于自定义开发板，当 IO 配置与原有开发板不同时，切勿直接覆盖原有开发板的配置编译固件；必须创建新的开发板类型，或者通过 config.json 文件中的 builds 配置不同的 name 和 sdkconfig 宏定义来区分，使用 python scripts/build.py [开发板目录名字] 来编译固件。
如果直接覆盖原有配置，将来 OTA 升级时，自定义固件可能会被原有开发板的标准固件覆盖，导致设备无法正常工作。每个开发板有唯一的标识和对应的固件升级通道，保持开发板标识的唯一性非常重要。
每个开发板目录通常包含四个文件：
| 文件 | 作用 |
|---|---|
| xxx_board.cc | 主要的板级初始化代码，实现板子相关的初始化和功能 |
| config.h | 板级配置文件，定义硬件管脚映射和其他配置项 |
| config.json | 上报开发板类型及发布配置，供 CMake 和 scripts/build.py 使用 |
| README.md | 开发板相关的说明文档 |
config.json 的三个关键字段：
| 字段 | 含义 |
|---|---|
| target | 目标芯片型号，必须与硬件匹配 |
| builds | 定义发布构建，其中的 name 是 release 构建上报的固件变体名称，用于生成固件包 |
| sdkconfig_append | 追加到默认配置中的额外 sdkconfig 配置项数组 |
type 和 name 只能包含小写字母、数字、点（.）和连字符（-），不允许使用下划线、空格或大写字母。不要在板子的 config.json 中选择语言或具体唤醒词，这些属于用户构建选项，应统一通过 menuconfig 或构建脚本参数配置。
- 创建板目录：
mkdir main/boards/my-custom-board，命名使用 [品牌名]-[开发板类型] 的形式，例如 m5stack-tab5。预期结果：main/boards/ 下出现以新板名命名的新目录。 - 编写 config.h：定义音频采样率与 I2S 引脚、音频编解码芯片地址与 I2C 引脚、按钮和 LED 引脚、显示屏参数与引脚。预期结果：所有管脚映射与硬件原理图一致，板级代码可直接引用这些宏。
- 编写 config.json：填写 type（固件上报的开发板系列类型，发布后应保持稳定）、target、builds（含 name 与 sdkconfig_append）。预期结果：文件能通过 JSON 解析，且 name 与任何原有板都不同，从源头保证 OTA 升级通道不与原有板冲突。
- 添加构建系统配置：在 main/Kconfig.projbuild 的 choice BOARD_TYPE 部分添加新板配置项（配置项名称全大写、下划线分隔，用 depends on 指定目标芯片，如 IDF_TARGET_ESP32S3）；在 main/CMakeLists.txt 的开发板类型判断部分添加 elseif(CONFIG_BOARD_TYPE_MY_CUSTOM_BOARD) 并将 BOARD_DIR 指向你的板目录。预期结果：menuconfig 的板型列表里出现这块自定义开发板。
- 编写板级初始化代码 xxx_board.cc：板级类继承自 WifiBoard 或 Ml307Board——官方继承关系为 Board 基础板级类，派生出 Wi-Fi 连接的 WifiBoard、使用 4G 模块的 Ml307Board、支持 Wi-Fi 与 4G 切换的 DualNetworkBoard——类内实现 I2C、显示屏、按钮、IoT 等初始化，重写 GetAudioCodec()、GetDisplay()、GetBacklight() 等虚函数，最后用 DECLARE_BOARD 宏注册开发板。预期结果：编译系统识别并注册该板类，选中该板后编译能链接到你的实现。
- 手动配置编译：执行
idf.py set-target esp32s3（另两档为idf.py set-target esp32c3与idf.py set-target esp32），需要时用idf.py fullclean清理旧配置，再执行idf.py menuconfig，导航到 Xiaozhi Assistant -> Board Type 选择你的自定义开发板，然后执行idf.py build与idf.py flash monitor。预期结果：编译产出固件并烧录成功，串口监视器输出这块板的启动日志。 - 改用脚本自动编译（官方推荐）：
python scripts/build.py my-custom-board。预期结果：脚本读取 config.json 中的 target 自动完成配置和编译，默认生成 build/merged-binary.bin，不创建 ZIP。 - 补写 README.md：说明开发板特性、硬件要求、编译和烧录步骤。预期结果：他人按文档可以复现从建板到烧录的整条链路。
常见组件按需组合：
- 显示屏：支持 ST7789（SPI）、ILI9341（SPI）、SH8601（QSPI）等驱动
- 音频：编解码器常用 ES8311，ES7210 用于麦克风阵列，AW88298 用作功放
- 电源：部分开发板使用 AXP2101 等电源管理芯片
- MCP 设备控制：可添加 Speaker（扬声器控制）、Screen（屏幕亮度调节）、Battery（电池电量读取）、Light（灯光控制）等工具，让 AI 能够操作对应硬件
与面包板接线教程的边界：官方教程为早期固件口径，当前固件以 v2.5.2 发布包为准。教程原文写明「目前两个版本接线方案的固件互不兼容，烧录固件时，要留意是哪个版本（固件版本在 0.3 之前的都是采用第一版接线方案），如果是自己编译固件，可以自行配置 GPIO」。
也就是两版接线对应的固件不能混烧；而自己建板编译时引脚由 config.h 决定，不受这两版接线方案的约束。