{ "added_at": "2026-10-27", "additional_evidence_urls": [ "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDISession.swift", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDICodec.swift", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDIFiles.swift", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDIBattery.swift", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDICoreIdentity.swift", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/docs/DEVICES.md", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/VERIFICATION.md", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/docs/developer/API.md", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/docs/developer/WATCH-REQUESTS.md", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/CONTRIBUTING.md", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Package.swift", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/VERSION", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/CHANGELOG.md", "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/LICENSE" ], "category": "reconstruction-cases", "description_en": "Implements a Garmin watch companion as a native macOS menu-bar app that pairs over Bluetooth, receives live health notifications and original FIT files, and can upload them to Garmin Connect. Source comments attribute its GFDI framing, handshake, file-transfer and status fields to analysis of a supplied Garmin Android package, cross-checked against community implementations such as Gadgetbridge. Device verification covers one watch model, and the opt-in MCP and HTTP interfaces expose only locally cached data.", "description_zh": "以原生 macOS 菜单栏应用实现佳明手表的配套客户端：通过蓝牙配对，接收实时健康通知和原始 FIT 文件，并可上传至 Garmin Connect。源码注释称，GFDI 分帧、握手、文件传输和状态字段依据对一个自备佳明 Android 安装包的分析实现，并与 Gadgetbridge 等社区实现相互核对。设备验证仅涵盖一款手表；可选启用的 MCP 与 HTTP 接口只提供本地缓存的数据。", "entry_url": "https://awesomerea.org/resources/wristbeam-garmin-watch-protocol-case/", "entry_url_zh": "https://awesomerea.org/zh/resources/wristbeam-garmin-watch-protocol-case/", "evidence_url": "https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/README.md", "group": "cases", "id": "wristbeam-garmin-watch-protocol-case", "json_url": "https://awesomerea.org/resources/wristbeam-garmin-watch-protocol-case/record.json", "kind": "case-study", "markdown_url": "https://awesomerea.org/resources/wristbeam-garmin-watch-protocol-case/index.md", "markdown_url_zh": "https://awesomerea.org/zh/resources/wristbeam-garmin-watch-protocol-case/index.md", "name": "WristBeam: reconstructing Garmin’s watch protocol for a Mac companion", "name_zh": "WristBeam：为 Mac 配套应用重建佳明手表协议", "record_type": "resource", "relationship": "independent-reconstruction", "requirements": [ "Reviewed at VERSION 0.3.7 plus unreleased changes. It needs macOS 13+, a Garmin watch prepared with heart-rate broadcast off, and, for cloud features, a Garmin China or Global account signed in through Garmin’s own page; a local mode pauses all Garmin cloud access. Application-level encryption, native MLR/CoreTransfer and desktop widgets are unsupported, and a sleeping Mac cannot sync.", "Protocol source comments describe an independent Swift implementation of GFDI framing (COBS, CRC-16), multilink registration, device information, file directories and transfers, battery status and account-identity fields, each tied to named classes of a supplied Garmin Android package. Gadgetbridge, garmin-bridge and garmin-ble are cited as corroborating wire observations that were consulted, not ported. The reviewed tree contains no APK or decompiled listing; cloud history uses Connect client endpoints that the developer guide says are not a published Garmin API contract.", "Building needs macOS 13+, Swift 5.9+ and Command Line Tools; native swift test and CodeQL analysis need full Xcode, which CI supplies. CONTRIBUTING lists lint, localization, secret-scan, release-pipeline and core regression scripts. Release packages are ad hoc signed and not Apple notarized.", "The device matrix marks pairing, fresh notifications, original FIT download, China upload and daily charts verified only for an Instinct 2 Solar on 2026-10-13, with firmware unrecorded. Other Instinct, fēnix, epix, Forerunner, Venu and vívoactive models and real Global uploads remain unverified. VERIFICATION.md records regression counts run through Command Line Tools rather than full XCTest.", "MIT covers the project, which says it is not affiliated with Garmin; Garmin services, the Android package, watch firmware and health data keep their own terms. MCP, the HTTP/HTTPS API and webhooks are off until enabled." ], "requirements_zh": [ "审阅版本为 VERSION 0.3.7 及未发布的改动。需要 macOS 13+、已关闭心率广播的佳明手表；使用云端功能时，还需通过佳明官方页面登录佳明中国或国际账号。本地模式会暂停所有佳明云端访问。不支持应用层加密、原生 MLR／CoreTransfer 和桌面小组件，Mac 休眠时无法同步。", "协议源码注释称，GFDI 分帧（COBS、CRC-16）、多链路注册、设备信息、文件目录与传输、电池状态及账号身份字段均以 Swift 独立实现，并逐项对应自备佳明 Android 安装包中的具名类。Gadgetbridge、garmin-bridge 和 garmin-ble 被列为相互印证的线上协议观察资料，仅作参考而未移植。所审阅文件树不含 APK 或反编译清单；云端历史数据使用 Connect 客户端接口，开发者指南说明这些接口并非佳明公开的 API 约定。", "构建需要 macOS 13+、Swift 5.9+ 和 Command Line Tools；原生 swift test 及 CodeQL 分析需要完整 Xcode，由 CI 提供。CONTRIBUTING 列出了代码检查、本地化、密钥扫描、发布流水线及核心回归脚本。发布包为临时（ad hoc）签名，未经 Apple 公证。", "设备矩阵仅将 Instinct 2 Solar 于 2026-10-13 的配对、实时通知、原始 FIT 下载、中国区上传和每日图表标为已验证，且未记录固件版本。其他 Instinct、fēnix、epix、Forerunner、Venu 和 vívoactive 型号以及国际区的实际上传仍未验证。VERIFICATION.md 记录的回归数量通过 Command Line Tools 运行，而非完整 XCTest。", "MIT 覆盖项目本身，项目声明与佳明无关联；佳明服务、Android 安装包、手表固件和健康数据保留各自条款。MCP、HTTP／HTTPS API 和 Webhook 在启用前均为关闭状态。" ], "targets": [ "app", "protocol" ], "url": "https://github.com/kongdayan/wristbeam", "verification": "source-reviewed", "verified_at": "2026-10-19" }