🚌 BusPulse

BusPulse is a real-time school bus GPS tracking and telemetry ecosystem built with Flutter and Firebase. It provides two distinct portals: an active Driver Portal for broadcasting live GPS streams from a background service, and an interactive Parent Portal featuring cached maps, weather integration, and customized geofence proximity notifications.

---

🌟 Key Features

📡 Driver Portal

• Foreground Tracking Service: Uses background isolates and persistent system notifications to guarantee uninterrupted GPS streams even when the app is minimized or closed.
• Sensory Filters: Automatically filters out erratic GPS drift (points with accuracy > 100m) to maintain precise tracking.
• Smart Telemetry Throttling: Saves bandwidth and battery by limiting database writes to a maximum of once every 2 seconds and skipping redundant updates when the bus is stationary.
• Live Stream Logs: Offers real-time console log prints for drivers to inspect network connectivity, GPS fixes, and Firebase write transactions.

🏠 Parent Portal

• Cached OpenStreetMap View: Interactive maps built on flutter_map with local file cache storage to reduce mobile data usage.
• Blended ETA Calculation: Combines actual live velocity (using a rolling average of speed readings) with precise OSRM API routing paths to estimate arrival times.
• Geofenced Proximity Alerts: Fires local system notifications when the bus is within 2 km, 500 m, and 100 m ranges of the home stop.
• Interactive Stop Selector: Parents can relocate their home stop pins directly on the map interface.
• Live Weather Updates: Queries Open-Meteo weather telemetry to show current temperatures, wind speeds, and visual icons at the bus location.
• Safety Monitoring: Displays alerts for high speeds (>60 km/h) and debounced stoppage tracking.

---

🛠️ Technology Stack

• Framework: Flutter (SDK ^3.12.1)
• Backend & Database: Firebase (Authentication, Realtime Database)
• Maps & Routing: OpenStreetMap (OSM), OSRM API, and flutter_map
• Background Isolates: flutter_background_service & geolocator
• Notifications: flutter_local_notifications
• Data Caching: dio_cache_interceptor & flutter_map_cache
• Weather API: Open-Meteo API

---

📂 Project Structure

lib/
├── firebase_options.dart      # Autogenerated Firebase credentials setup
├── main.dart                  # App initialization, routing & state wrapper
├── models/
│   ├── journey_log.dart       # Logging models for telemetry states
│   └── parent_models.dart     # Proximity and alert log data structures
├── pages/
│   ├── login_page.dart        # Dual-role entry authentication gate
│   ├── home_page.dart         # Driver Console & GPS stream controls
│   └── parent_dashboard_page.dart # Map dashboard, ETAs, alerts & weather settings
├── services/
│   ├── auth_service.dart      # Firebase Authentication manager & provider
│   └── location_service.dart  # Background GPS isolate & database sync
├── theme/
│   └── app_theme.dart         # Unified system dark-mode styling tokens
└── widgets/
    └── app_splash_screen.dart # Splash screen loading animation

---

🚀 Getting Started

Prerequisites

1. Installed Flutter SDK (Version 3.12.0 or higher).
2. Connected physical device or emulator (Background location requires physical hardware sensors for optimal accuracy).

Setup Instructions

1. Clone and Navigate:

   cd bus

2. Install Dependencies:

   flutter pub get

3. Configure Firebase:

   • Place your google-services.json inside android/app/ for Android.
   • Run the FlutterFire CLI command or replace the default configurations in lib/firebase_options.dart to link with your Firebase instance:

     flutterfire configure

4. Launch the Application:

   flutter run

---

🧪 Safety and Permissions

To ensure background tracking operates correctly on mobile devices:

• Location Permission: Must be granted as "Allow all the time" for background updates.
• Notification Permission: Must be approved to show the active foreground service notification status.
• Battery Optimization: Disable battery optimization flags on Android to prevent the operating system from terminating the background isolate.