[BW-GARMIN-01] Add Garmin fēnix 8 BookWave companion controls #28

Open
opened 2026-09-18 08:46:59 +02:00 by alexander · 0 comments
Owner

Migrated from GitHub issue #119. Forgejo issue: #28. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links.

Classification

Planned cross-device integration. Blocked on #23. No watch-side audiobook download in v1.

Product intent

Support a Garmin fēnix 8 as a lightweight BookWave remote and information surface for playback on the Android phone.

Target experience:

  • current book, chapter and useful progress/remaining information;
  • Play/Pause;
  • Skip forward/back;
  • optional series/sequence detail;
  • commands act on BookWave running on the phone.

Important baseline first

The fēnix 8 already provides Garmin's built-in Control Phone media mode. Before writing a custom Connect IQ companion, test BookWave's existing Android MediaSession through that surface.

Stage 0 — built-in Garmin media-control acceptance

Verify on a real fēnix 8:

  • BookWave appears/controls correctly through Control Phone;
  • Play/Pause works;
  • skip forward/back maps sensibly for an audiobook;
  • what metadata Garmin actually renders from BookWave's MediaSession;
  • behavior while phone is locked/screen off;
  • reconnect after watch/phone disconnect.

If built-in Control Phone already satisfies the desired controls, keep it. Do not build a custom watch app merely to recreate Garmin's buttons.

Proceed to the custom companion because BookWave-specific audiobook information or actions are missing — especially chapter, book progress, series/sequence, explicit Continue, or future sleep controls.

Feasibility for custom companion

Garmin Connect IQ supports phone-app messaging over BLE and lists fēnix 8 models among supported devices. Garmin also provides a Connect IQ Mobile SDK for Android; wireless companion communication routes through Garmin Connect Mobile.

That makes a phone companion architecture the recommended custom implementation rather than an Audio Content Provider that downloads audiobook files to the watch.

Architecture if Stage 0 is insufficient

Android BookWave app:

  • small Garmin companion adapter using Garmin Connect IQ Mobile SDK;
  • projects a privacy-safe GarminPlaybackSnapshot from existing BookWave state;
  • receives a tiny allowlisted command protocol and dispatches it through #23;
  • no direct ExoPlayer ownership in Garmin code.

Garmin Connect IQ app/glance:

  • receives current playback snapshot;
  • renders book/chapter/progress information appropriate to fēnix 8 display constraints;
  • sends Play/Pause/Skip Forward/Skip Back/Continue commands;
  • degrades gracefully when phone/BookWave/Garmin Connect is unavailable.

V1 information model

Where profile/privacy permits:

  • book title;
  • author;
  • chapter title;
  • chapter elapsed/remaining or book progress;
  • play/pause state;
  • optional series + sequence on detail screen.

Do not continuously stream second-by-second position over BLE. Send meaningful snapshots and let the watch interpolate/display coarse progress where appropriate.

V1 controls

  • Continue/Play;
  • Pause;
  • Skip forward;
  • Skip backward.

Possible later controls:

  • next/previous chapter;
  • sleep timer start/cancel;
  • audio output action if it proves useful and safe.

Explicitly out of scope

  • No audiobook/media download to the Garmin in v1.
  • No independent Audiobookshelf authentication from the watch.
  • No watch-owned progress/resume state.
  • No direct server connection required from the watch.
  • No generic Garmin device matrix initially; fēnix 8 is the acceptance target, then compatibility can broaden from evidence.

Dependencies

  • Stage 0 built-in Control Phone test can happen as soon as the current MediaSession build is device-testable.
  • Custom companion implementation depends on #23 BW-SYS-01 action contract.
  • #24/GitHub #93 indirectly own Continue/resume correctness.

Storage / migration

No Android database migration expected. Garmin-side preferences may store only presentation/configuration state. Playback truth stays on the phone.

Privacy / security

  • Pair/communicate only through the installed Garmin Connect/Connect IQ app relationship.
  • Command protocol is an allowlist; no arbitrary intents/URLs/IDs.
  • If active profile is locked, a custom companion must switch to a generic BookWave — profile locked state and stop receiving title/chapter metadata.
  • Never send credentials/server URLs to the watch.

Automated tests

Android custom adapter:

  • snapshot projection;
  • locked-profile redaction;
  • command -> #23 action mapping;
  • stale/out-of-order message handling;
  • unavailable Garmin service does not affect playback.

Connect IQ custom app:

  • message parsing;
  • disconnected state;
  • key/touch control mapping;
  • glance/detail rendering with long titles;
  • no metadata shown after lock-redaction message.

Device acceptance

Required on a real fēnix 8 + Android phone:

  1. Stage 0 Control Phone baseline.
  2. If custom companion is needed: Garmin Connect installed, connect/disconnect, screen off/phone locked, Play/Pause and skip latency, current book/chapter updates, process death/relaunch, profile lock/switch, out-of-range reconnect.

Estimated effort

Stage 0: Small test.
Custom companion: Medium-Large because it introduces a second SDK/runtime and watch app.

Risk

Stage 0: Low.
Custom companion: Medium. Main risks are BLE/message lifecycle, Garmin Connect dependency and stale private metadata.

Sequence

Run Stage 0 early. Build custom companion after #23 only for the gaps the built-in Garmin surface cannot satisfy.

