FoloToy AI Passport 有一块 240 × 320 屏幕、三个实体按键和一颗 ESP32-C3。故事机固件之外，这套硬件也很适合做一块安静的桌面仪表。
FoloToy Usage 会显示 Claude 和 Codex 的额度、重置倒计时、今日与累计 Token，以及 API 等价费用。它没有麦克风、TTS 或模型密钥，也不会把网页硬塞进小屏。整个界面按 240 × 320 的真实尺寸重新设计。
为什么要把用量放在一块小屏上
手机和浏览器都能查用量，但它们需要一次主动操作。拿起手机、解锁、找到页面，通常还会顺手被别的通知带走。
小屏的价值来自“常驻”。它放在键盘边，额度接近上限、重置时间变化或数据变旧时，抬眼就能看到。它不会让工作流更复杂，也不负责替你做额度管理。
FoloToy Usage 还保留了硬件本身的手感：
- 上下键在额度页和用量页之间切换；
- 额度页轻按确认键，在“已用”和“剩余”之间切换；
- 长按确认键主动刷新；
- 每分钟自动取数，重置倒计时在设备端持续更新。
界面用红色区分 Claude、蓝色区分 Codex。首页保留头像、名称、日期和时间。数字使用独立等宽字体，中文标签使用 Noto Sans SC 子集，避免在 240 × 320 上缩成一团。
谁适合用，谁不适合
如果你已经有 FoloToy AI Passport，又经常同时使用 Claude Code 与 Codex，这个项目能把闲置硬件变成每天都看得见的工具。它也适合喜欢物理设备、希望用量信息离开主显示器的人。
下面几种情况更适合直接使用 UsageHub 网页或 Android 版：
- 你没有 AI Passport；
- 你不想安装 ESP-IDF，也不想通过 USB 刷写固件；
- 你希望同一套固件继续承担故事音频功能。FoloToy Usage 是独立固件，不包含故事机语音资源；
- 你要一套完全自托管云端。仓库只公开设备固件，云服务需要另行实现兼容接口。
它和 UsageHub Open 的关系
FoloToy Usage 是显示端。电脑上的 Claude/Codex 数据仍由 UsageHub Open 采集器写入同一个工作空间。
Claude / Codex on computer
│
▼
UsageHub Open collector
│
▼
UsageHub workspace
│ read-only Display Token
▼
FoloToy AI Passport
设备通过 HTTPS 调用 GET /v1/dashboard。它先同步网络时间，再校验证书，不接受重定向。Wi-Fi 只能连局域网、不能访问 Internet 或 NTP 时，数据不会刷新。
安装前要准备什么
你需要：
- 一台 FoloToy AI Passport；
- 一根可传数据的 USB 线；
- 2.4 GHz Wi-Fi，且能访问 Internet 和 NTP；
- ESP-IDF 5.5.3；
- UsageHub 的只读 Display Token，或一次性显示设备配对码。
配置前关闭串口监视器，避免它占用设备端口。macOS 的端口通常类似 /dev/cu.usbmodem...，请以自己电脑实际显示的名称为准。
第 1 步：获取源码并固定版本
git clone https://github.com/cfrs2005/folotoy-usage.git
cd folotoy-usage
git checkout v0.1.0
Release 同时提供通用固件、源码 ZIP 和 SHA256 校验文件。已有设备仍建议按仓库文档使用分段 idf.py flash，不要看到 full.bin 就整片覆盖。
第 2 步：激活 ESP-IDF 并检查工程
先安装 ESP-IDF 5.5.3，再激活环境。下面的路径只是示例：
source /path/to/esp-idf/export.sh
idf.py --version
./tools/validate.sh
idf.py --version 应显示 ESP-IDF v5.5.3。校验脚本会执行公开内容审计、主机测试、固件构建和分区检查。
项目保护三类硬件边界：应用镜像不能超过 3 MB；0x356000 的设备身份区要保留；0x700000 的 Recovery 和开机长按上键五秒的恢复入口也要保留。
已有 AI Passport 不要运行
erase-flash。整片擦除会破坏设备身份和永久恢复固件。
第 3 步：通过 USB 刷入
把端口替换成你的设备端口：
idf.py -p /dev/cu.YOUR_DEVICE flash
这条命令按工程分区表写入需要更新的分区。刷入后不要急着打开串口监视器，下一步的配置工具还要使用同一个端口。
第 4 步：写入 Wi-Fi 和显示凭据
python tools/configure.py --port /dev/cu.YOUR_DEVICE
工具会询问 2.4 GHz Wi-Fi，以及只读 Display Token 或一次性显示设备配对码。配对码要在 UsageHub 登录后创建。采集器接入码不能拿来给小屏配对。
电脑会通过校验证书的 HTTPS 兑换一次性配对码，只有只读 Display Token 会写入设备。Wi-Fi 和 Token 保存在 NVS，不会编进源码或公开固件。
如果想先连 Wi-Fi、稍后再配对，可以运行：
python tools/configure.py --port /dev/cu.YOUR_DEVICE --wifi-only
装好后怎么检查
启动后先看额度页。Claude 和 Codex 各有 5 小时与 7 天数据、进度条和重置倒计时。按上下键切到用量页，确认今天和累计 Token 已出现，再试一次确认键刷新。
缺失值应显示 --，不能伪装成 0。网络中断时，设备保留内存里的最后一份数据；超过三分钟或云端标记为旧数据时，屏幕会显示“数据较旧”。额度和 Token 各自判断新鲜度。
需要保留验收证据时，可以通过 USB 获取设备实际渲染的像素块：
python tools/screenshot.py --port /dev/cu.YOUR_DEVICE --output screen.png
截图可能包含头像和真实用量，发到公开 Issue、博客或社交平台前要先脱敏。本文使用的是仓库已经处理过的示例图。
头像同步是可选项
默认固件不会编入个人头像或 Token。配对后可以用本机私有配置同步云端头像：
python tools/sync_profile.py \
--port /dev/cu.YOUR_DEVICE \
--config device.local.json
这个工具需要 Pillow 和 pyserial。它把头像缩到 40 像素后单独写入 NVS。device.local.json 含服务地址和只读 Token，不能提交到 Git。
我重新跑过哪些检查
发文前，我在 ESP-IDF 5.5.3 环境运行了 ./tools/validate.sh --static。公开内容审计检查了 60 个源码文件，没有发现构建产物或未脱敏敏感值；9 个主机测试和 Usage 数据模型测试全部通过。
长期无人值守仍需单独验证。仓库当前明确写着：USB 刷入、云端加载、头像同步、真实屏幕渲染和多次切页已经检查；小程序实际安装和长时间稳定运行仍未完成验收。
转让设备前别忘了清理
设备的 NVS 目前没有加密。拿到 Flash 物理读取权限的人可能恢复 Wi-Fi 和只读 Display Token。转让设备前，要先在 UsageHub 撤销 Token，再清除 usage NVS 命名空间。不要上传整片 Flash 备份、NVS 镜像或串口日志。
查看 FoloToy Usage 源码。项目使用 MIT 许可证，当前公开 Release 为 v0.1.0。
