allinone_location 4.1.0

Enterprise Flutter location SDK featuring Fused Location, Kalman smoothing, adaptive engines, geofencing, background recovery, diagnostic UI, and offline sync.

allinone_location

allinone_location is a production-ready, enterprise-grade Flutter Location SDK designed for high-precision tracking, navigation, battery efficiency, geofencing, background service resilience, and offline data sync.

Built with zero external binary dependencies (pure Dart + standard Flutter plugins), allinone_location combines Google Fused Location, 2D Kalman smoothing, route smoothing, speed/heading/bearing/altitude processing, dead reckoning prediction, auto-pause battery saving, GPX/CSV exporting, two-tier reverse geocoding caching, and self-healing watchdog supervision into a unified, high-performance package.

---

🌟 Key Features Matrix

Feature Module	Capabilities
Fused Location	Inverse-variance weighted multi-sample centroid averaging ($1/\sigma^2$) with LocationAccuracy.bestForNavigation.
2D Kalman & Route Smoothing	Real-time position noise reduction, moving average centroid, and Bezier curve trajectory smoothing.
Speed Engine	Moving average, exponential smoothing (EMA), max/avg calculation, and acceleration/deceleration trend detection.
Heading & Bearing	Circular weighted heading noise filter (rejects jumps >120°) & Haversine forward azimuth bearing computation.
Altitude Processing	Median window + EMA altitude filtering, spike rejection (>50m), and cumulative elevation gain/loss tracking.
Dead Reckoning	Predicts position using heading + velocity during temporary GPS outages (tunnels, parking garages).
Auto-Pause Saver	Detects stationary state via accelerometer/GPS motion classification and reduces update frequency.
Geofencing Engine	Circle and arbitrary polygon geofencing with enter/exit/dwell events and hysteresis anti-flapping protection.
Data Exporting	Export route trajectories to standard GPX 1.1 XML and CSV formats directly from memory.
Distance Matrix & ETA	Pure offline polyline distance calculation, N×M distance matrix, and travel time / ETA estimation.
Geocoding Cache	Two-tier LRU Memory + SharedPreferences Disk cache with TTL expiration for reverse geocoding lookups.
Heatmap Engine	Spatial grid cell aggregation, visit counting, frequency density calculation, and spatial clustering.
Background Resilience	Foreground service notification, boot auto-start, self-healing watchdog, and crash recovery state restoration.
Offline Sync Manager	Persistent FIFO offline queue, deduplication by coordinate/timestamp hash, and automated batch upload retry.
Diagnostic Dashboard	Pre-built Flutter UI Widget (AllInOneDiagnosticDashboard) for real-time telemetry debugging.

---

🏗 Architecture Overview

graph TD
    A[GPS Hardware / Fused Location] --> B[AllInOneLocationService]
    B --> C[Mock Location Detector]
    B --> D[Motion Detector & Activity Classification]
    B --> E[Indoor/Outdoor Engine]
    B --> F[Speed, Heading & Bearing Engines]
    B --> G[Altitude Filter & Gain/Loss Engine]
    B --> H[2D Kalman & Route Smoother]
    B --> I[Dead Reckoning Predictor]
    B --> J[Auto-Pause Engine]
    
    H --> K[AllInOneLocation Object]
    I --> K
    
    K --> L[Smart Geofence Manager]
    K --> M[Offline Location Queue & Sync Manager]
    K --> N[Crash Recovery Manager]
    K --> O[Developer Diagnostic Dashboard Widget]

---

🚀 Quick Start

1. Installation

Add allinone_location to your pubspec.yaml:

dependencies:
  allinone_location: ^4.0.0

2. Request Permissions

import 'package:allinone_location/allinone_location.dart';

Future<void> requestLocationPermissions() async {
  final hasPermission = await AllInOnePermission.requestAllPermissions();
  if (hasPermission) {
    print("✅ All location and notification permissions granted!");
  }
}

3. Get High-Accuracy Location Fix

import 'package:allinone_location/allinone_location.dart';

