AI Passport Treasure Hunt

English | 简体中文

trae ai创造力大赛送的电子通行证可以带回家，于是让AI重写了一个小游戏跟小朋友玩😀 把两台 FoloToy AI Passport 变成一套离线像素寻宝游戏：一台藏起来，另一台根据 BLE 信号强弱和逐渐加急的 原创电子音效寻找它。它也可以用来玩蒙眼捉人、冷热提示和亲子寻宝。

两台设备运行完全相同的固件，不需要手机 App、Wi-Fi、账号、云服务或麦克风。

这是基于 FoloToy 开源硬件开发基线制作的社区项目，并非 FoloToy 官方固件。

直接烧录

已经准备好可供网页烧录的单个合并固件：

• 下载 ai-passport-treasure-hunt-universal.bin
• 芯片：ESP32-C3
• 烧录地址：0x0
• 两台设备使用同一个 .bin 文件
• 查看 SHA-256 校验值

烧录步骤：

1. 用 USB 连接第一台 AI Passport。
2. 打开 FoloToy 网页烧录器。
3. 选择“单个合并固件”，上传上面的 .bin，烧录地址使用 0x0。
4. 烧录完成后重启设备。
5. 对第二台设备重复相同步骤。

更详细的刷机说明和实机验收清单见 artifacts/TREASURE_HUNT_FLASHING.md。

怎么玩

1. 设置本机

准备界面包含三个选项：

• 短按 OK：切换黄色选中项。
• UP / DOWN：修改当前选项。
• 设置会保存到 NVS，重启后仍然有效。
• 两台设备可分别决定是否发声，因此可以让寻找者发声、宝藏发声、双方发声， 或只看屏幕提示。

2. 手动组队

1. A 设备长按 OK，开始广播邀请并显示 WAITING FOR PARTNER。
2. B 设备扫描到稳定邀请后显示 JOIN PLAYER?。
3. B 使用 UP / DOWN 选择 YES 或 NO，短按 OK 确认。
4. 选择 YES 后，两台设备锁定同一局并进入20秒 HIDE NOW! 倒计时。
5. 选择 NO 或长按 OK 会拒绝或取消本次邀请，不会误组队。

倒计时给玩家时间藏好设备。倒计时期间长按 OK 可以退出本局。

3. 开始寻找

倒计时结束后，屏幕根据锁定设备的 BLE RSSI 显示五档相对距离：

进入 EXTREMELY NEAR 后必须连续保持3秒，确认进度条填满才算真正找到。 中途变远或丢失新鲜信号会清空进度，避免仅靠一次 RSSI 尖峰误判。

BLE RSSI 只能反映相对远近，不是精确测距。人体遮挡、墙壁、盒子、设备方向和 环境反射都会影响结果。默认阈值集中在 main/distance_estimator.c，可按实机环境校准。

4. 寻找中的按键

• UP / DOWN：即时调整本机音量。
• 短按 OK：发起或取消主动救援。
• 长按 OK：退出本局。
• 找到后短按 OK：重新开始组队。

主动救援

如果宝藏藏得太好，寻找者可以短按 OK 发起救援。请求会持续通过 BLE 广播， 即使对方暂时不在范围内，重新走近后仍能收到。

收到救援请求的设备会：

• 临时覆盖普通静音设置；
• 以100%音量播放明显的救援报警；
• 在屏幕上显示救援状态；
• 最长响30秒，取消或退出时提前停止；
• 结束后恢复原来的声音和音量设置。

救援不会因为“找太久”自动触发，只能由玩家主动发起。

电量、亮度与内存保护

• 配对前显示本机电量，配对后显示双方电量。
• 对方电量超过10秒未更新时保留最后数值并显示 ?；未知时显示 --。
• 寻找界面15秒没有按键后，背光降到30%；第一次按键只负责唤醒，避免误操作。
• LVGL 使用64KB固定内存池；启动和游戏状态切换时会记录 LVGL 剩余量、最大连续 空闲块、碎片率，以及 ESP 内部堆的当前值和历史最低值。
• 界面避免使用容易产生大块临时绘制层的缩放、旋转和分层透明效果。

技术实现

• ESP-IDF 5.5.3 / ESP32-C3
• NimBLE 无连接广播 + 被动扫描，不建立 BLE 连接或绑定
• 版本化 manufacturer data 协议，同步邀请、加入、倒计时、找到和救援状态
• RSSI 中值窗口、低通滤波和迟滞，降低信号抖动
• 纯 C 游戏状态机，可在 macOS/Linux 主机上测试
• ES8311 上实时生成16kHz单声道原创音效，不包含语音或复制的游戏音乐
• CW2017 电量显示和过期状态处理
• LVGL 9 像素风界面，适配 240×320 ST7789P3 屏幕
• 单个合并固件，包含 bootloader、分区表和应用

从源码构建

准备 ESP-IDF 5.5.3，然后执行：

source /path/to/esp-idf-v5.5.3/export.sh
idf.py set-target esp32c3
idf.py build

运行不依赖硬件的主机测试：

bash tests/run_host_tests.sh

测试覆盖距离滤波、BLE协议、手动组队、倒计时、3秒找到确认、救援、音效、 偏好设置、电量、UI布局和内存采集边界。

项目结构

main/                    寻宝状态机、BLE、距离、音效、界面和应用入口
components/bsp/          AI Passport 显示、按键、音频、电量和共享 I2C BSP
tests/                   可在主机运行的逻辑与边界测试
artifacts/               合并固件、SHA-256 和网页烧录说明
sdkconfig.defaults       ESP32-C3、BLE、64KB LVGL 内存池等默认配置

开源与来源

本项目基于 FoloToy/ai-passport 开发，硬件 BSP 源自上游项目。本仓库只保留寻宝游戏所需的代码、 测试和烧录资料。源代码按照仓库中的 MIT License 发布。