Skip to content

feat: Keep Android rides running in the background with live notification controls - #120

Open
ThoreKoritzius wants to merge 17 commits into
mainfrom
codex/android-background-riding
Open

ThoreKoritzius wants to merge 17 commits into
mainfrom
codex/android-background-riding

Conversation

@ThoreKoritzius

@ThoreKoritzius ThoreKoritzius commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Why

Switching apps or locking the phone during an indoor ride must not leave trainer control, telemetry and recording dependent on WebView rendering. This adds Android background riding, live notification controls and clearer Bluetooth connection help.

Follows the merged #118 and targets main. Android version code stays 3, since that release is not published yet.

Changes

  • Run active trainer rides in an Android connected-device foreground service, with native Bluetooth subscriptions, a WebSocket, a telemetry clock and a ride-scoped wake lock. Reconnect using the existing rider session and restore sensor subscriptions.
  • Keep trainer resistance, selected gear, workout timing and scheduled class changes working in the background. Preserve drafting savings for native virtual gears, with shared web/native parity fixtures. Reconcile elapsed time and recorded samples before the foreground UI resumes.
  • Show the OpenRadlr icon, watts, distance and a minutes/seconds clock in the collapsed notification. The expanded card adds cadence and route/workout progress, with Return to ride and End & save actions.
  • Persist samples in an app-private journal for unfinished-ride recovery. End/save preserves the recording, leaves the session and releases trainer resistance. Stale sensor readings are not replayed as fresh power.
  • Explain Bluetooth adapter, permission and connection failures, with Android settings shortcuts and English/German text.
  • Add native unit/instrumentation coverage, Android CI checks and architecture/testing documentation. Fix CI's missing sdkmanager setup using the runner's SDK, within the repository action policy.
  • Add an opt-in bundled-client debug APK for testing this branch against production without a local server or USB forwarding. Release bundles retain the server-delivered client.
  • Bind browser timers to the global receiver, fixing a real-device WebView error when starting or finishing a native ride.

Screenshots

Collapsed and expanded notification, captured on the Android emulator with synthetic trainer input:

Collapsed OpenRadlr ride notification with live stats and elapsed time Expanded OpenRadlr ride notification with progress and ride actions

Validation

  • make check passes locally, including 1,837 client tests and the Rust suites.
  • Android JVM tests, lintDebug, APK and release bundle builds pass locally.
  • Emulator instrumentation passes again after review fixes: service/network/journal integration, screen-lock continuity, drafted FTMS resistance across a loop start, notification End/save and owner-preserving recovery. Peripheral I/O is faked; this does not establish physical trainer compatibility.
  • Physical-phone checks confirm a live Bluetooth trainer connection, recording while backgrounded with the screen off, return to the ride, and notification End/save with the journal marked finished. The production-backed bundled preview is installed and reaches the live API without USB forwarding. A further physical-phone test confirms trainer reconnection, screen-off recording against production, and the corrected foreground Finish/save action showing the saved ride summary. Longer network-interruption and workout testing remains part of rollout validation.
  • make check and Android native tests/lint/build pass locally after merging the rider-profile changes from main. GitHub CI is rerunning for the merge commit.

Rollout notes

Deploy the updated web client alongside the Android shell to enable the complete feature. Older shells retain their existing foreground behavior. Force-stop, reboot or process termination stop live riding; the journal recovers saved samples on the next launch. This implementation is Android-specific.

Google Play's connected-device foreground-service declaration must describe the user-started trainer session and notification stop action before rollout. No ride is uploaded by the notification's End/save action.

Recovery now checks the snapshot’s local profileId, including when the browser autosave is empty. Legacy journals belong to main. With #115 now on main, snapshot creation and recovery use its roster-backed activeRider() accessor. Pending recovery reads are guarded by rider generation, and delayed autosave cleanup stays pinned to the rider who left.

@ThoreKoritzius ThoreKoritzius changed the title feat: app release background notification feat: app background notification Nov 16, 2026
@ThoreKoritzius ThoreKoritzius changed the title feat: app background notification feat: show live ride stats in app notification Nov 16, 2026
@ThoreKoritzius
ThoreKoritzius changed the base branch from main to codex/android-production November 16, 2026 19:34
@ThoreKoritzius ThoreKoritzius changed the title feat: show live ride stats in app notification feat: Keep Android rides running in the background with live notification controls Nov 16, 2026
Base automatically changed from codex/android-production to main November 16, 2026 19:58

@RalfLeonFasler RalfLeonFasler left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot for this, Thore! Keeping the ride alive with the screen off is a big step for the app, and the notification looks great. Mirroring the trainer logic natively is fine; I checked the FTMS parsing, ERG ramp and virtual-shifting formula against the web client and they match.

One thing I'd like to see before we merge, and one optional note:

  1. Drafting in the background (please add). With virtual shifting on, the web client lowers the air drag by the draft saving (dragFactor from draftInfo() in ride/draft.js, up to 30 % from 2–6.5 m behind a rider in the same lane). RideEngine.command() always uses the full cda, so as soon as the screen goes off, riding in a group suddenly gets harder on the trainer. The service already receives the state messages with all riders, so it could compute the same draft from them (ideally with a shared test fixture so the two stay in sync). See the inline comment.

  2. Rider profiles (#115), not a blocker. The native journal is one file per device, and mergeNativeRecovery uses the journal's ride when the current rider has no saved one. Once several riders share a device (#115), rider B could be offered rider A's unfinished ride after a crash. If you're in there anyway, storing the rider/profile id in the snapshot and checking it on recovery would make this work with #115 right away. Otherwise we can do it afterwards.

@ThoreKoritzius

Copy link
Copy Markdown
Contributor Author

@RalfLeonFasler Thanks for the review! Both points are addressed in 0e95831:

  • Background drafting: the native service derives drafting savings from incoming rider states and applies them to the virtual-gear air-drag term. It follows the web client's lane, nearest-leader and rounding rules, including loop start-line wrapping. Web and native tests now consume the same fixture for full/partial drafting and the boundary cases.
  • Recovery ownership: snapshots carry a local profileId, and recovery checks the active owner even when the browser autosave is empty. Legacy journals belong only to main. Since feat(client): Share one device between several riders, each with their own profile and progress #115 is still separate, its roster-backed activeRider() accessor needs to replace this branch's single-rider accessor when combined; both snapshot creation and recovery already use that integration point.

I also merged current main and resolved the conflicts while retaining the Android/Discord discovery links.

Validation: make check passes with 1,782 client tests and the Rust suites; Android JVM tests, lint and builds pass. The emulator suite passed again, including screen-off recording, the actual drafted FTMS resistance command across a loop start, notification End/save and owner-preserving journal recovery. Peripheral I/O is faked in that test. All GitHub CI and CodeQL checks are now green.

I've replied to and resolved both inline threads. Ready for another look when you have time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants