{
  "added_at": "2026-11-02",
  "additional_evidence_urls": [
    "https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/reverse_engineering/accelerometer/rev_eng.md",
    "https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/CHANGELOG.md",
    "https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/pyproject.toml",
    "https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/.github/workflows/test.yml",
    "https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/garmin_ble/protocol/gfdi.py",
    "https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/garmin_ble/transport/simulated.py",
    "https://github.com/gwerneckp/garmin-ble/tree/b66203232f0abb314aeb7dc9e448680184f28ed3/proto",
    "https://github.com/gwerneckp/garmin-ble/tree/b66203232f0abb314aeb7dc9e448680184f28ed3/tests",
    "https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/LICENSE",
    "https://github.com/gwerneckp/garmin-ble/commit/69b6ed1cccfce79482fd13ca3fad292551b99a18",
    "https://github.com/gwerneckp/garmin-ble/releases/tag/v0.3.2",
    "https://pypi.org/project/garmin-ble/0.3.2/"
  ],
  "category": "reconstruction-cases",
  "description_en": "Python library that talks to Garmin watches over their proprietary GFDI V2 Bluetooth LE protocol, with no Garmin Connect, phone or cloud service. It implements the handshake, multi-link routing, COBS framing, CRC16 checks and protobuf service messages, streams typed readings such as heart rate, HRV, SpO2, stress, Body Battery and accelerometer data, and adds a simulator and recorded-session replay for work without hardware. Its acknowledgements credit Gadgetbridge for the protocol logic and schemas, while a published journal shows how the author decoded the accelerometer payload, which Gadgetbridge only logged, from labelled recordings.",
  "description_zh": "一个 Python 库，通过 Garmin 手表专有的 GFDI V2 低功耗蓝牙协议与手表通信，无需 Garmin Connect、手机或云服务。它实现了握手、多链路路由、COBS 分帧、CRC16 校验和 protobuf 服务报文，可流式读取心率、HRV、血氧、压力、Body Battery 和加速度计等类型化数据，并提供模拟器和录制会话回放，便于在没有硬件时开发。致谢部分说明协议逻辑和 schema 源自 Gadgetbridge；另有一份公开的分析记录，展示作者如何依据带标注的录制数据解出加速度计载荷，而 Gadgetbridge 此前只记录其十六进制内容。",
  "entry_url": "https://awesomerea.org/resources/garmin-ble-gfdi-protocol-case/",
  "entry_url_zh": "https://awesomerea.org/zh/resources/garmin-ble-gfdi-protocol-case/",
  "evidence_url": "https://github.com/gwerneckp/garmin-ble/blob/b66203232f0abb314aeb7dc9e448680184f28ed3/README.md",
  "group": "cases",
  "id": "garmin-ble-gfdi-protocol-case",
  "json_url": "https://awesomerea.org/resources/garmin-ble-gfdi-protocol-case/record.json",
  "kind": "case-study",
  "markdown_url": "https://awesomerea.org/resources/garmin-ble-gfdi-protocol-case/index.md",
  "markdown_url_zh": "https://awesomerea.org/zh/resources/garmin-ble-gfdi-protocol-case/index.md",
  "name": "garmin-ble: a Python client for Garmin's GFDI watch protocol",
  "name_zh": "garmin-ble：Garmin 手表 GFDI 协议的 Python 客户端",
  "record_type": "resource",
  "relationship": "independent-reconstruction",
  "requirements": [
    "Reviewed at main commit b662032 (2026-09-27), four commits after v0.3.2 of 2026-08-01, which is also the latest PyPI release; those commits add examples and an announcement video. pyproject marks the package Alpha and the CHANGELOG warns that the pre-1.0 API may change. The README roadmap lists BLE transport, live telemetry, the Watch API, simulator and replay as done, protobuf settings and device state as in progress, and notifications, media control and FIT/GPX file transfers as planned.",
    "Requires the user's own Garmin watch and a Bluetooth LE adapter on the computer; the README warns that the watch allows one BLE connection at a time, so it must be disconnected from the phone first. No Garmin Connect, firmware or SDK is used, and the repository's data files are the author's labelled accelerometer recordings. The README gives no list of tested watches; the bundled simulator profiles model a fenix 7 and a Venu 3, and the CHANGELOG notes that GFDI has no capability query, so a metric's support shows only when the watch accepts or declines its service.",
    "Python 3.10+ with bleak and protobuf, installed from PyPI or from source; development extras add pytest, pytest-mock and pytest-asyncio. Compiled protobuf modules are committed next to their .proto sources, and most examples accept --simulate.",
    "CI runs the pytest suite on Ubuntu with Python 3.10–3.13. Tests cover COBS, CRC16, GFDI, MLR and Smart framing, the bleak-backed transport with mocks, frame tracing, capture files and replay, and watch lifecycle, protobuf and telemetry behavior against the simulator. rev_eng.md documents how the 17-byte accelerometer packet was decoded from nine labelled recordings. Behavior on real watches remains author-reported.",
    "AGPL-3.0-only, matching the Gadgetbridge-derived code the README acknowledges, although the README also calls the library clean-room. Garmin watches, apps and trademarks keep their own rights. One commit message calls the tilt game example a test of unsupervised vibe coding."
  ],
  "requirements_zh": [
    "审阅基于 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 的一次测试。"
  ],
  "targets": [
    "protocol"
  ],
  "url": "https://github.com/gwerneckp/garmin-ble",
  "verification": "source-reviewed",
  "verified_at": "2026-10-20"
}