AwesomeREA.org

Case study

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.

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; this review read the sources and did not run the app or a watch.
  • 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. The reviewed sources establish no AI or REA attribution for building the app.

About this entry

Type
Case study
Category
Independent reconstruction cases
Relationship
Independent reconstruction project
Targets
App · Protocol

Sources reviewed

The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.

Report an outdated entry Suggest a translation fix

Primary sources

  1. README.md GitHub · kongdayan/wristbeam · Revision 712f577
  2. Sources/GarminBar/Protocol/GFDISession.swift GitHub · kongdayan/wristbeam · Revision 712f577
  3. Sources/GarminBar/Protocol/GFDICodec.swift GitHub · kongdayan/wristbeam · Revision 712f577
  4. Sources/GarminBar/Protocol/GFDIFiles.swift GitHub · kongdayan/wristbeam · Revision 712f577
  5. Sources/GarminBar/Protocol/GFDIBattery.swift GitHub · kongdayan/wristbeam · Revision 712f577
  6. Sources/GarminBar/Protocol/GFDICoreIdentity.swift GitHub · kongdayan/wristbeam · Revision 712f577
  7. docs/DEVICES.md GitHub · kongdayan/wristbeam · Revision 712f577
  8. VERIFICATION.md GitHub · kongdayan/wristbeam · Revision 712f577
  9. docs/developer/API.md GitHub · kongdayan/wristbeam · Revision 712f577
  10. docs/developer/WATCH-REQUESTS.md GitHub · kongdayan/wristbeam · Revision 712f577
  11. CONTRIBUTING.md GitHub · kongdayan/wristbeam · Revision 712f577
  12. Package.swift GitHub · kongdayan/wristbeam · Revision 712f577
  13. VERSION GitHub · kongdayan/wristbeam · Revision 712f577
  14. CHANGELOG.md GitHub · kongdayan/wristbeam · Revision 712f577
  15. LICENSE GitHub · kongdayan/wristbeam · Revision 712f577

More in Apps

All 86 entries in AppsApps case studies (37)