allinone_location 4.2.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 high-precision, enterprise-grade Flutter Location SDK designed for production 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.

---

📚 Documentation & Guides

• 📐 ARCHITECTURE.md — In-depth mathematical formulas, 2D Kalman state equations, centroid weighting, and state machines.
• 📊 BENCHMARKS.md — Public, reproducible performance benchmark report detailing latency, throughput, memory overhead, and geofence scaling.
• 📱 DOCS/DEVICE_PERMISSIONS.md — Platform setup guide for Android 8–15 (Foreground Services, Doze mode exemptions, Notification channels) & iOS 12–18 (Info.plist & UIBackgroundModes).
• 💡 DOCS/BEST_PRACTICES.md — Production configuration profile recipes for Delivery & Fleet Tracking, Fitness Tracking, Field Check-ins, and Asset Tracking.
• 🤝 CONTRIBUTING.md & SECURITY.md — Community governance and security reporting policy.

---

🌐 Multi-Platform Support Matrix

Platform	Location Fixes	Background Tracking	Offline Queue	Diagnostic UI
Android (8.0–15+)	✅ Google Fused GPS	✅ Foreground Service	✅ SharedPreferences	✅ Pre-built Widget
iOS (12.0–18+)	✅ CoreLocation	✅ Background Modes	✅ SharedPreferences	✅ Pre-built Widget
Web	✅ HTML5 Geolocation	⚠️ Tab Scope	✅ LocalStorage	✅ Pre-built Widget
macOS	✅ CoreLocation	✅ Background Daemon	✅ SharedPreferences	✅ Pre-built Widget
Windows	✅ WinRT Location	✅ Background Worker	✅ SharedPreferences	✅ Pre-built Widget
Linux	✅ GeoClue2	✅ Daemon Service	✅ SharedPreferences	✅ Pre-built Widget

---

🚀 Performance Benchmarks (Full Reproducible Report)

Every release is continuously stress-tested against extreme data throughput. Measured benchmark results on standard Flutter runtime:

Benchmark Test Scenario	Workload Size	Execution Time	Metric
Pipeline Throughput	10,000 Location Fixes	96 ms	9.65 µs / point
Geofence Scaling	1,000 Regions $\times$ 1,000 Locations	43 ms	1,000,000 Spatial Checks
RDP Route Compression	5,000 GPS Points	4 ms	100% Noise Reduction
2D Route Smoothing	5,000 GPS Points	9 ms	Moving Average $O(N)$
Distance Matrix	50 $\times$ 50 ($2,500$ Pairs)	< 1 ms	$2,500$ Pairs Computed
Heatmap Grid Binning	10,000 Points	20 ms	$10,000$ Grid Cells
Offline Queue Batching	1,000 Enqueued / 500 Dequeued	54 ms	Batched Storage Operations

See BENCHMARKS.md for full hardware details and methodology.

---

⚡ Comparison vs Existing Packages

Feature	geolocator	location	allinone_location
Fused GPS Location Fixes	✅	✅	✅ Multi-sample Weighted Centroid ($1/\sigma^2$)
2D Kalman & Route Smoothing	❌	❌	✅ Kalman + Bezier + Moving Average
Speed Engine & Acceleration Trends	❌	❌	✅ Moving Average + EMA + Trend
Altitude Spike Rejection & Elevation Gain	❌	❌	✅ Median + EMA Filter & Gain/Loss
Dead Reckoning Outage Prediction	❌	❌	✅ Speed + Bearing Prediction
Auto-Pause Battery Saver	❌	❌	✅ Motion Activity Classification
Circle & Polygon Geofencing	❌	❌	✅ With Dwell & Hysteresis Anti-Flapping
Offline Queue & Batch Sync	❌	❌	✅ FIFO Queue + SharedPreferences Disk
Self-Healing Background Watchdog	❌	❌	✅ Boot Auto-Start + State Recovery
GPX 1.1 XML & CSV Exporters	❌	❌	✅ Pure Offline Generators
Distance Matrix & Travel Time ETA	❌	❌	✅ Pure Offline Haversine Math
Reverse Geocoding Cache	❌	❌	✅ Two-Tier LRU Memory + Disk Cache
Diagnostic Dashboard Widget	❌	❌	✅ Pre-built Flutter UI Debugger

