魔改 AI Passport：一枚大赛勋章的固件重写，变身随身网络音乐盒

FoloToy AI Passport 是 TRAE AI 创造力大赛线下活动发放的纪念勋章，硬件配置：ESP32‑C3 主控、240×320 彩屏、ES8311 音频芯片、自带扬声器与锂电池。官方固件主打「AI 伙伴」，我将其重制固件，改造为桌面网络音乐盒项目：TY MUSIC。

 项目功能

开机自动连接 WiFi，拉取云公开歌单曲目循环播放。整机仅三颗按键完成全部交互：上/下键切歌，OK 单击暂停播放，长按唤起菜单。

屏幕顶栏展示：TY MUSIC 标识、实时时钟、WiFi 信号、电池电量。 播放界面：频道号 CH 01/21、大号歌名，一排曲目进度格子，当前播放曲目格子高亮红色。

无需手机 App：设备启动后会广播热点 TYMusic‑XXXX，手机连接该热点，访问网页 192.168.4.1。 在配置网页搜索家庭 WiFi、填写密码、填入云歌单 ID，保存后设备自动重启，直接开始播放。

 技术路线

基于开源项目 FoloToy/ai‑passport，ESP‑IDF 5.5 工程，硬件驱动直接复用官方资料，工程分为两层：

• 板级层（BSP）：LVGL9 屏幕驱动、ES8311 音频编解码器、按键、I2C、CW2017 电量计，复用官方驱动并做适配修正。
• 应用层：整机状态机（启动 → 联网 → 播放/菜单/配网）、网络播放器、网页配网门户、歌单解析、UI 交互。

音频方案：基于 Meting API 获取歌单列表，解析音频直链；HTTP 流式接收音频，Helix MP3 软件解码，通过 I2S 输出至 ES8311 播放。无外置存储、不缓存音频，边拉边播。

ESP32‑C3 仅有 400KB RAM，同时运行 TLS、JSON 解析、LVGL，内存资源十分紧张：

• 舍弃封面、歌词等附加功能，只保留播放核心链路
• TLS 切换软件加密，收缩缓冲区大小
• 大块内存使用静态分配，避免动态 malloc 造成堆内存碎片化

UI：复古电台风

视觉采用复古电台风格：深色背景、琥珀色高亮，大字号歌名，曲目格子模拟调频刻度。屏幕分辨率仅 240×320，字号、间距全部像素级微调。

开发采用模拟器先行策略：先实现 1:1 屏幕尺寸的 HTML 模拟器，界面布局、配色、按键逻辑全部在浏览器调试完成，再移植为 LVGL 代码烧录。减少反复烧录、反复配网带来的调试成本。

两个关键移植难点：

1. 20px 中文字库优化 LVGL 默认 16px 中文显示偏小；完整 20px GB2312 字库体积 3.7MB，超出应用分区 3MB 上限。 解决方案：裁剪字库，仅保留 3238 个一级常用汉字，配置 fallback 降级到 16px 全字库，生僻字自动降级渲染，观感几乎无差别，固件最终控制在 2.99MB。
2. 时钟与电量采集 硬件无 RTC 芯片，联网后通过阿里云 SNTP 服务获取网络时间；电量读取复用 BSP 层 CW2017 驱动，每 2 秒读取一次电池数据。

成品效果

开机 10 秒内完成 WiFi 连接并自动播放；顶栏时钟精确到分钟，电量显示准确。 按键逻辑完整：上下切歌、OK 暂停、长按唤起菜单；更换歌单只需要在配置网页修改歌单 ID。 硬件零改动，几乎重写全部上层固件，把一枚大赛纪念勋章变成桌面网络电台。

烧录方式

方式一：网页刷写（推荐）

设备 USB‑C 连接电脑，Chrome / Edge 浏览器打开： https://ai‑passport.folotoy.cn/plays/184 点击「连接设备」，选择对应串口，网页直接烧录固件，无需额外安装工具。

方式二：esptool 命令行

# 1. 擦除 Flash（建议执行，清除旧固件残留配置）
esptool.py --chip esp32c3 --port COM3 --baud 115200 erase_flash

# 2. 0x0 地址烧录完整固件包
esptool.py --chip esp32c3 --port COM3 --baud 115200 write_flash 0x0 FoloToy-AI-Passport-full-0x0.bin

COM3 修改为你电脑实际设备端口；也可使用乐鑫 flash_download_tool 图形工具。

⚠️ 注意：整包烧录会清空 NVS，WiFi 配置丢失，烧完设备进入配网模式，需要重新配置网络。 直接烧录完整包 FoloToy‑AI‑Passport‑full‑0x0.bin；

按键速查表