Acceptance criteria

  • We record exactly what fēnix 8 Control Phone already gives BookWave.
  • If it is sufficient for basic controls, BookWave does not duplicate them unnecessarily.
  • If a custom companion is built, it adds useful audiobook-specific information/actions.
  • All custom commands delegate to existing BookWave owners.
  • Locked/profile-switch state cannot leave old metadata visible.
  • Disconnect/reconnect is safe and requires no playback restart.
> Migrated from [GitHub issue #119](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/119). Forgejo issue: #28. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links. ## Classification Planned cross-device integration. Blocked on #23. No watch-side audiobook download in v1. ## Product intent Support a Garmin fēnix 8 as a lightweight BookWave remote and information surface for playback on the Android phone. Target experience: - current book, chapter and useful progress/remaining information; - Play/Pause; - Skip forward/back; - optional series/sequence detail; - commands act on BookWave running on the phone. ## Important baseline first The fēnix 8 already provides Garmin's built-in **Control Phone** media mode. Before writing a custom Connect IQ companion, test BookWave's existing Android `MediaSession` through that surface. ### Stage 0 — built-in Garmin media-control acceptance Verify on a real fēnix 8: - BookWave appears/controls correctly through `Control Phone`; - Play/Pause works; - skip forward/back maps sensibly for an audiobook; - what metadata Garmin actually renders from BookWave's MediaSession; - behavior while phone is locked/screen off; - reconnect after watch/phone disconnect. If built-in Control Phone already satisfies the desired controls, keep it. **Do not build a custom watch app merely to recreate Garmin's buttons.** Proceed to the custom companion because BookWave-specific audiobook information or actions are missing — especially chapter, book progress, series/sequence, explicit Continue, or future sleep controls. ## Feasibility for custom companion Garmin Connect IQ supports phone-app messaging over BLE and lists fēnix 8 models among supported devices. Garmin also provides a Connect IQ Mobile SDK for Android; wireless companion communication routes through Garmin Connect Mobile. That makes a **phone companion architecture** the recommended custom implementation rather than an Audio Content Provider that downloads audiobook files to the watch. ## Architecture if Stage 0 is insufficient Android BookWave app: - small Garmin companion adapter using Garmin Connect IQ Mobile SDK; - projects a privacy-safe `GarminPlaybackSnapshot` from existing BookWave state; - receives a tiny allowlisted command protocol and dispatches it through #23; - no direct ExoPlayer ownership in Garmin code. Garmin Connect IQ app/glance: - receives current playback snapshot; - renders book/chapter/progress information appropriate to fēnix 8 display constraints; - sends Play/Pause/Skip Forward/Skip Back/Continue commands; - degrades gracefully when phone/BookWave/Garmin Connect is unavailable. ## V1 information model Where profile/privacy permits: - book title; - author; - chapter title; - chapter elapsed/remaining or book progress; - play/pause state; - optional series + sequence on detail screen. Do not continuously stream second-by-second position over BLE. Send meaningful snapshots and let the watch interpolate/display coarse progress where appropriate. ## V1 controls - Continue/Play; - Pause; - Skip forward; - Skip backward. Possible later controls: - next/previous chapter; - sleep timer start/cancel; - audio output action if it proves useful and safe. ## Explicitly out of scope - No audiobook/media download to the Garmin in v1. - No independent Audiobookshelf authentication from the watch. - No watch-owned progress/resume state. - No direct server connection required from the watch. - No generic Garmin device matrix initially; fēnix 8 is the acceptance target, then compatibility can broaden from evidence. ## Dependencies - Stage 0 built-in Control Phone test can happen as soon as the current MediaSession build is device-testable. - Custom companion implementation depends on #23 BW-SYS-01 action contract. - #24/[GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) indirectly own Continue/resume correctness. ## Storage / migration No Android database migration expected. Garmin-side preferences may store only presentation/configuration state. Playback truth stays on the phone. ## Privacy / security - Pair/communicate only through the installed Garmin Connect/Connect IQ app relationship. - Command protocol is an allowlist; no arbitrary intents/URLs/IDs. - If active profile is locked, a custom companion must switch to a generic `BookWave — profile locked` state and stop receiving title/chapter metadata. - Never send credentials/server URLs to the watch. ## Automated tests Android custom adapter: - snapshot projection; - locked-profile redaction; - command -> #23 action mapping; - stale/out-of-order message handling; - unavailable Garmin service does not affect playback. Connect IQ custom app: - message parsing; - disconnected state; - key/touch control mapping; - glance/detail rendering with long titles; - no metadata shown after lock-redaction message. ## Device acceptance Required on a real fēnix 8 + Android phone: 1. Stage 0 Control Phone baseline. 2. If custom companion is needed: Garmin Connect installed, connect/disconnect, screen off/phone locked, Play/Pause and skip latency, current book/chapter updates, process death/relaunch, profile lock/switch, out-of-range reconnect. ## Estimated effort Stage 0: Small test. Custom companion: Medium-Large because it introduces a second SDK/runtime and watch app. ## Risk Stage 0: Low. Custom companion: Medium. Main risks are BLE/message lifecycle, Garmin Connect dependency and stale private metadata. ## Sequence Run Stage 0 early. Build custom companion after #23 only for the gaps the built-in Garmin surface cannot satisfy. ## Acceptance criteria - We record exactly what fēnix 8 `Control Phone` already gives BookWave. - If it is sufficient for basic controls, BookWave does not duplicate them unnecessarily. - If a custom companion is built, it adds useful audiobook-specific information/actions. - All custom commands delegate to existing BookWave owners. - Locked/profile-switch state cannot leave old metadata visible. - Disconnect/reconnect is safe and requires no playback restart.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#28
No description provided.