EV Range Tracker

Offline range and battery estimation app for the TailG F52, built on a physics model (cruise + congestion overhead) with real-trip calibration data collection for future ML refinement.

Folder structure

ev_range_tracker/
├── android/                     # generated by `flutter create .`
├── ios/                          # generated by `flutter create .`
├── analysis/
│   └── analyze_trips.py          # offline: turns exported CSVs into
│                                  # calibration constants + residual model
├── lib/
│   ├── main.dart                  # Hive init, theming, 3-tab root shell
│   ├── theme/
│   │   └── app_theme.dart         # Material You theme + tank gauge colors
│   ├── models/                    # Hive data models
│   │   ├── vehicle_profile.dart   # F52 spec + calibration constants
│   │   ├── trip_sample.dart       # raw 1Hz GPS samples
│   │   ├── trip_metadata.dart     # per-trip rider/passenger/charge state
│   │   └── bar_drop_event.dart    # mid-trip "bar just dropped" anchors
│   ├── services/
│   │   ├── range_engine.dart      # pure-Dart physics + coulomb counter
│   │   └── trip_logger.dart       # GPS logging, start/stop, CSV export
│   ├── screens/
│   │   ├── home_screen.dart       # dashboard: tank gauge, quick actions
│   │   ├── active_trip_screen.dart# live ride: speed/distance/bar-drop
│   │   ├── trip_history_screen.dart
│   │   └── vehicle_setup_screen.dart
│   └── widgets/
│       ├── battery_gauge.dart     # the signature tank/battery gauge
│       └── stat_tile.dart         # reusable labeled stat display
├── test/
│   └── range_engine_test.dart     # validates physics against real benchmarks
├── pubspec.yaml
└── README.md

Setup

1. Copy lib/, test/, pubspec.yaml, analysis/ into your existing EV_Range_Tracker project folder (keep your existing android//ios/).

2. Install dependencies:

   flutter pub get

3. Generate Hive adapter code (needed for every @HiveType model — vehicle_profile.dart, trip_sample.dart, trip_metadata.dart, bar_drop_event.dart):

   dart run build_runner build --delete-conflicting-outputs

4. Run the tests:

   flutter test

5. Run the app:

   flutter run

What's wired up vs. what's a stub

Wired: Hive persistence, the 3-tab shell (Home/History/Settings), the tank gauge UI, start/stop ride flow, mid-trip bar-drop logging, CSV export from TripLogger.

Deliberately stubbed for you to connect:

• ActiveTripScreen's speed/distance display is currently just a UI shell with a stopwatch — it doesn't yet call engine.tick() from live GPS. Wire TripLogger's position stream to also call RangeEngine.tick() per sample (they're currently separate so you can test each independently).
• A "Share Export" button using share_plus to send a trip's CSVs off the phone — the export logic exists in TripLogger.exportTripToCsv(), just needs a button calling it + Share.shareXFiles(...).
• GPS permission request flow (geolocator's requestPermission()) — not yet called anywhere; add it before TripLogger.startTrip().

Design notes

The tank gauge (widgets/battery_gauge.dart) is deliberately shaped like a battery with a liquid fill level, not a generic circular ring — it's meant to visually reinforce that this number comes from the software energy-tank model, not the bike's own (untrustworthy) bars. Color shifts teal → amber → red via TankColors, matching the amber/red distance-based alerts from the original feature spec.

Manifest additions needed for this update (map + background notification)

Add these inside <manifest> (alongside the location permissions from before) in android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.INTERNET" />

And this inside <application> (do not rename the service):

<service
    android:name="com.pravera.flutter_foreground_task.service.ForegroundService"
    android:foregroundServiceType="location"
    android:exported="false" />

These come straight from flutter_foreground_task 9.2.2's own setup docs — pinned exactly to that version, not guessed.

New in this update

• Map — flutter_map + CartoDB Dark Matter tiles, with a hand-rolled offline-first tile provider (offline_tile_provider.dart) instead of flutter_map_tile_caching. That package depends on ObjectBox (a native database) — one more native-build surface on top of the Kotlin issues you already hit. The plain-file approach only uses FileImage/NetworkImage, both simple and stable.
• Offline downloads — Settings > Offline Map, pre-downloads tiles for your Mirpur DOHS <-> Tongi corridor (real coordinates, buffered). Standard Slippy Map tile math, nothing exotic.
• Trip detail screen — tap any trip in History for its route map, distance/duration/avg+max speed/stop count/elevation gain, notes, and its bar-drop + alert timeline.
• Persistent notification — trip_foreground_task.dart, using the exact current (9.2.2) TaskHandler API confirmed against the package's own docs.
• Export format — now 2 files per trip: _samples.csv (raw GPS, genuinely tabular) and _trip.json (metadata + bar drops + alerts — these fit JSON's nested-list shape far better than forced-flat CSV).