bincio-rec

GPS activity recorder for the bincio ecosystem. Companion to bincio-autarchive (archive/sync app): rec makes the data, autarchive stores and syncs it.

Concept

A focused, minimal recording app for cycling, running, hiking, and walking. Records GPS track + BLE sensor data, saves to GPX, optionally uploads directly to a bincio-activity server. Future: live navigation / turn-by-turn instructions.

The app does one thing well: record. No browsing, no analysis — that's autarchive's job.

Ecosystem

bincio-rec          →  writes GPX files to shared storage
bincio-autarchive   →  imports GPX, stores locally, syncs to server
bincio-activity     →  server: parses GPX, stores activities, serves API
bincio-auth         →  auth service: issues JWTs for all bincio apps

bincio-rec can also upload directly to bincio-activity via /api/upload/raw (same endpoint autarchive uses), with instance URL + API token configured in settings.

Tech Stack

Expo Prebuild (not managed Expo, not bare RN).

Managed Expo ruled out: BLE requires native modules
Bare RN ruled out: Expo library ecosystem is valuable (location, notifications, file system)
Prebuild gives full native access while keeping Expo tooling and EAS Build

Key libraries:

expo-location + expo-task-manager — background GPS recording
react-native-ble-plx — BLE sensors (HR, power, cadence)
@maplibre/maplibre-react-native — live track map, future navigation
expo-notifications — km milestone alerts, future navigation cues
expo-keep-awake — keep screen on during recording (user-toggleable)
expo-file-system — write GPX/JSON to shared storage
expo-sqlite — local DB for past recordings list

Target: Android first, iOS second.

v1 Screens

Sensor pairing — scan BLE, pair HR monitor / power meter / cadence sensor; persisted
Recording — start / pause / resume / stop
- Live stats: elapsed time, distance, current+avg speed, HR, power, cadence, elevation gain
- Map with track drawn in real time
- Keep-awake toggle
Post-recording summary — stats overview, title field, save / discard
Saved recordings — list of past sessions; tap to export GPX or upload to server
Settings — bincio instance URL + API token; km notification toggle; upload format

Output Format

GPX with Garmin trackpoint extensions — one <trkpt> per second with:

lat/lon/elevation from GPS
<gpxtpx:hr> — heart rate
<gpxtpx:power> — power (watts)
<gpxtpx:cad> — cadence (rpm)

bincio-activity already parses this format via bincio.extract.parsers.

Files saved to a user-accessible location (iOS Files app / Android shared storage) so bincio-autarchive can import them manually.

Known Platform Concerns

Android battery optimization: aggressive OEMs (Xiaomi, Samsung, Huawei) kill background tasks. Prompt user to whitelist bincio-rec in battery settings on first launch. Every recording app has this problem — no framework-level fix.
iOS background location: requires location background mode in Info.plist and "Always" location permission. Fine for sideloading/TestFlight; App Store submission requires clear justification.
iOS foreground notifications: notification sounds are suppressed when app is in foreground — use expo-av audio cue instead for km alerts while screen is on.

Out of Scope (v1)

Navigation / turn-by-turn routing
Auto-pause (stop lights, etc.)
Structured workouts / intervals
Offline maps
Live tracking / sharing

v1 Completion Plan

Scaffold is done (all screens, navigation, store, services, GPX, DB, upload). Items below are what remains before v1 is shippable.

1 — Quick fixes (each < 30 min)

Keep-awake toggle — useKeepAwake() in RecordingScreen is unconditional; wire it to keepAwake from the store so the toggle actually works
Sensor button on Recording screen — no entry point to the SensorPairing modal; add a BLE icon button in the header or stats area that calls nav.navigate('SensorPairing')
GPS pause/resume — pause() / resume() only change store state; also call stopGpsRecording() / startGpsRecording() so the background task actually pauses

2 — BLE (half day)

Android runtime permissions — BLUETOOTH_SCAN + BLUETOOTH_CONNECT require explicit permission requests on Android 12+; add a requestBlePermissions() call in SensorPairingScreen before scanning
Cadence CSC parsing — subscribeCadence() in ble.ts is stubbed; implement stateful CSC Measurement parsing (track previous crank revolution count + timestamp, compute RPM from delta)
BLE persistence — save paired device IDs + types to AsyncStorage on connect; on app start, attempt to reconnect to previously paired devices automatically

3 — Km notifications (half day)

Permission request — call Notifications.requestPermissionsAsync() on first launch
Milestone tracker — track last notified km in the GPS background task (or store); fire a notification each time distanceMeters crosses a new km boundary, gated on the kmNotifications setting from AsyncStorage

4 — Android battery optimization prompt (1–2 hours)

On first launch, detect if the app is affected by battery optimization (expo-intent-launcher) and show a one-time prompt directing the user to whitelist bincio-rec; persist dismissal in AsyncStorage so it only shows once

5 — Map (1–2 days)

Initialize MapLibre — call MapLibreGL.setAccessToken(null) at app start (or configure a tile provider in Settings); add a tile source (e.g. OpenFreeMap / self-hosted)
Replace placeholder — swap the grey <View> in RecordingScreen with a <MapLibreGL.MapView> + <MapLibreGL.Camera> that follows current location
Live track polyline — subscribe to trackPoints from the store and render a <MapLibreGL.ShapeSource> + <MapLibreGL.LineLayer> that updates as points arrive

6.0 KiB Raw Blame History Unescape Escape