---

🏗 Architecture Overview

graph TD
    A[GPS Hardware / Fused Location] --> B[AllInOneLocationSDK / 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 & Examples

1. Unified SDK Access (AllInOneLocationSDK)

Access all sub-engines through a single static facade:

import 'package:allinone_location/allinone_location.dart';

// Single entry point facade accessors
final geofences = AllInOneLocationSDK.geofences;
final analytics = AllInOneLocationSDK.analytics;
final offlineSync = AllInOneLocationSDK.offlineSync;
final geocoding = AllInOneLocationSDK.geocoding;
final crashRecovery = AllInOneLocationSDK.crashRecovery;
final speedEngine = AllInOneLocationSDK.speedEngine;

2. Request Permissions

import 'package:allinone_location/allinone_location.dart';

Future<void> requestPermissions() async {
  final result = await AllInOnePermission.requestAllPermissions();
  if (result.values.any((status) => status.isGranted)) {
    print('✅ Location & notification permissions granted!');
  }
}

3. High-Accuracy Multi-Sample Centroid Fix

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('Confidence Score: ${location.confidenceScore}%');

4. Polygon & Circle Geofencing

final geofenceManager = AllInOneLocationSDK.geofences;

// Add Circle Region
geofenceManager.addRegion(GeofenceRegion.circle(
  id: 'hq_office',
  centerLatitude: 12.9716,
  centerLongitude: 77.5946,
  radiusMeters: 100.0,
  dwellDuration: const Duration(minutes: 2),
  hysteresisMeters: 5.0,
));

// Listen to enter, exit, and dwell events
geofenceManager.onGeofenceEvent.listen((event) {
  print('🚩 Geofence [${event.geofenceId}] event: ${event.type.name}');
});

5. Export Route to GPX 1.1 XML & CSV

List<AllInOneLocation> routePoints = [...];

// Export to GPX XML
final gpxString = GpxExporter.export(points: routePoints, trackName: 'Site Survey Route');

// Export to CSV
final csvString = CsvExporter.export(points: routePoints);

6. Background Tracking Service

await AllInOneBackgroundService.initialize(
  config: const BackgroundConfig(
    notificationTitle: 'Site Worker Tracking',
    notificationContent: 'Active high-precision background tracking',
    heartbeatIntervalSeconds: 15,
    enableOfflineQueue: true,
    enableGeofencing: true,
  ),
);

await AllInOneBackgroundService.startService();

---

🔄 Migration Guide (v3.x to v4.x)

In v4.0+, sub-engines and utilities are unified under AllInOneLocationSDK (alias AllInOneLocationService):

Old v3.x API	New v4.x API
AllInOneBackground.initializeService(...)	AllInOneBackgroundService.initialize(...)
AllInOneBackground.startTracking()	AllInOneBackgroundService.startService()
OfflineLocationQueue() instance	AllInOneLocationSDK.offlineQueue
SmartGeofenceManager() instance	AllInOneLocationSDK.geofences
GpxExporter.export(route)	GpxExporter.export(points: route)

---

❓ Frequently Asked Questions (FAQ)

Q: Does this package work offline without an internet connection?

Yes! All calculations (Haversine distances, 2D Kalman filtering, RDP route compression, polygon ray-casting geofence checks, Distance Matrix computation, GPX/CSV generation) run entirely offline in pure Dart. Offline location fixes are queued locally in `OfflineLocationQueue` and automatically synced when connectivity resumes.

Q: How does `allinone_location` save battery during long background tracking?

The SDK uses an Auto-Pause Motion Activity Engine. When the device is stationary (classified as ActivityType.still via accelerometer data), the sampling rate scales down automatically, preventing unnecessary CPU wake locks and GPS chip battery drain.

Q: Is mock/fake GPS detection supported?

Yes! Every location fix is inspected by MockLocationDetector which analyzes provider flags, altitude consistency, and speed plausibility to identify spoofed location coordinates.

---

🛠 Community & Contribution

We welcome contributions! Please review our Contributing Guide and Code of Conduct.

To run unit & performance benchmark tests locally:

cd packages/allinone
flutter test

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.