Repository navigation
Description
Reporter: nickywilks6405 (Discord) — feature originally requested by <@409347378949128203>
Type: Enhancement (feature request)
Repo: mobile — 9thlevelsoftware/project-phoenix-mp
Source: Discord #feature-requests, thread 1569464719817838833
Summary
Let users control a Phoenix workout from the physical buttons on a Garmin watch: start the set or move to the next one, and stop or cancel the current exercise.
Request details (proposed behavior)
• Start / Next: one press starts the current exercise. If one is already running, it moves to the next set or exercise.
• Stop / Cancel: one press stops the current set. A long press (or a confirm step) cancels the exercise, so it can't be ended by accident.
• optional: The watch shows a short status or haptic buzz so you know the press registered.
Possible approaches (reporter's suggestions only, not a spec):
- A Connect IQ companion watch app that sends button events to Phoenix through the Garmin Connect IQ Mobile SDK.
- Map the controls to the watch's existing media-control buttons (play/pause, next), if the app can listen for those.
Nice to have:
• Watch shows the current exercise, set number, and rest countdown.
• Haptic cue when rest ends.
• Let users choose which watch button does which action.
Expected behavior
The physical buttons on a Garmin watch can control a live Phoenix workout without touching the phone: one press starts the current exercise (or moves to the next set or exercise when one is already running), one press stops the current set, and a long press (or a confirm step) cancels the current exercise so it can't be ended by accident. Optionally the watch shows a short status or haptic buzz confirming the press registered.
Actual behavior (current state)
There are no watch controls today: starting the next set or stopping an exercise means walking over and tapping the phone. During a session your hands are on the handles or bar, and the phone is often out of reach or across the room. That breaks rest timing, slows transitions, and adds friction to every set.
Impact / Why it matters
Hands-free control is a quality-of-life gain for anyone training alone. It also fits naturally with the people already wearing a Garmin to track heart rate during sessions.
Attachments
No attachments recorded.
Original Discord Request (verbatim)
<@1502654170031849644>
**Feature Request: Garmin watch button controls for workouts**
Originally requested by <@409347378949128203>
**Summary**
Let users control a Phoenix workout from the physical buttons on a Garmin watch: start the set or move to the next one, and stop or cancel the current exercise.
**Problem**
During a session your hands are on the handles or bar, and the phone is often out of reach or across the room. Right now, starting the next set or stopping an exercise means walking over and tapping the phone. That breaks rest timing, slows transitions, and adds friction to every set.
**Proposed behavior**
• **Start / Next**: one press starts the current exercise. If one is already running, it moves to the next set or exercise.
• **Stop / Cancel**: one press stops the current set. A long press (or a confirm step) cancels the exercise, so you can't end it by accident.
• optional: The watch shows a short status or haptic buzz so you know the press registered.
**Possible approaches** (suggestions only, not a spec)
1. A Connect IQ companion watch app that sends button events to Phoenix through the Garmin Connect IQ Mobile SDK.
2. Map the controls to the watch's existing media-control buttons (play/pause, next), if the app can listen for those.
**Nice to have**
• Watch shows the current exercise, set number, and rest countdown.
• Haptic cue when rest ends.
• Let users choose which watch button does which action.
**Why it matters**
Hands-free control is a quality-of-life gain for anyone training alone. It also fits naturally with the people already wearing a Garmin to track heart rate during sessions.
Discord-Message-ID: 1569464719817838833
Activity
9thLevelSoftware commentedon Nov 9, 2026
Feasibility assessment — ACCEPT (phased)
Verdict: accept. Recommended path is a Connect IQ companion watch app (reporter's approach 1) plus phone-side command routing in this repo. The reporter's approach 2 (repurposing the watch's media-control buttons) is rejected: media keys route to the phone's active media player, so they would fight music playback during workouts (the exact time users need them), and they can't deliver status/haptic feedback.
Why it's feasible
ActiveSessionEngine:startWorkout(...),startNextSet()(advances set-or-exercise),stopAndReturnToSetReady(),stopAndSkipCurrentExercise(),stopWorkout(...)map directly to Start/Next and Stop/Cancel. The long-press/confirm cancel guard lives naturally in the watch UI.TvSessionControlleris the established pattern for a secondary surface orchestrating the shared core; aGarminSessionControllermirrors it, keeping validation/teardown in shared code.com.garmin.connectiq:ciq-companion-app-sdk) and iOS, so both phone platforms are coverable via KMP expect/actual.Key constraints / risks
Phasing
No scope overlap with the in-flight Garmin heart-rate work (#1359 / PR #1326) — that is inbound sensor telemetry; this is outbound session control.
Full assessment (assumptions + evidence) recorded in the enhancement pipeline artifacts. Next stage: architecture.
9thLevelSoftware commentedon Nov 9, 2026
Architecture designed — Garmin workout controls
The architecture stage is complete; this feature is not implemented or resolved. The selected approach is a Connect IQ watch app, explicitly opt-in phone association with one selected watch, and per-workout arming. Existing phone session ownership, safety and saving rules remain authoritative; no new backend or database contract is proposed.
startSetFromReady()(DefaultWorkoutSessionManager.kt:1008; TvSessionController.kt:120–128). Prepared standalone JustLift retains existing phone preparation andstartWorkout(skipCountdown=false,isJustLiftMode=true). During an active set, Next safely ends the current set, awaits successful saving/teardown and prepares the next; a separate press starts it. This needs a bounded shared coordination seam, not a trivial button-to-engine mapping.Next: integration modelling, phone/watch UI prototype, and escalated-model signoff before implementation; no human approval wait is being requested. No application builds, runtime tests or hardware tests were performed for this documentation stage.
Pipeline artifact (local, not a public download):
/Users/christopherwilloughby/.hermes/phoenix-enhancements/issue-1391-1569464719817838833/architecture.mdArtifact SHA-256:
9a508664781c457b12db894f18e808e787397ab149912d1439c8f18b0f3688f0· 3210 whitespace-delimited words. The two reviewed corrections are included in both acceptance gates and downstream checklist.9thLevelSoftware commentedon Nov 9, 2026
Integration model complete — Garmin workout controls
The architect-approved integration model is complete. This is a proposed integration contract, not an implemented or resolved feature.
skipCountdown=truepath throughstartSetFromReady(); standalone JustLift retainsskipCountdown=false. This corrects the architecture wording rather than introducing a remote countdown. Stop preserves existing partial-save/discard semantics; Cancel exercise requires confirmation.Next: source-based phone/watch prototype, then escalated-model signoff before implementation—no human approval wait. Physical Android/iOS/watch QA remains required; this stage provides no application build, runtime or hardware-test evidence.
Approved artifact SHA-256:
0486dcd6f111ae4286bcfee67682f894a9932bff0138967c57edcf4af01cf4d7.9thLevelSoftware commentedon Nov 9, 2026
Garmin controls prototype update (#1391): integration design is ready, but the native visual preview is blocked by the current-app capture tooling. An untouched current-main launch was refused before building: its required simulator fixture is absent, and the actual phone UI lives outside this stage’s permitted edit paths. No prototype screenshot or watch/trainer validation has been produced. The visual gate remains incomplete; implementation/signoff must not advance from this attempt. Next step is a supported current-main capture contract and corrected UI-path scope, then the phone/watch safety-state prototype. This is a tooling hold, not a request for reporter diagnostics or approval.
9thLevelSoftware commentedon Nov 13, 2026
Garmin controls prototype progress (#1391): the previous fixture-launcher/UI-path restriction has been superseded and the supported current PhoenixApp host now builds successfully for the iOS simulator. Native launch still stops at STARTUP_INITIALIZATION_FAILED before the proposed controls appear; the failed UI tests, startup screenshots and build logs are retained. These are not feature-preview images, and no Garmin/trainer behavior has been validated. The visual gate remains incomplete: no signoff or implementation advance from this attempt. Next is a startup-ready supported capture environment, then native phone/watch-design-preview frames and contextual review. No reporter diagnostics or human approval are requested.
9thLevelSoftware commentedon Nov 14, 2026
Garmin controls prototype update (#1391): bounded startup diagnosis now identifies the exact missing setup: the simulator app has no SUPABASE_URL in its Info.plist, so its normal SupabaseConfig dependency cannot initialize. Native builds succeed, but the app still stops before the proposed controls. The separate Keychain warning is not the established cause, so no Keychain fallback or startup bypass was applied. The cause chain, native failure screenshot and logs are retained; zero feature-preview frames are accepted. Next is a supported, normally configured capture build, then contextual phone/watch-design-preview captures and independent review. The visual gate remains incomplete; no Garmin/trainer compatibility, signoff or implementation advance is claimed. No reporter diagnostics or human approval are requested.
9thLevelSoftware commentedon Nov 14, 2026
Garmin controls prototype — recovered native previews, gate still incomplete
The supported simulator configuration now reaches ordinary app startup. We recovered the interrupted native capture run: 78 hash-verified checkpoints (76 presentation-only lab frames and 2 ordinary-app startup/return frames), including 21 deterministic design scenarios. This is a retained focused UI run, not a new full-suite or hardware test.
Actual phone placements — proposed controls, mock state
Watch design inside the phone app — NOT Garmin runtime
Settings recovery preview · Composite of native failure/stale/unknown design states
Still outstanding: real Set Ready and Active Workout contextual captures. The lab is not a substitute for those screens. Independent review also found stale footer feedback after a simulated save-completion transition; that feedback must be corrected and recaptured. Normal workout-entry/connection gates remain intact—no runtime repository substitution or safety bypass was used.
These are hardcoded presentation mocks. No Garmin connection, machine command, real saving, hardware compatibility or emergency-stop reliability is demonstrated. The prototype gate remains incomplete; signoff and implementation have not advanced. No reporter diagnostics or human approval are requested. Next: supported normal workout-context capture, the bounded feedback correction, and independent re-review.
9thLevelSoftware commentedon Nov 14, 2026
Garmin prototype progress — footer corrected; concrete simulator BLE blocker
The stale post-APPLIED footer is now corrected on the disposable capture branch. A fresh native simulator run passed the focused footer regression and ordinary connection observation probe (two selected tests, not a full suite). The corrected footer explicitly says simulation only, fresh press required, no autostart. Bounded independent source/visual review accepts that correction only.
The ordinary app connection action now produces Connection Failed: “This device doesn't support the Bluetooth low energy central or client role.” The inspected iOS platform module binds
KableBleRepository; simply having PhantomBleRepository in a simulator source set does not establish that the app uses it. No new repository/DI hook or connection/safety bypass was added. Supported initialization, real EULA acceptance, builds and capture work; those historical blockers are superseded.Prototype remains incomplete: real SetReady and ActiveWorkout context captures still need a supported prepared-workout connection path. This is presentation-only design work, not successful BLE/Garmin connection, real saving, hardware compatibility or safety validation. Signoff and implementation have not advanced. No reporter diagnostics or human approval requested; the concrete capture-binding discrepancy is returned to the pipeline coordinator.
9thLevelSoftware commentedon Nov 14, 2026
Garmin prototype progress — authorized Phantom path, source-graph constraint found
The capture-policy decision now authorizes a narrow, compile-time Phantom machine binding on the disposable simulator branch. The earlier permission discrepancy is superseded; the accepted simulated-save footer correction remains accepted.
Preflight found a separate source-graph constraint: the TV simulator module imports the entire iOS simulator Kotlin source directory. The prescribed new iOS simulator
actualfactory would therefore also enter TV compilation without its iOSexpectdeclaration. This is an inspected compile-graph incompatibility, not an observed compiler failure. No source changes or build were performed in this pass; the existing Phantom stays unchanged and initially Disconnected.The concrete request returned to the coordinator is a narrowly bounded source-root isolation adjustment for that new factory (or another named compatible arrangement), not a runtime override or startup/safety bypass. Prototype remains incomplete: actual Set Ready and Active Workout captures, runtime-resolved provider identity and ordinary scan/connect/workout transitions remain due. No signoff, implementation, Garmin/hardware compatibility or physical safety acceptance is claimed. No reporter action or diagnostics are needed.
9thLevelSoftware commentedon Nov 17, 2026
Garmin prototype — actual ActiveWorkout context captured (gate still incomplete)
A fresh run on the sanctioned simulator capture chain (ruling
t_62c3867a§A Phantom factory +t_0590e626§B ordinary-app capture) drove the real app through its ordinary UI: real EULA → ordinary header scan/connect (Connected) → Single Exercise → search "Bench Press" → Configure Exercise → Start Workout → actual ActiveWorkoutScreen. XCUITesttestPhantomPreparedWorkoutContextpassed; 13 checkpoints, all 1206×2622.Runtime repository identity, from the resolved Koin instance in a fresh process:
Capture BleRepository=PhantomBleRepository.Actual ActiveWorkoutScreen with the proposed strip at the top of the workout content (Set 1/3, calibration WARMUP 0/3, live simulated L/R cable bars, phone
STOPuntouched):Strip text:
PROPOSED GARMIN · Active / Rest / Summary · presentation only/No device connected · NOT armed (mock)/Arm preview (mock).Ordinary Configure Exercise sheet on the way in (no Garmin UI):
Still open — prototype gate NOT complete:
Evidence boundary: Phantom proves app-to-repository inputs and simulated telemetry only. It does not exercise Kable, protocol parsing, firmware, physical cables, Garmin Connect IQ or hardware. These are design frames only: nothing is implemented, and no save, persistence or safety behaviour has been accepted.
9thLevelSoftware commentedon Nov 17, 2026
Garmin prototype — actual SetReady context captured; prototype visual gate complete
The prototype was rebuilt on main (
7f232562) on a disposable, never-pushed capture branch: the recorded Phantom factory diff plus a new presentation-only SetReady strip. An XCUITest (testRoutineSetReadyContext, passed, 15 checkpoints, all 1206×2622) then drove the real app through its ordinary UI in the iOS Simulator: ordinary scan/connect to the Phantom simulated trainer (Connected) → Routines → create "Garmin Proto Upper" → add Barbell Bench Press → Save → Start Workout → START EXERCISE → actual SetReadyScreen.Runtime repository identity, from the resolved instance in this run:
Capture BleRepository=PhantomBleRepository.SetReady, watch not armed. The strip sits below the start-gate notice, directly above the unchanged phone Prev / START / Next / ✕ row:
SetReady, armed for this workout (mock). The copy explains the mapping: Watch Start = this START, Stop = phone stop.
Armed, body scrolled. The strip stays pinned with the action row:
Path context: Routine Overview before SetReady (https://github.com/9thLevelSoftware/Project-Phoenix-MP/releases/download/v1.1.0/issue1391-ctx2140-routine-overview.png). Phone START → actual ActiveWorkout (https://github.com/9thLevelSoftware/Project-Phoenix-MP/releases/download/v1.1.0/issue1391-ctx2140-phone-start-activeworkout.png). The ActiveWorkout strip placement is the earlier captured run-2117 frames.
Evidence boundary. These are simulator design frames, which the owner directive accepts as sufficient. Phantom proves app-to-repository inputs and simulated telemetry only. Nothing is implemented, and no Garmin Connect IQ, Kable/protocol, firmware, hardware, save, persistence or safety behaviour is claimed. The arm/disarm toggle is local mock state.
Next: escalated-model signoff on the prototype + architecture/integration model.
9thLevelSoftware commentedon Nov 17, 2026
Escalated design signoff — APPROVED for specification/development (Phase 1)
Reviewer: phoenix-rca / claude-opus-5-5. This is a reviewed design decision. It does not accept the implementation, release or merge.
Approved scope (Phase 1):
The on-watch exercise/set/rest dashboard and rest-end haptic (Phase 2) and button remapping (Phase 3) are deferred. Media-key control is rejected: it would take over music and can't give feedback.
I read feasibility, architecture, the integration model and the final prototype gate, and inspected the native SetReady/ActiveWorkout frames and the cancel-confirmation lab frame. No human feedback or reactions are recorded on this issue or the Discord thread, so this gate is the decision.
Decisions on the escalated items
startSetFromReady()→startWorkout(skipCountdown=true), re-verified onmainf6bf1712. No new remote countdown is added. Standalone Just Lift keepsskipCountdown=false.APPLIEDonly after a typed receipt from the commit path itself shows persistenceSUCCEEDED/NOT_REQUIREDand teardown Ready. Showing SetSummary is not proof that the set was saved. A save still pending after 5 s reportsUNKNOWN_RESULT, and a failed save reportsSAVE_FAILED. Both block the next watch Start.sourceApplicationis nil for apps from another team, so it cannot be relied on. A Garmin device-selection callback is accepted only on the dedicated scheme (separate from OAuth), only when it matches an outstanding phone-initiated, single-use and short-lived request, and only when the devices are confirmed through the SDK. Unsolicited callbacks are rejected.Binding corrections (full text in
signoff.md)main: the HR card is nowHrmSensorSettingsCard. Garmin controls stay separate from Garmin HR, and all line citations must be re-derived.Not an emergency stop. The phone and trainer safe stop remain authoritative.
Decision record:
signoff.mdin the enhancement artifacts. Next: implementation specification via the enhancement bridge.9thLevelSoftware commentedon Nov 17, 2026
Implementation plan — Phase 1 (spec complete)
The FE/BE implementation spec for Garmin watch button controls is complete, governed by the approved signoff's binding corrections (simulator-evidence gates,
backgroundStopSupported=false, CIQ-device-definition allowlist,HrmSensorSettingsCardrebase, default-off phone side, Phases 2/3 deferred). Citations were re-derived at the implementation basemain@f6bf1712.Bounded packets
endCurrentSetAndPrepareNext(expectedExecutionIdentity)on the existing phone-owned session manager, returning a typed receipt (persistenceNOT_REQUIRED|PENDING|SUCCEEDED|FAILED, teardown, terminal state).APPLIEDis only reported on aSUCCEEDED/NOT_REQUIREDcommit-path receipt;SetSummarypublication is not proof. Characterization tests first (routine /temp_single_*/ JustLift × zero/partial/full reps, warmup, timed/bodyweight, manual/autoplay).GarminSessionController+ frozen v1HELLO/STATE/COMMAND/RESULTdictionaries with the provisional limits (2048 B / 24 keys / 3 s grant / 10 s confirmation / 5 s result / 256-id dedupe cap, monotonic clock), epoch/grant/confirmation lifecycle, fail-closed validation, urgent Stop pre-emption of pending starts.GarminControlsSettingsCardnext to the HRM sensor card (controls copy strictly separate from heart-rate copy), plus the SetReady/Active Arm strip; strip must not cover the STOP button, rep counter or weight readout at the largest accessibility text size; localizedPhoenixThemestrings only.-ObjC, dedicated callback scheme (OAuth untouched); device-selection callback accepted only when solicited, single-use and SDK-confirmed (sourceApplicationadvisory only).garmin/Monkey C app + CI: START/ENTER→Start/Next, BACK/LAP→urgent Stop, DOWN→Cancel confirm (second press confirms), UP→dismiss, no long-hold destructive; mandatory text feedback, haptic only afterAPPLIED.Acceptance highlights: routine watch Start == phone START (
skipCountdown=true), JustLift keepsfalse; Stop mirrors phone Stop Set; Cancel skips only the named exercise; no autostart/queued starts survive Stop; logout/profile/restart/disarm revoke authority; HRM card and session HR untouched; feature ships default-off behind matched watch-app detection.Non-goals: Phase 2/3, portal/backend/DB/sync/analytics, background start, watch-side routine/weight editing, media-key mapping, emergency-stop claims.
Full spec and user instructions/release-note draft are stored with the enhancement artifacts. Next: development + PR per the packets above.
9thLevelSoftware commentedon Nov 17, 2026
Implementation update (Phase 1 MVP) — PR #1407
The signed-off Phase 1 enhancement is implemented and open for review: #1407 (
feat/1391-garmin-watch-controls@64e8c084onmainf6bf1712).Landed: shared
endCurrentSetAndPrepareNextseam with typed commit-path receipts; frozen v1 wire codec (GarminProtocol) mirroring the Monkey C watch codec; fullGarminSessionController(per-workout arming with fresh epochs, 3 s grants, 10 s confirmation binding, fail-closed dedupe 256/epoch with cap disarm/rekey, serialized admission with urgent Stop pre-emption, ACCEPTED/APPLIED/REJECTED receipts, UNKNOWN_RESULT/SAVE_FAILED start-blocks, authority invalidation); phone UI settings card + Arm strip (default-OFF release boundary); Android/iOS Connect IQ transports + tvOS no-op;garmin/watch app + CI workflow; regressions.Verification so far: 43/43 protocol/controller tests pass (fake monotonic clock, no sleeps). Known not green at this head and recorded in the PR body for triage:
ManualStopProfileAttributionTest2,JustLiftCompletionBehaviorTest2,Issue1366JustLiftExitNavigationTest12 (untouched by this PR; suspected pre-existing/flaky).Final in-app visual QA evidence is in progress and will be posted here and on the PR; the merge gate should hold until it exists. Not resolved yet.
fix(garmin): PR #1407 follow-up — CI fixes for the #1391 Phase 1 branch