# garmin-ble：Garmin 手表 GFDI 协议的 Python 客户端

> 一个 Python 库，通过 Garmin 手表专有的 GFDI V2 低功耗蓝牙协议与手表通信，无需 Garmin Connect、手机或云服务。它实现了握手、多链路路由、COBS 分帧、CRC16 校验和 protobuf 服务报文，可流式读取心率、HRV、血氧、压力、Body Battery 和加速度计等类型化数据，并提供模拟器和录制会话回放，便于在没有硬件时开发。致谢部分说明协议逻辑和 schema 源自 Gadgetbridge；另有一份公开的分析记录，展示作者如何依据带标注的录制数据解出加速度计载荷，而 Gadgetbridge 此前只记录其十六进制内容。

- 类型：案例
- 目标：协议
- 类别：独立重建案例
- 关联：独立重建项目
- 来源复核于：2026-10-20
- 收录于：2026-11-02
- 原始资源：<https://github.com/gwerneckp/garmin-ble>
- 一手来源：<https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/README.md>
- 目录页面：<https://awesomerea.org/zh/resources/garmin-ble-gfdi-protocol-case/>
- 记录 JSON：<https://awesomerea.org/resources/garmin-ble-gfdi-protocol-case/record.json>
- 英文版：[English](https://awesomerea.org/resources/garmin-ble-gfdi-protocol-case/index.md)

## 使用条件与局限

- 审阅基于 main 分支 2026-09-27 的提交 b662032，比 2026-08-01 发布的 v0.3.2 多四个提交，v0.3.2 也是 PyPI 上的最新版本；这些提交只增加了示例和一段发布视频。pyproject 将其标为 Alpha，CHANGELOG 提醒 1.0 之前的 API 可能变化。README 路线图显示 BLE 传输、实时遥测、Watch API、模拟器和回放已完成，protobuf 设置与设备状态仍在开发中，通知、媒体控制和 FIT/GPX 文件传输尚在计划中。
- 需要使用者自有的 Garmin 手表，以及电脑上的低功耗蓝牙适配器；README 提醒手表同一时间只允许一个 BLE 连接，因此须先断开与手机的连接。不使用 Garmin Connect、固件或 SDK，仓库中的数据文件是作者自己录制并标注的加速度计数据。README 未列出已测试的手表；内置模拟器配置模拟 fenix 7 和 Venu 3，CHANGELOG 指出 GFDI 没有能力查询，某项指标是否受支持只能在手表接受或拒绝相应服务时得知。
- 需要 Python 3.10+ 以及 bleak 和 protobuf，可从 PyPI 或源码安装；开发依赖另含 pytest、pytest-mock 和 pytest-asyncio。编译好的 protobuf 模块与对应的 .proto 源文件一同提交，大多数示例支持 --simulate。
- CI 在 Ubuntu 上用 Python 3.10–3.13 运行 pytest 测试套件。测试覆盖 COBS、CRC16、GFDI、MLR 和 Smart 分帧，以模拟对象测试基于 bleak 的传输，检查帧追踪、抓包文件与回放，并在模拟器上检查手表生命周期、protobuf 与遥测行为。rev_eng.md 记录了如何依据九组带标注的录制数据解出 17 字节的加速度计数据包。在真实手表上的表现仍属作者报告。
- 采用 AGPL-3.0-only，与 README 致谢的 Gadgetbridge 衍生代码一致，尽管 README 同时称其为净室实现。Garmin 手表、应用和商标仍归各自权利人所有。一条提交信息称倾斜游戏示例是对无人监督 vibe coding 的一次测试。

## 一手来源

1. <https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/README.md>
2. <https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/reverse_engineering/accelerometer/rev_eng.md>
3. <https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/CHANGELOG.md>
4. <https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/pyproject.toml>
5. <https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/.github/workflows/test.yml>
6. <https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/garmin_ble/protocol/gfdi.py>
7. <https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/garmin_ble/transport/simulated.py>
8. <https://github.com/gwerneckp/garmin-ble/tree/b66203232f0abb314aeb7dc9e448680184f28ed3/proto>
9. <https://github.com/gwerneckp/garmin-ble/tree/b66203232f0abb314aeb7dc9e448680184f28ed3/tests>
10. <https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/LICENSE>
11. <https://github.com/gwerneckp/garmin-ble/commit/69b6ed1cccfce79482fd13ca3fad292551b99a18>
12. <https://github.com/gwerneckp/garmin-ble/releases/tag/v0.3.2>
13. <https://pypi.org/project/garmin-ble/0.3.2/>

## 同分区更多条目：协议

- [bosectl：重建 Bose BMAP 耳机协议](https://awesomerea.org/zh/resources/bosectl-bose-bmap-protocol-case/index.md) · 案例
- [lib-osmo-ble：DJI Osmo Pocket 3 低功耗蓝牙协议库](https://awesomerea.org/zh/resources/osmo-pocket-3-ble-protocol-case/index.md) · 案例
- [DJI MIMO BLE 逆向素材：重建 DJI Osmo 控制协议](https://awesomerea.org/zh/resources/dji-mimo-ble-reveng-case/index.md) · 案例
- [Cat Printer BLE：重建 MXW01 热敏打印机协议](https://awesomerea.org/zh/resources/catprinterble-mxw01-printer-case/index.md) · 案例
- [a0rfid：A0 协议 UHF RFID 读写头的开源驱动](https://awesomerea.org/zh/resources/a0rfid-uhf-reader-protocol-case/index.md) · 案例
- [Xiaomi Kettle BLE protocol：重建智能电水壶的控制接口](https://awesomerea.org/zh/resources/xiaomi-kettle-ble-protocol-case/index.md) · 案例

## 关于此条目

说明已依据一手来源复核。
原创说明采用 MIT 许可；外部项目、论文与素材保留各自的权利和许可。