1. 项目概述：Clawdmeter 是什么？

Clawdmeter 是一个基于 ESP32 的开源硬件项目，它通过蓝牙连接电脑，实时显示 Claude Code 的使用情况。这个桌面小工具解决了开发者频繁查看 API 用量的痛点 - 你不再需要打开终端输入命令或者登录网页后台，只需扫一眼桌上的小屏幕就能掌握用量信息。

这个项目在 GitHub 上已经获得了 1.4K Stars 和 160+ Forks，说明它确实击中了开发者的需求。它不仅仅是个显示器，还内置了三个物理按钮，可以快速触发 Claude Code 的语音模式和模式切换功能，相当于给你的工作台增加了一个专用的蓝牙快捷键面板。

2. 硬件配置与选型

2.1 核心硬件组件

Clawdmeter 的核心硬件是 ESP32 开发板和 AMOLED 显示屏的组合。项目作者选择了 Waveshare 的几款开发板作为官方支持硬件：

• ESP32-S3-Touch-AMOLED-2.16：2.16 英寸 AMOLED 触摸屏，搭载 ESP32-S3 芯片
• ESP32-C6-Touch-AMOLED-2.16：2.16 英寸 AMOLED 触摸屏，搭载 ESP32-C6 芯片
• ESP32-S3-Touch-AMOLED-1.8：1.8 英寸 AMOLED 触摸屏，搭载 ESP32-S3 芯片

选择这些开发板有几个关键考虑：

1. 内置高品质 AMOLED 屏幕，显示效果出色
2. 都带有触摸功能，方便交互设计
3. ESP32-S3/C6 芯片性能足够且功耗低
4. 板载电池管理电路，适合桌面设备使用

2.2 硬件扩展性

虽然项目主要支持上述三款开发板，但其架构设计考虑到了扩展性。固件采用 HAL（硬件抽象层）设计，核心逻辑与硬件驱动分离。这意味着如果你想使用其他 ESP32 开发板，只需要：

1. 在 firmware/src/boards/ 下新建对应板子的目录
2. 实现显示驱动、按钮 GPIO、触摸输入等接口
3. 创建对应的 PlatformIO 环境配置

这种设计让项目具有很强的适应性，开发者可以根据自己的需求选择合适的硬件方案。

3. 软件架构与实现

3.1 固件开发环境

项目使用 PlatformIO 作为开发环境，这是一个专业的嵌入式开发平台，相比传统的 Arduino IDE 提供了更强大的功能：

• 多平台支持（Windows/macOS/Linux）
• 完善的依赖管理
• 丰富的调试工具
• 支持多种构建配置

固件主要使用 C++ 开发，代码量约 180 万字符。UI 部分采用了 LVGL（Light and Versatile Graphics Library），这是一个开源的嵌入式图形库，特别适合资源受限的设备。

3.2 数据流设计

Clawdmeter 的数据流设计非常精巧，整个工作流程分为以下几个步骤：

1. 后台守护进程获取认证信息：

   • macOS：从系统钥匙串读取 OAuth Token
   • Linux：从 ~/.claude/.credentials.json 读取

2. 发送最小 API 请求：

   • 向 api.anthropic.com/v1/messages 发送基本请求
   • 使用 Claude Haiku 模型（成本最低）

3. 解析响应头获取用量数据：

   • anthropic-ratelimit-unified-5h-utilization：5小时窗口用量
   • 其他相关速率限制头信息

4. 通过 BLE 传输数据到设备：

   • 连接设备的 GATT RX Characteristic
   • 写入 JSON 格式的用量数据

5. 设备端更新显示：

   • 解析 JSON 数据
   • 更新 LVGL 界面元素
   • 根据用量变化率调整动画状态

这个设计的精妙之处在于它通过一次几乎免费的 API 调用（使用 Claude Haiku）就获取了所有需要的用量信息，避免了额外的 API 成本。

4. 用户界面设计

4.1 三种显示模式

Clawdmeter 提供了三种界面模式，通过中间的物理按钮切换：

1. Splash 动画屏：

   • 像素风格的 Claude 吉祥物动画
   • 动画状态根据用量自动调整
   • 低用量时显示悠闲动画
   • 高用量时显示忙碌动画
   • 每20秒自动切换同组内的不同动画

2. Usage 用量屏：

   • 显示会话用量百分比（Session %）
   • 显示周用量百分比（Weekly %）
   • 各自的剩余重置时间
   • 清晰的进度条可视化

3. Bluetooth 蓝牙屏：

   • 显示连接状态
   • 显示设备 MAC 地址
   • 提供重置蓝牙绑定的功能

4.2 动画设计细节

