Davide Scaini
244 lines
7.0 KiB
Markdown
244 lines
7.0 KiB
Markdown
# bincio-rec
|
|
|
|
GPS activity recorder for cycling, running, hiking, and walking.
|
|
Records GPS tracks + BLE sensor data (HR, power, cadence) and saves them as GPX files.
|
|
Part of the [bincio ecosystem](#ecosystem).
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
### All platforms
|
|
|
|
| Tool | Version | Notes |
|
|
|---|---|---|
|
|
| Node.js | 22+ | [nodejs.org](https://nodejs.org) |
|
|
| npm | 10+ | Comes with Node |
|
|
| Expo CLI | latest | `npm install -g expo-cli` (optional, `npx expo` works too) |
|
|
|
|
### Android
|
|
|
|
| Tool | Notes |
|
|
|---|---|
|
|
| Android Studio | [developer.android.com/studio](https://developer.android.com/studio) |
|
|
| Android SDK | Install via Android Studio SDK Manager |
|
|
| JDK 17 | Bundled with Android Studio, or install separately |
|
|
| `ANDROID_HOME` env var | Set to your SDK path, e.g. `~/Library/Android/sdk` |
|
|
|
|
Minimum supported Android version: **API 26 (Android 8.0)**.
|
|
|
|
### iOS (macOS only)
|
|
|
|
| Tool | Notes |
|
|
|---|---|
|
|
| Xcode 16+ | Install from the Mac App Store |
|
|
| Xcode Command Line Tools | `xcode-select --install` |
|
|
| CocoaPods | `sudo gem install cocoapods` |
|
|
| Apple Developer account | Free account works for device sideloading |
|
|
|
|
Minimum supported iOS version: **16.4**.
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
# 1. Install JS dependencies
|
|
npm install
|
|
|
|
# 2. Prebuild was already run — android/ and ios/ directories exist.
|
|
# Re-run only when you add/remove native modules:
|
|
npx expo prebuild --clean
|
|
```
|
|
|
|
---
|
|
|
|
## Running in development
|
|
|
|
### Android
|
|
|
|
```bash
|
|
# Start Metro bundler + launch on a connected device or emulator
|
|
npm run android
|
|
|
|
# Or target a specific device
|
|
npx expo run:android --device
|
|
```
|
|
|
|
**Android emulator setup:** In Android Studio → Device Manager, create an AVD with API 34+, x86_64 image. Start it before running the command above.
|
|
|
|
**Physical device:** Enable Developer Options → USB Debugging, then connect via USB.
|
|
|
|
> **Battery optimization:** On first launch, the app will prompt you to whitelist it in battery settings. This is required for background GPS recording to survive on Xiaomi / Samsung / Huawei devices.
|
|
|
|
### iOS
|
|
|
|
```bash
|
|
# Install CocoaPods dependencies (first time and after native changes)
|
|
cd ios && pod install && cd ..
|
|
|
|
# Start Metro bundler + launch on a connected device or simulator
|
|
npm run ios
|
|
|
|
# Or target a specific simulator
|
|
npx expo run:ios --simulator "iPhone 16"
|
|
|
|
# Or target a physical device (requires Apple Developer account)
|
|
npx expo run:ios --device
|
|
```
|
|
|
|
**Location permission:** iOS will prompt for location access. Choose **Always Allow** — background GPS recording requires it.
|
|
|
|
---
|
|
|
|
## Building release APK / IPA
|
|
|
|
### Android — local release APK
|
|
|
|
The release build embeds the JS bundle, so it runs standalone without Metro.
|
|
The default config signs with the debug keystore, which is fine for personal device testing.
|
|
|
|
```bash
|
|
cd android
|
|
./gradlew assembleRelease
|
|
# Output: android/app/build/outputs/apk/release/app-release.apk
|
|
```
|
|
|
|
**Install on a connected device via ADB:**
|
|
|
|
```bash
|
|
# Add ADB to PATH (one-time, macOS)
|
|
echo 'export PATH="$PATH:$HOME/Library/Android/sdk/platform-tools"' >> ~/.zprofile
|
|
source ~/.zprofile
|
|
|
|
# Install (device must have USB Debugging enabled)
|
|
adb install -r app/build/outputs/apk/release/app-release.apk
|
|
```
|
|
|
|
The `-r` flag reinstalls over any existing version on the device.
|
|
|
|
**Android Studio note:** If Gradle sync fails with `Cannot run program "node"`, Android Studio
|
|
launched without Homebrew in its PATH. Fix by opening from the terminal:
|
|
```bash
|
|
open -a "Android Studio" android/
|
|
```
|
|
Or make it permanent (no sudo needed):
|
|
```bash
|
|
launchctl setenv PATH "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
|
|
```
|
|
Then fully quit and reopen Android Studio.
|
|
|
|
To build a release AAB (required for Play Store):
|
|
|
|
```bash
|
|
./gradlew bundleRelease
|
|
# Output: android/app/build/outputs/bundle/release/app-release.aab
|
|
```
|
|
|
|
**Production signing:** For Play Store or sharing with others, generate a proper keystore:
|
|
```bash
|
|
keytool -genkey -v -keystore android/app/bincio-rec.keystore \
|
|
-alias bincio-rec -keyalg RSA -keysize 2048 -validity 10000
|
|
```
|
|
Then update `signingConfigs.release` in `android/app/build.gradle` to reference it.
|
|
See [React Native signing docs](https://reactnative.dev/docs/signed-apk-android).
|
|
|
|
### iOS — local release archive
|
|
|
|
Open Xcode:
|
|
|
|
```bash
|
|
open ios/binciorec.xcworkspace
|
|
```
|
|
|
|
1. Select your device or **Any iOS Device (arm64)** as the target.
|
|
2. Set your Team in **Signing & Capabilities**.
|
|
3. **Product → Archive**.
|
|
4. In the Organizer window, click **Distribute App**.
|
|
|
|
---
|
|
|
|
## Building with EAS Build (recommended for CI / TestFlight)
|
|
|
|
EAS Build runs in Expo's cloud so you don't need Android Studio or Xcode locally.
|
|
|
|
```bash
|
|
# Install EAS CLI
|
|
npm install -g eas-cli
|
|
|
|
# Log in to your Expo account
|
|
eas login
|
|
|
|
# Configure the project (first time only — creates eas.json)
|
|
eas build:configure
|
|
|
|
# Build Android APK for local testing
|
|
eas build --platform android --profile preview
|
|
|
|
# Build Android AAB for Play Store
|
|
eas build --platform android --profile production
|
|
|
|
# Build iOS IPA for TestFlight / App Store
|
|
eas build --platform ios --profile production
|
|
```
|
|
|
|
Builds appear at [expo.dev](https://expo.dev) and a download link is printed when done.
|
|
|
|
---
|
|
|
|
## Project structure
|
|
|
|
```
|
|
bincio-rec/
|
|
├── App.tsx # Entry point
|
|
├── app.json # Expo config (permissions, plugins, bundle IDs)
|
|
├── android/ # Generated Android project (do not edit manually)
|
|
├── ios/ # Generated iOS project (do not edit manually)
|
|
└── src/
|
|
├── types/index.ts # Shared TypeScript types
|
|
├── store/recording.ts # Zustand recording state + haversine stats
|
|
├── services/
|
|
│ ├── gps.ts # Background GPS via expo-location + expo-task-manager
|
|
│ ├── ble.ts # BLE scan / connect / HR + power subscriptions
|
|
│ ├── gpx.ts # GPX file builder (Garmin trackpoint extensions)
|
|
│ ├── upload.ts # Upload GPX to bincio-activity /api/upload/raw
|
|
│ └── db.ts # SQLite CRUD for saved recordings list
|
|
├── screens/
|
|
│ ├── RecordingScreen.tsx
|
|
│ ├── PostRecordingScreen.tsx
|
|
│ ├── SensorPairingScreen.tsx
|
|
│ ├── SavedRecordingsScreen.tsx
|
|
│ └── SettingsScreen.tsx
|
|
└── navigation/
|
|
└── AppNavigator.tsx # Root stack + bottom tabs
|
|
```
|
|
|
|
---
|
|
|
|
## Ecosystem
|
|
|
|
```
|
|
bincio-rec → writes GPX files to device 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
|
|
```
|
|
|
|
Configure your bincio instance URL and API token in **Settings** to enable direct upload from the app.
|
|
|
|
---
|
|
|
|
## Adding native modules
|
|
|
|
Any new Expo or React Native library with native code requires a prebuild + reinstall cycle:
|
|
|
|
```bash
|
|
npx expo install <package-name>
|
|
npx expo prebuild --clean # regenerates android/ and ios/
|
|
cd ios && pod install && cd ..
|
|
```
|
|
|
|
## License
|
|
|
|
[AGPL v3](LICENSE) — see the `LICENSE` file for details.
|