# WristBeam: reconstructing Garmin’s watch protocol for a Mac companion

> 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.

- Type: Case study
- Targets: App · Protocol
- Category: Independent reconstruction cases
- Relationship: Independent reconstruction project
- Sources reviewed: 2026-10-19
- Added to the catalog: 2026-10-27
- Original resource: <https://github.com/kongdayan/wristbeam>
- Primary source: <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/README.md>
- Catalog page: <https://awesomerea.org/resources/wristbeam-garmin-watch-protocol-case/>
- Record JSON: <https://awesomerea.org/resources/wristbeam-garmin-watch-protocol-case/record.json>
- Chinese version: [简体中文](https://awesomerea.org/zh/resources/wristbeam-garmin-watch-protocol-case/index.md)

## Requirements & limits

- 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.

## Primary sources

1. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/README.md>
2. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDISession.swift>
3. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDICodec.swift>
4. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDIFiles.swift>
5. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDIBattery.swift>
6. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDICoreIdentity.swift>
7. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/docs/DEVICES.md>
8. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/VERIFICATION.md>
9. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/docs/developer/API.md>
10. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/docs/developer/WATCH-REQUESTS.md>
11. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/CONTRIBUTING.md>
12. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Package.swift>
13. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/VERSION>
14. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/CHANGELOG.md>
15. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/LICENSE>

## More in Apps

- [usque: an open reimplementation of Cloudflare WARP’s MASQUE mode](https://awesomerea.org/resources/usque-warp-masque-client-case/index.md) · Case study
- [Webamp: a browser reimplementation of Winamp 2](https://awesomerea.org/resources/webamp-winamp-reimplementation-case/index.md) · Case study
- [NOOP: an offline WHOOP strap client built from Bluetooth protocol research](https://awesomerea.org/resources/noop-whoop-ble-client-case/index.md) · Case study
- [NiimBlue: an independent web client for NIIMBOT label printers](https://awesomerea.org/resources/niimblue-niimbot-printer-client-case/index.md) · Case study
- [open_oura: a cloud-free Oura Ring client built on its reverse-engineered BLE protocol](https://awesomerea.org/resources/open-oura-ring-protocol-case/index.md) · Case study
- [Sony Headphones Client: a desktop client for Sony’s headset control protocol](https://awesomerea.org/resources/sony-headphones-client-case/index.md) · Case study

## About this entry

The description was reviewed against primary sources.
Original editorial content: MIT. Linked projects, papers and assets retain their own rights and licenses.