项目的动画设计非常用心，全部采用像素风格，素材来自 claudepix 资源库。动画不只是装饰，还承载了信息传达的功能：

• 动画组别：根据用量变化率分为"悠闲"、"正常"、"忙碌"三组
• 状态反映：用量增长快时，动画节奏会加快
• 细节丰富：每个状态组包含多个动画变体，避免单调

这种设计让设备不仅实用，还具有很好的观赏性，成为桌面上的一件"玩具"。

5. 功能扩展与物理控制

5.1 物理按钮功能

Clawdmeter 的三个物理按钮提供了实用的快捷功能：

1. 左侧按钮：

   • 长按：发送 Space 键（触发 Claude Code 语音模式）

2. 中间按钮：

   • 短按：切换显示模式
   • 在 Splash 屏：切换动画

3. 右侧按钮：

   • 按下：发送 Shift+Tab（切换 Claude Code 模式）

这些功能通过 BLE HID 键盘协议实现，意味着它们可以在任何应用程序中使用，不限于 Claude Code。

5.2 自定义功能扩展

项目保留了很好的扩展性，开发者可以通过修改代码添加新功能：

1. 添加新的屏幕模式：

   • 在 ui.cpp 中添加新屏幕类
   • 注册到屏幕管理器中

2. 增加按钮功能：

   • 修改 button_handler.cpp
   • 添加新的 HID 键值或组合键

3. 调整数据更新逻辑：

   • 修改 daemon 端的查询频率
   • 更改设备端的数据解析方式

6. 安装与使用指南

6.1 Linux 系统安装

对于 Linux 用户，安装过程如下：

1. 烧录固件：

./flash.sh waveshare_amoled_216

2. 蓝牙配对：

bluetoothctl scan le
bluetoothctl pair <MAC>
bluetoothctl trust <MAC>

3. 安装后台守护进程：

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

6.2 macOS 系统安装

macOS 的安装步骤略有不同：

1. 烧录固件：

./flash-mac.sh waveshare_amoled_216

2. 通过系统偏好设置完成蓝牙配对

3. 安装守护进程：

./install-mac.sh

macOS 版守护进程使用 Python 编写（bleak + httpx），首次运行时会请求蓝牙权限。

7. 开发与移植指南

7.1 移植到其他硬件

如果你想将项目移植到其他 ESP32 开发板，可以按照以下步骤操作：

1. 在 firmware/src/boards/ 下创建新目录

2. 实现硬件抽象层接口：

   • 显示驱动
   • 按钮 GPIO
   • 触摸输入
   • 其他外设

3. 创建 PlatformIO 环境配置：

   • 指定正确的开发板类型
   • 配置依赖项和编译选项

项目文档中提供了详细的移植指南（adding-a-board.md 和 hal-contract.md），建议先仔细阅读。

7.2 开发注意事项

在开发过程中需要注意以下几点：

1. 版权问题：

   • 项目使用了 Anthropic 的品牌字体和吉祥物素材
   • 二次开发时需要注意版权限制

2. 电源管理：

   • 优化睡眠模式以延长电池寿命
   • 合理设置屏幕刷新率

3. 蓝牙连接稳定性：

   • 实现自动重连机制
   • 处理连接中断的情况

8. 常见问题与解决方案

8.1 蓝牙连接问题

问题表现：设备无法连接或频繁断开

解决方案：

1. 检查蓝牙适配器兼容性
2. 确保系统蓝牙服务正常运行
3. 尝试重置设备蓝牙绑定
4. 调整守护进程的重试间隔

8.2 数据显示不更新

问题表现：屏幕信息长时间不变

排查步骤：

1. 检查守护进程是否运行
2. 查看系统日志中的错误信息
3. 验证 API 令牌有效性
4. 测试 BLE 通信是否正常

8.3 电池续航问题

问题表现：设备电量消耗过快

优化建议：

1. 降低屏幕亮度
2. 增加数据更新间隔
3. 优化固件睡眠策略
4. 检查是否有硬件短路

9. 项目意义与扩展思考

Clawdmeter 展示了一个有趣的趋势：随着 AI 工具深度融入开发工作流，专用的物理交互设备变得越来越有价值。这种"看一眼就知道"的体验，比不断切换窗口查看日志要自然得多。

这个项目也启发我们思考其他可能的硬件扩展：

1. 多服务监控：同时显示多个 AI 服务的用量
2. 团队协作版：显示团队共享配额的使用情况
3. 增强交互：加入旋钮、滑块等更多输入方式
4. 桌面集成：与其他开发工具联动

在实际使用中，我发现这种物理反馈设备确实能帮助开发者更好地管理 API 用量，避免意外超额。它的存在本身就是一种提醒，让你更自觉地规划使用策略。