Clawdmeter

在 AI 编程助手日益普及的今天，开发者往往难以直观感知自己的 Token 消耗与配额剩余。Clawdmeter 是一款基于 ESP32-S3 和 2.16 英寸 AMOLED 屏幕 的开源硬件仪表盘，专为监控 Claude Code 的使用情况而设计。

它通过蓝牙低功耗（BLE）与电脑配对，不仅实时显示会话百分比、周配额剩余及重置时间，更通过可爱的 Clawd 像素动画反映当前负载状态。此外，它还集成了两个物理快捷键，可直接触发 Claude Code 的语音模式与界面切换，将虚拟的 AI 交互转化为具象的桌面体验。

核心亮点：实时可视、动态反馈、物理交互

1. 实时用量监控，告别盲盒焦虑

• 多维度数据：清晰展示当前会话用量百分比（s）、会话重置倒计时（sr）、本周总用量百分比（w）及周重置倒计时（wr）。
• 低延迟同步：后台守护进程每 60 秒轮询一次 Claude API，通过 BLE GATT 特性将 JSON 数据推送到设备，确保信息即时更新。
• 状态指示：直接显示账户状态（如 allowed），让你随时掌握服务可用性。

2. 动态像素动画，情感化反馈

• Clawd 精灵库：集成 claudepix 像素艺术资源，启动画面播放可爱的 Clawd 动画。
• 负载感知：动画会根据当前使用率的变化率自动调整情绪——用量越高，动画越“忙碌”，提供直观的情感化反馈。
• 自动轮换：在启动画面停留时，固件每 20 秒自动轮换动画，避免视觉疲劳。

3. 物理快捷键，提升操作效率

• BLE HID 键盘模拟：两个侧边按钮通过标准 BLE HID 协议发送键盘指令，无需额外驱动。
  • 左键 (GPIO 0)：按住发送 空格键，快速激活 Claude Code 的语音模式（Push-to-Talk）。
  • 右键 (GPIO 18)：按下发送 Shift+Tab，快速切换 Claude Code 的界面模式或焦点。
• 全局生效：由于模拟标准键盘输入，快捷键在任何聚焦窗口中均有效，不仅限于 Claude Code。

4. 触控交互，简洁直观

• 三屏循环：点击屏幕可在“启动动画”、“用量详情”和“蓝牙信息”之间切换。
• 中间按钮：物理按键也可用于屏幕循环或在启动画面中手动切换动画。
• 一键关闭：在启动画面再次点击即可关闭屏幕，节省电量。

技术架构

• 硬件核心：Waveshare ESP32-S3-Touch-AMOLED-2.16（ESP32-S3R8, 480×480 AMOLED, CST9220 触摸, AXP2101 PMU）。
• 通信协议：
  • 自定义 GATT 服务：UUID 4c41555a-...，包含 RX（写入数据）和 TX（通知）特性。
  • HID 服务：标准键盘描述符，用于物理按键映射。
• 软件栈：
  • 固件：基于 PlatformIO + LVGL 9，处理 BLE 连接、JSON 解析、动画渲染及 HID 报告。
  • 守护进程：Python 脚本（macOS LaunchAgent / Linux systemd），负责 OAuth 令牌管理、API 轮询及 BLE 数据推送。

快速开始

硬件准备

• Waveshare ESP32-S3-Touch-AMOLED-2.16 开发板。
• USB-C 数据线（用于烧录与供电）。
• 3.7V 锂电池（可选，用于离线运行）。

macOS 部署

1. 烧录固件：

   ./flash-mac.sh                       # 自动检测端口
   # 或指定端口
   ./flash-mac.sh /dev/cu.usbmodem1101
   

2. 蓝牙配对：
   • 打开系统设置 → 蓝牙，找到 “Clawdmeter” 并点击连接。
   • 等待约 30 秒，守护进程将自动发现设备。
3. 安装守护进程：

   ./install-mac.sh
   

   • 脚本将创建 Python 虚拟环境，安装依赖，并注册 LaunchAgent。
   • 首次运行需授权蓝牙权限。
4. 管理守护进程：

   launchctl list | grep claude-usage                                          # 检查状态
   tail -F ~/Library/Logs/claude-usage-daemon.out.log                          # 查看日志
   launchctl unload ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist  # 停止
   launchctl load -w ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist # 启动
   

Linux 部署

1. 烧录固件：

   cd firmware
   pio run -t upload --upload-port /dev/ttyACM0
   

2. 蓝牙配对：

   bluetoothctl scan le
   # 出现 "Claude Controller" 后记录 MAC 地址
   bluetoothctl pair <MAC_ADDRESS>
   bluetoothctl trust <MAC_ADDRESS>
   

3. 安装守护进程：

   ./install.sh
   systemctl --user start claude-usage-daemon
   

4. 查看状态：

   systemctl --user status claude-usage-daemon
   journalctl --user -u claude-usage-daemon -f
   

适用场景

开发与定制

• 字体编译：使用 lv_font_conv 生成 LVGL 9 兼容字体，需注意移除 .cache 字段并添加 .fallback 等结构体成员。
• 图标转换：使用 tools/png_to_lvgl.js 将 Lucide PNG 图标转换为 RGB565 C 数组。
• 动画提取：运行 tools/scrape_claudepix.js 从网站提取帧数据，并通过 convert_to_c.js 生成固件可用的头文件。