TRAE 创造力大赛身份牌 · 基于官方 BSP 源码与实测验证整理
1. 设备概览
FoloToy AI Passport 是 TRAE 创造力大赛随赠的身份牌，本质是一块基于 ESP32-C3 的 AI 语音交互开发板，官方定位为"AI 语音护照"。内置麦克风、喇叭、TFT 彩屏、按键和电池，原厂固件支持语音对话、微信小程序同步身份信息等功能。
图 2：AI Passport 正面渲染（官方）
| 关键项 | 规格 |
|---|---|
| 主控 | ESP32-C3（RISC-V 单核 160MHz） |
| 存储 | 8MB Flash，无 PSRAM |
| 屏幕 | 240×320 TFT（ST7789P3 彩屏） |
| 无线 | BLE + Wi-Fi 2.4GHz |
2. 硬件规格
| 模块 | 规格 |
|---|---|
| MCU | ESP32-C3，RISC-V 单核 160MHz，8MB Flash，无 PSRAM |
| 屏幕 | ST7789P3 TFT LCD，240×320 竖屏，RGB565，SPI2 40MHz mode 0 |
| 背光 | GPIO21，LEDC PWM 5kHz / 10bit 可调光 |
| 按键 | 3 个物理键（UP / DOWN / OK），共用 GPIO0 ADC 分压电阻梯 |
| 音频 | ES8311 codec（麦克风 + 喇叭），I2S 全双工 |
| 电池 | CW2017 电量计 + 520mAh 锂电池 |
| NFC | NTAG213 被动标签（不连 MCU，仅手机碰读身份信息） |
| USB | Type-C 2.0，USB Serial/JTAG（GPIO18/19） |
| 电源 | 独立硬件电源键（区别于三功能键） |
实测核对（MicroPython 直读）
以下为刷入 MicroPython 后，通过 REPL 直接读取板载硬件得到的结果，与官方规格完全一致。
| 硬件 | 实测结果 | 核对 |
|---|---|---|
| 芯片 | MicroPython 报告 ESP32-C3 module |  |
| Flash | 8388608 bytes = 8MB | |
| 内存 | free 170KB / alloc 5KB（无 PSRAM） | |
| 音频 codec | I2C 0x18 响应，寄存器 0x80 | |
| 电量计 | I2C 0x63 响应，VERSION 0x0f，电压 4196mV | |
| 按键 | GPIO0 松开态 3300mV（ADC 分压） | |
| 屏幕 | ST7789P3 已点亮并显示中文界面 | |
| MAC | 4C:11:AE:30:A6:68（Espressif OUI） | |
无 PSRAM 的影响要提前认清：这块板没有 PSRAM，单片机内存只有约 370KB（free 约 170KB）。跑 LVGL 大页面、放整屏位图缓冲、叠音频缓冲都会吃紧。超大 UI 素材建议放 Flash，按需分页读取，别一次性塞进内存。
3. 引脚分配
引脚定义来自官方 BSP（bsp_pins.h），是板级配置的"单一事实来源"。
| GPIO | 功能 | 说明 |
|---|---|---|
| 0 | 三键 ADC 节点 | ADC1_CH0，boot 相关引脚 |
| 1 | LCD CS | ST7789P3 片选 |
| 2 | I2S DOUT | MCU → ES8311 播放 |
| 3 | I2S WS | I2S 帧同步 |
| 4 | I2S DIN | ES8311 → MCU 录音 |
| 5 | I2S BCLK | I2S 位时钟 |
| 6 | I2S MCLK | codec 主时钟 |
| 7 | I2C SCL | ES8311 + CW2017 共用 |
| 8 | LCD SCLK | SPI2 时钟 40MHz |
| 9 | LCD MOSI | 无 MISO，屏幕不可读 |
| 10 | I2C SDA | 内部上拉已启用 |
| 18/19 | USB Serial/JTAG | 串口控制台 |
| 20 | LCD DC | 命令/数据选择 |
| 21 | 背光 PWM | 与 UART0 默认 TX 冲突 |
I2C 设备地址：ES8311 = 0x18，CW2017 = 0x63（7 位地址）
引脚细节补充
- 几乎全部 GPIO 都被占用：屏幕占了 SPI（1/8/9/20），音频占了 I2S（2/3/4/5/6）和一路 I2C（7/10），剩下能自由用的 GPIO 非常有限。如果要做交互扩展（额外按键 / 传感器），要专门规划。
- GPIO0 身兼数职：既是 boot 选择引脚、又是三键 ADC 采样脚。按键通过分压电阻梯挂在不同电压点，靠 ADC 量程区分。这意味着 GPIO0 不能当普通 IO 用，且按下时电压会被拉低，boot 时序要小心。
- GPIO21 与 UART0 TX 冲突：背光 PWM 默认接 GPIO21，若想复用串口打印日志，两者会打架。MicroPython 下
machine.UART默认走的就是 0/1，用 GPIO21 做背光时别指望同时用默认串口输出。
4. 无线能力
这块板子无线能力齐全，BLE 和 Wi-Fi 都支持，可灵活用于各类物联网 / 可穿戴场景。
| 无线方式 | 支持 | 详情 |
|---|---|---|
| BLE | |
NimBLE 协议栈，peripheral 模式（广播 / 连接 / GATT / 特征读写 / 通知） |
| Wi-Fi | |
2.4GHz station 模式，官方 demo 有扫描页 |
设备 (peripheral) ← BLE → 手机 (central) ← 网络 → 云端
BLE 实测（MicroPython 上板跑通）
微控制器内置 BLE，刷入 MicroPython 后可用 bluetooth 模块直接做 peripheral，不需额外硬件。
- 服务 / 特征骨架：
BLE_GAP_APPEARANCE+ 自定义服务（如6E400001-...），一个「写」特征收命令、一个「通知」特征上行数据，收到写消息回显echo。 - 广播名自定义：可设成
SmartBadge这类易识别的名字，手机端扫 BLE 时一眼定位。 - 连接后互动：手机写入特征 → 板子回显 → 手机收到通知，整条链路实测可用。做「设备 ↔ 手机」数据中转（状态上报 / 命令下发）基本不用改协议栈。
- 配合上方无 PSRAM 说明：BLE 收发的数据量要克制，超大 payload 会挤压内存，建议拆小包。
5. 软件与固件
Flash 分区布局（8MB）
| 分区 | 大小 / 地址 | 说明 |
|---|---|---|
| NVS | 24KB | 非易失存储 |
| PHY | 4KB | 射频校准数据 |
| Factory | 3MB | 主应用固件 |
| cardid | 0x356000 | 受保护设备身份分区 |
| Recovery | 0x700000 | 永久恢复分区（非双槽 OTA） |
原厂固件架构
基于 ESP-IDF 5.5.3，BSP 组件（components/bsp）封装屏幕、按键、音频、电池等硬件；LVGL 负责 UI；Wi-Fi / BLE 用 ESP-IDF 原生接口。Recovery 分区支持 BLE 安装固件，bootloader 在按住 UP 键 5 秒时进入。
recovery 分区值得利用
这块板子的 OTA 机制是「Factory + Recovery 单槽」而非双槽 A/B。Recovery 永久存在，意味着你可以始终保住一个能恢复的固件入口——即使主固件刷坏，也能在 recovery 里重新写，容错性比普通板好。刷机前记住这个机制，敢随便折腾主分区。
6. 实操经验
从零刷机到跑起 UI 的完整流程：
① 备份原厂固件
用 esptool 读取完整 8MB flash 备份，确保可随时恢复。
python -m esptool --port COM3 read_flash 0 0x800000 passport_backup.bin
② 刷入 MicroPython
擦除 flash 后烧录 MicroPython v1.29.0（ESP32-C3 通用固件），REPL 验证成功。
python -m esptool --port COM3 erase_flash
python -m esptool --port COM3 write_flash 0 ESP32_GENERIC_C3-v1.29.0.bin
烧录端口选择：这块板是 USB Serial/JTAG（GPIO18/19），不是传统外置 CP2102/CH340 串口。Windows 下会枚举成 COM 口，但芯片识别会显示为 Espressif 的 USB JTAG。刷机前在设备管理器确认端口号，常有两口并存的情况，别刷错口。
③ 点亮 ST7789P3 屏幕
关键：这块屏是 ST7789P3，需要厂商专属初始化序列（PORCTRL/GCTRL/伽马等 13 条命令），且写入像素前必须发 RAMWR (0x2C) 命令。
④ 生成并显示中文 UI
MicroPython 内置字体不支持中文，用 PIL 生成 240×320 RGB565 图片，mpremote 上传到板子文件系统，MicroPython 读取后经 SPI 显示。
python -m mpremote connect COM3 fs cp ui_standby.bin :ui_standby.bin
大 UI 分页读：240×320 的整屏 RGB565 约 150KB，远超 free 内存。别
read()整个塞进内存再write()，要分块读取 + 分块送显（比如一次 8 行），才能在这块板上流畅刷出全屏中文界面。
⑤ 按键交互
三键共用 GPIO0 ADC 分压，通过电压窗口区分 UP/DOWN/OK，实现待机 → 通知 → 确认的界面切换。
![正面结构与按键位置]
图 3：正面结构与按键布局（官方渲染）
7. 踩坑记录
-
坑 1：屏幕"卡住"显示原厂界面 — 刷完 MicroPython 后屏幕仍显示原厂画面。原因是板子一直 USB 供电，ST7789 的 GRAM 保留了原厂固件最后写入的画面；而我们的写入没生效。根因是初始化序列不完整 + 缺少 RAMWR 命令。
-
坑 2：ST7789P3 ≠ 通用 ST7789 — 普通 ST7789 初始化序列不够，必须用官方 BSP 里的厂商专属序列（PORCTRL/GCTRL/VCOMS/伽马等），否则屏幕不响应。
-
坑 3：电源键是硬件开关 — 板子有独立电源键，关机后 USB 不枚举（COM 口消失）。esptool 硬复位后可能关机，需要重新按电源键开机。
-
坑 4：NFC 是被动标签 — 板子上有 NTAG213，但它是被动 NFC 标签，不连 MCU、固件无任何 NFC 代码，无法做主动读卡/模拟卡。
-
坑 5：mpremote cp 路径坑 — mpremote 的 cp 命令对 Windows 路径解析有坑，文件必须放在正确目录并用绝对路径，否则报 “No such file or directory”。
-
坑 6：内存小，别整屏加载位图 — 没有 PSRAM，屏幕位图一次性
read()会 OOM。全屏 RGB565 必须分块读取分块送显（见第 6 节④）。 -
坑 7：刷机别刷错 COM 口 — USB Serial/JTAG 与可能的串口并存，Windows 会枚举多个 COM，插拔后端口还常变。刷之前先确认当前实际端口，别
--port COM3想当然。 -
坑 8：GPIO0 三键 + boot 纠缠 — GPIO0 既是 boot 选择脚又是三键 ADC 采样脚。下载/复位时序里按键状态会影响启动行为，按键测试时别当作普通 GPIO 主线逻辑去用。
8. 小结
这块 FoloToy AI Passport 是一块麻雀虽小五脏俱全的 ESP32-C3 开发板：屏幕、音频、电池、NFC、BLE、Wi-Fi 全部集成，价格亲民、生态成熟（ESP-IDF + MicroPython 双路）。最适合当可穿戴 / 语音交互 / 小彩屏设备的快速原型平台。
真正要注意的三件事：内存小（无 PSRAM）、GPIO 几乎全占用、屏幕驱动需要厂商专属序列。把这三关过了，剩下的就是常规 ESP32 开发流程。