Future<void> fetchLocation() async {
  final location = await AllInOneLocationService.getCurrentLocation(
    config: const AllInOneConfig(
      sampleCount: 3,
      enableKalmanFilter: true,
      enableSpeedEngine: true,
      enableAltitudeFiltering: true,
    ),
  );

  print('Lat: ${location.latitude}, Lng: ${location.longitude}');
  print('Filtered Altitude: ${location.filteredAltitude}m');
  print('Speed: ${location.smoothedSpeed} m/s (Trend: ${location.speed})');
  print('Confidence: ${location.confidenceScore}%');
}

4. Background Tracking Service

import 'package:allinone_location/allinone_location.dart';

Future<void> startBackgroundTracking() async {
  await AllInOneBackground.initialize(
    config: const BackgroundConfig(
      notificationTitle: 'Site Worker Tracking Active',
      notificationContent: 'Monitoring location and safety geofences...',
      heartbeatIntervalSeconds: 15,
      enableBackgroundRecovery: true,
      enableCrashRecovery: true,
    ),
  );

  await AllInOneBackground.startTracking();
}

---

📖 Advanced Features

📦 Data Export (GPX & CSV)

// Export tracked location history to GPX XML format
final String gpxXml = GpxExporter.export(
  points: routeLocations,
  trackName: 'Field Inspection Route',
);

// Export tracked location history to CSV format
final String csvData = CsvExporter.export(
  points: routeLocations,
);

🗺 Distance Matrix & ETA Calculation

// Compute offline ETA
final eta = EtaCalculator.calculateEta(
  currentLocation: currentLocation,
  destLat: 37.7749,
  destLng: -122.4194,
);

print('Remaining: ${eta.remainingDistanceMeters}m, Arrival: ${eta.estimatedArrival}');

// Compute N x M Distance Matrix
final matrix = DistanceMatrix.computeMatrix(
  origins: [[37.7749, -122.4194]],
  destinations: [[37.7833, -122.4167], [37.7600, -122.4350]],
);

🛡 Geocoding Cache

final cache = GeocodingCache(ttl: const Duration(days: 7));

final address = await cache.getAddress(
  latitude: 37.7749,
  longitude: -122.4194,
  lookupCallback: (lat, lng) async {
    // Your preferred geocoding API lookup (Google, Nominatim, Mapbox)
    return await myGeocodingApi(lat, lng);
  },
);

📊 Heatmap Generation & Spatial Density

final heatmapEngine = HeatmapEngine(gridResolutionMeters: 50.0);
final heatmapPoints = heatmapEngine.generateHeatmap(routeLocations);
final clusters = heatmapEngine.clusterHeatmap(heatmapPoints);

📱 Developer Diagnostic Dashboard Widget

Embed the pre-built telemetry dashboard directly into your app during development:

AllInOneDiagnosticDashboard(
  currentLocation: currentLocation,
  analytics: analyticsSummary,
  offlineQueueCount: pendingQueueCount,
  isBackgroundTracking: isTracking,
  onFlushOfflineQueue: () => syncManager.syncNow(myUploadCallback),
)

---

⚡ Performance & Battery Benchmarks

Tracking Profile	Update Cadence	Battery Drain / Hour	GPS Accuracy
High Performance	Continuous (2s)	~ 2.5% / hour	< 3 meters
Adaptive (Default)	Dynamic (5s - 30s)	~ 1.2% / hour	< 5 meters
Battery Saver	Heartbeat (60s)	< 0.5% / hour	< 15 meters
Auto-Paused	Stationary Idle	< 0.1% / hour	Retains last fix

---

🔄 Migration Guide (v3.x -> v4.0)

allinone_location v4.0.0 is 100% backward-compatible. No existing API signatures or class structures were broken.

1. Config Options: New engines are configured via optional flags on AllInOneConfig (e.g. enableSpeedEngine, enableDeadReckoning).
2. Extended Location Fields: AllInOneLocation includes new optional getters: filteredAltitude, altitudeGain, smoothedSpeed, bearing, isDeadReckoned, isPaused.
3. Type Alias: IndoorOutdoorType is provided as a type alias for IndoorOutdoorState.

---

📄 License

This package is licensed under the MIT License.