@josuelmm/cordova-background-geolocation 3.1.1 → 4.2.0

package/android/common/src/main/java/com/marianhello/bgloc/oem/BatteryOemHelper.java

@@ -0,0 +1,214 @@
+package com.marianhello.bgloc.oem;
+
+import android.app.Activity;
+import android.content.ComponentName;
+import android.content.Context;
+import android.content.Intent;
+import android.net.Uri;
+import android.os.Build;
+import android.os.PowerManager;
+import android.provider.Settings;
+
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+/**
+ * v3.6 Phase 5: Battery / OEM helpers.
+ *
+ * Standard Android Doze whitelist:
+ *   - {@link #isIgnoringBatteryOptimizations(Context)}
+ *   - {@link #requestIgnoreBatteryOptimizations(Activity)}
+ *   - {@link #openBatterySettings(Activity)}
+ *
+ * OEM-specific "auto-start" / "background activity" screens (Xiaomi MIUI, Huawei
+ * EMUI, Oppo ColorOS, Vivo FunTouch, Samsung One UI). These cannot be granted
+ * programmatically — the user must toggle them in Settings.
+ */
+public final class BatteryOemHelper {
+
+    private BatteryOemHelper() { /* no instances */ }
+
+    public static boolean isIgnoringBatteryOptimizations(Context ctx) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.M) return true;
+        try {
+            PowerManager pm = (PowerManager) ctx.getSystemService(Context.POWER_SERVICE);
+            return pm != null && pm.isIgnoringBatteryOptimizations(ctx.getPackageName());
+        } catch (Exception e) {
+            return false;
+        }
+    }
+
+    /**
+     * Opens the system battery-optimisation prompt for the app.
+     * Does not throw; logs and silently returns if the system dialog is missing.
+     */
+    public static void requestIgnoreBatteryOptimizations(Activity activity) {
+        if (activity == null || Build.VERSION.SDK_INT < Build.VERSION_CODES.M) return;
+        try {
+            Intent intent = new Intent(Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS);
+            intent.setData(Uri.parse("package:" + activity.getPackageName()));
+            intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+            activity.startActivity(intent);
+        } catch (Exception ignored) {
+            openBatterySettings(activity);
+        }
+    }
+
+    public static void openBatterySettings(Activity activity) {
+        if (activity == null) return;
+        // Try the per-app battery usage screen first; fall back to app-info.
+        try {
+            Intent intent = new Intent(Settings.ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS);
+            intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+            activity.startActivity(intent);
+        } catch (Exception e) {
+            try {
+                Intent fallback = new Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS);
+                fallback.setData(Uri.parse("package:" + activity.getPackageName()));
+                fallback.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+                activity.startActivity(fallback);
+            } catch (Exception ignored) {}
+        }
+    }
+
+    /**
+     * Open the OEM-specific "auto-start" / "background activity" screen.
+     * Returns a JSON object describing what was opened so the JS layer can show
+     * appropriate copy: { opened, manufacturer, screen }.
+     */
+    public static JSONObject openAutoStartSettings(Activity activity) throws JSONException {
+        JSONObject out = new JSONObject();
+        String manufacturer = Build.MANUFACTURER != null ? Build.MANUFACTURER.toLowerCase() : "";
+        out.put("manufacturer", manufacturer);
+        out.put("opened", false);
+        out.put("screen", "");
+
+        if (activity == null) return out;
+
+        ComponentName component = autoStartComponent(manufacturer);
+        if (component != null) {
+            try {
+                Intent intent = new Intent();
+                intent.setComponent(component);
+                intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+                activity.startActivity(intent);
+                out.put("opened", true);
+                out.put("screen", component.flattenToShortString());
+                return out;
+            } catch (Exception ignored) { /* fall through to app-info */ }
+        }
+
+        // Fallback: standard application details page so the user can toggle background restrictions.
+        try {
+            Intent fallback = new Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS);
+            fallback.setData(Uri.parse("package:" + activity.getPackageName()));
+            fallback.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+            activity.startActivity(fallback);
+            out.put("opened", true);
+            out.put("screen", "android.settings.APPLICATION_DETAILS_SETTINGS");
+        } catch (Exception ignored) {}
+        return out;
+    }
+
+    /** Known OEM auto-start screen components. Verified against AOSP / OEM forks; may vary by ROM. */
+    private static ComponentName autoStartComponent(String manufacturer) {
+        if (manufacturer == null) return null;
+        if (manufacturer.contains("xiaomi") || manufacturer.contains("redmi") || manufacturer.contains("poco")) {
+            return new ComponentName("com.miui.securitycenter",
+                    "com.miui.permcenter.autostart.AutoStartManagementActivity");
+        }
+        if (manufacturer.contains("huawei") || manufacturer.contains("honor")) {
+            return new ComponentName("com.huawei.systemmanager",
+                    "com.huawei.systemmanager.startupmgr.ui.StartupNormalAppListActivity");
+        }
+        if (manufacturer.contains("oppo")) {
+            return new ComponentName("com.coloros.safecenter",
+                    "com.coloros.safecenter.permission.startup.StartupAppListActivity");
+        }
+        if (manufacturer.contains("vivo")) {
+            return new ComponentName("com.vivo.permissionmanager",
+                    "com.vivo.permissionmanager.activity.BgStartUpManagerActivity");
+        }
+        if (manufacturer.contains("samsung")) {
+            // Samsung does not expose a stable component for "Sleeping apps"; return null and
+            // let the caller fall back to app-info, where the user can disable battery optimisation.
+            return null;
+        }
+        if (manufacturer.contains("oneplus")) {
+            return new ComponentName("com.oneplus.security",
+                    "com.oneplus.security.chainlaunch.view.ChainLaunchAppListActivity");
+        }
+        if (manufacturer.contains("asus")) {
+            return new ComponentName("com.asus.mobilemanager",
+                    "com.asus.mobilemanager.entry.FunctionActivity");
+        }
+        return null;
+    }
+
+    /**
+     * Returns OEM-specific guidance steps. The caller renders them as a help screen.
+     */
+    public static JSONObject getManufacturerHelp() throws JSONException {
+        JSONObject out = new JSONObject();
+        String m = Build.MANUFACTURER != null ? Build.MANUFACTURER.toLowerCase() : "";
+        out.put("manufacturer", m);
+        out.put("steps", new JSONArray(stepsFor(m)));
+        return out;
+    }
+
+    private static String[] stepsFor(String manufacturer) {
+        if (manufacturer.contains("xiaomi") || manufacturer.contains("redmi") || manufacturer.contains("poco")) {
+            return new String[] {
+                "Settings → Apps → Manage apps → [your app] → Autostart → enable.",
+                "Settings → Apps → Manage apps → [your app] → Battery saver → No restrictions.",
+                "Settings → Apps → Manage apps → [your app] → Other permissions → Display pop-up windows while running in the background → Allow.",
+                "Lock the app in Recents (drag it down to keep it in memory)."
+            };
+        }
+        if (manufacturer.contains("huawei") || manufacturer.contains("honor")) {
+            return new String[] {
+                "Settings → Apps → [your app] → Battery → App launch → switch off Manage automatically and enable Auto-launch + Run in background.",
+                "Settings → Battery → App launch → [your app] → manage manually."
+            };
+        }
+        if (manufacturer.contains("oppo")) {
+            return new String[] {
+                "Settings → Battery → Power Consumption Protection → [your app] → Allow.",
+                "Settings → Apps → App management → [your app] → Permissions → Auto-start → Allow.",
+                "Settings → Privacy permissions → Startup manager → [your app] → enable."
+            };
+        }
+        if (manufacturer.contains("vivo")) {
+            return new String[] {
+                "Settings → Battery → High background power consumption → [your app] → Allow.",
+                "Settings → More settings → Permission management → Auto-start → [your app] → enable."
+            };
+        }
+        if (manufacturer.contains("samsung")) {
+            return new String[] {
+                "Settings → Apps → [your app] → Battery → Unrestricted.",
+                "Settings → Battery and device care → Battery → Background usage limits → Sleeping apps → make sure [your app] is NOT listed.",
+                "Settings → Battery and device care → Battery → Background usage limits → Never sleeping apps → add [your app]."
+            };
+        }
+        if (manufacturer.contains("oneplus")) {
+            return new String[] {
+                "Settings → Battery → Battery optimisation → [your app] → Don't optimise.",
+                "Settings → Apps → [your app] → Battery → Background activity → Allow."
+            };
+        }
+        if (manufacturer.contains("asus")) {
+            return new String[] {
+                "Settings → Apps → [your app] → Battery → Battery saver → Off.",
+                "Mobile Manager → Auto-start manager → [your app] → enable."
+            };
+        }
+        // Generic Android.
+        return new String[] {
+            "Settings → Apps → [your app] → Battery → Unrestricted.",
+            "Settings → Apps → [your app] → Permissions → Location → Allow all the time.",
+            "Disable battery optimisation for [your app] in Settings → Battery."
+        };
+    }
+}

package/android/common/src/main/java/com/marianhello/bgloc/provider/ActivityRecognitionLocationProvider.java

@@ -21,6 +21,7 @@ import com.google.android.gms.location.LocationCallback;
 import com.google.android.gms.location.LocationRequest;
 import com.google.android.gms.location.LocationResult;
 import com.google.android.gms.location.LocationServices;
+import com.google.android.gms.location.Priority;
 import com.marianhello.bgloc.Config;
 import com.marianhello.bgloc.data.BackgroundActivity;
 
@@ -136,10 +137,12 @@ public class ActivityRecognitionLocationProvider extends AbstractLocationProvide
         if (fusedLocationClient == null || mConfig == null) { return; }
 
         int priority = translateDesiredAccuracy(mConfig.getDesiredAccuracy());
-        LocationRequest locationRequest = LocationRequest.create()
-                .setPriority(priority)
-                .setFastestInterval(mConfig.getFastestInterval())
-                .setInterval(mConfig.getInterval());
+        // v3.4: LocationRequest.Builder (play-services-location 21.0.0+) replaces deprecated
+        // LocationRequest.create() + setPriority/setInterval/setFastestInterval.
+        LocationRequest locationRequest = new LocationRequest.Builder(priority, mConfig.getInterval())
+                .setMinUpdateIntervalMillis(mConfig.getFastestInterval())
+                .setWaitForAccurateLocation(false)
+                .build();
 
         try {
             fusedLocationClient.requestLocationUpdates(
@@ -213,19 +216,20 @@ public class ActivityRecognitionLocationProvider extends AbstractLocationProvide
      * 1000:  least aggressive, least accurate, best for battery.
      */
     private int translateDesiredAccuracy(Integer accuracy) {
+        // v3.4: Priority.* (play-services-location 21.0.0+) replaces deprecated LocationRequest.PRIORITY_*.
         if (accuracy == null) {
-            return LocationRequest.PRIORITY_BALANCED_POWER_ACCURACY;
+            return Priority.PRIORITY_BALANCED_POWER_ACCURACY;
         }
         if (accuracy >= 10000) {
-            return LocationRequest.PRIORITY_NO_POWER;
+            return Priority.PRIORITY_PASSIVE;
         }
         if (accuracy >= 1000) {
-            return LocationRequest.PRIORITY_LOW_POWER;
+            return Priority.PRIORITY_LOW_POWER;
         }
         if (accuracy >= 100) {
-            return LocationRequest.PRIORITY_BALANCED_POWER_ACCURACY;
+            return Priority.PRIORITY_BALANCED_POWER_ACCURACY;
         }
-        return LocationRequest.PRIORITY_HIGH_ACCURACY;
+        return Priority.PRIORITY_HIGH_ACCURACY;
     }
 
     public static DetectedActivity getProbableActivity(List<DetectedActivity> detectedActivities) {

package/android/common/src/main/java/com/marianhello/bgloc/provider/DistanceFilterLocationProvider.java

@@ -6,7 +6,6 @@ import android.content.BroadcastReceiver;
 import android.content.Context;
 import android.content.Intent;
 import android.content.IntentFilter;
-import android.location.Criteria;
 import android.location.Location;
 import android.location.LocationListener;
 import android.location.LocationManager;
@@ -55,8 +54,6 @@ public class DistanceFilterLocationProvider extends AbstractLocationProvider imp
     private PendingIntent singleUpdatePI;
     private Integer scaledDistanceFilter;
 
-    private Criteria criteria;
-
     private LocationManager locationManager;
     private AlarmManager alarmManager;
 
@@ -110,12 +107,20 @@ public class DistanceFilterLocationProvider extends AbstractLocationProvider imp
         singleUpdatePI = PendingIntent.getBroadcast(mContext, 9003, singleLocationUpdateIntent, cancelCurrentFlag);
         registerReceiver(singleUpdateReceiver, new IntentFilter(SINGLE_LOCATION_UPDATE_ACTION));
 
-        // Location criteria
-        criteria = new Criteria();
-        criteria.setAltitudeRequired(false);
-        criteria.setBearingRequired(false);
-        criteria.setSpeedRequired(true);
-        criteria.setCostAllowed(true);
+        // v3.4 Phase 3: Criteria API removed (deprecated since Android 12 / API 31).
+        // Provider selection is now explicit (GPS-first / Network-fallback) via pickProvider().
+    }
+
+    /** v3.4 Phase 3: replaces getBestProvider(criteria, true). */
+    private String pickProvider() {
+        if (locationManager == null) return null;
+        if (locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER)) {
+            return LocationManager.GPS_PROVIDER;
+        }
+        if (locationManager.isProviderEnabled(LocationManager.NETWORK_PROVIDER)) {
+            return LocationManager.NETWORK_PROVIDER;
+        }
+        return null;
     }
 
     @Override
@@ -209,9 +214,6 @@ public class DistanceFilterLocationProvider extends AbstractLocationProvider imp
 
         try {
             locationManager.removeUpdates(this);
-            criteria.setAccuracy(Criteria.ACCURACY_FINE);
-            criteria.setHorizontalAccuracy(translateDesiredAccuracy(mConfig.getDesiredAccuracy()));
-            criteria.setPowerRequirement(Criteria.POWER_HIGH);
 
             if (isMoving) {
                 // setPace can be called while moving, after distanceFilter has been recalculated.  We don't want to re-acquire velocity in this case.
@@ -228,18 +230,15 @@ public class DistanceFilterLocationProvider extends AbstractLocationProvider imp
                 // Turn on each provider aggressively for a short period of time
                 List<String> matchingProviders = locationManager.getAllProviders();
                 for (String provider: matchingProviders) {
-                    if (provider != LocationManager.PASSIVE_PROVIDER) {
+                    if (!LocationManager.PASSIVE_PROVIDER.equals(provider)) {
                         logger.info("Requesting location updates from provider {}", provider);
                         locationManager.requestLocationUpdates(provider, 0, 0, this);
                     }
                 }
             } else {
-                String provider = locationManager.getBestProvider(criteria, true);
-                if (Build.VERSION.SDK_INT > 30 && locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER)) {
-                    provider = LocationManager.GPS_PROVIDER;
-                }
+                String provider = pickProvider();
                 if (provider == null) {
-                    logger.warn("No best provider available");
+                    logger.warn("No location provider available (GPS and Network disabled)");
                     return;
                 }
                 logger.info("Requesting location updates from provider {}", provider);
@@ -251,23 +250,8 @@ public class DistanceFilterLocationProvider extends AbstractLocationProvider imp
         }
     }
 
-    /**
-     * Translates a number representing desired accuracy of Geolocation system from set [0, 10, 100, 1000].
-     * 0:  most aggressive, most accurate, worst battery drain
-     * 1000:  least aggressive, least accurate, best for battery.
-     */
-    private int translateDesiredAccuracy(Integer accuracy) {
-        if (accuracy == null) {
-            return Criteria.ACCURACY_MEDIUM;
-        }
-        if (accuracy >= 1000) {
-            return Criteria.ACCURACY_LOW;
-        }
-        if (accuracy >= 100) {
-            return Criteria.ACCURACY_MEDIUM;
-        }
-        return Criteria.ACCURACY_HIGH;
-    }
+    // v3.4 Phase 3: translateDesiredAccuracy(...) returning Criteria.ACCURACY_* removed.
+    // Provider selection no longer depends on Criteria; pickProvider() chooses GPS-first.
 
     /**
      * Returns the most accurate and timely previously detected location.
@@ -533,14 +517,19 @@ public class DistanceFilterLocationProvider extends AbstractLocationProvider imp
             logger.info("Stationary location monitor fired");
             playDebugTone(Tone.DIALTONE);
 
-            criteria.setAccuracy(Criteria.ACCURACY_FINE);
-            criteria.setHorizontalAccuracy(Criteria.ACCURACY_HIGH);
-            criteria.setPowerRequirement(Criteria.POWER_HIGH);
-
+            // v3.4 Phase 3: Criteria-based requestSingleUpdate removed (deprecated since API 31).
+            // Use the provider-string overload, which is still supported and stable.
+            String provider = pickProvider();
+            if (provider == null) {
+                logger.warn("Stationary monitor: no provider available");
+                return;
+            }
             try {
-                locationManager.requestSingleUpdate(criteria, singleUpdatePI);
+                locationManager.requestSingleUpdate(provider, singleUpdatePI);
             } catch (SecurityException e) {
                 logger.error("Security exception: {}", e.getMessage());
+            } catch (IllegalArgumentException e) {
+                logger.warn("requestSingleUpdate failed: {}", e.getMessage());
             }
         }
     }

package/android/common/src/main/java/com/marianhello/bgloc/provider/RawLocationProvider.java

@@ -1,14 +1,12 @@
 package com.marianhello.bgloc.provider;
 
 import android.content.Context;
-import android.location.Criteria;
 import android.location.Location;
 import android.location.LocationListener;
 import android.location.LocationManager;
 import android.os.Bundle;
 
 import com.marianhello.bgloc.Config;
-import com.marianhello.logging.LoggerManager;
 
 public class RawLocationProvider extends AbstractLocationProvider implements LocationListener {
     private LocationManager locationManager;
@@ -39,21 +37,10 @@ public class RawLocationProvider extends AbstractLocationProvider implements Loc
             logger.warn("RawLocationProvider started without config");
             return;
         }
-        String provider = LocationManager.GPS_PROVIDER;
-        boolean gpsEnabled = locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER);
-        if (!gpsEnabled) {
-            Criteria criteria = new Criteria();
-            criteria.setAltitudeRequired(false);
-            criteria.setBearingRequired(false);
-            criteria.setSpeedRequired(true);
-            criteria.setCostAllowed(true);
-            criteria.setAccuracy(Criteria.ACCURACY_FINE);
-            criteria.setHorizontalAccuracy(translateDesiredAccuracy(mConfig.getDesiredAccuracy()));
-            criteria.setPowerRequirement(Criteria.POWER_HIGH);
-            provider = locationManager.getBestProvider(criteria, true);
-        }
+        // v3.4 Phase 3: explicit GPS/Network selection. Drops the deprecated Criteria + getBestProvider.
+        String provider = pickProvider();
         if (provider == null) {
-            logger.warn("No location provider available (GPS disabled and getBestProvider returned null)");
+            logger.warn("No location provider available (GPS and Network disabled)");
             return;
         }
         try {
@@ -66,6 +53,17 @@ public class RawLocationProvider extends AbstractLocationProvider implements Loc
         }
     }
 
+    /** GPS first, fall back to Network. */
+    private String pickProvider() {
+        if (locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER)) {
+            return LocationManager.GPS_PROVIDER;
+        }
+        if (locationManager.isProviderEnabled(LocationManager.NETWORK_PROVIDER)) {
+            return LocationManager.NETWORK_PROVIDER;
+        }
+        return null;
+    }
+
     @Override
     public void onStop() {
         if (!isStarted) {
@@ -118,24 +116,6 @@ public class RawLocationProvider extends AbstractLocationProvider implements Loc
         logger.debug("Provider {} was disabled", provider);
     }
 
-    /**
-     * Translates a number representing desired accuracy of Geolocation system from set [0, 10, 100, 1000].
-     * 0:  most aggressive, most accurate, worst battery drain
-     * 1000:  least aggressive, least accurate, best for battery.
-     */
-    private int translateDesiredAccuracy(Integer accuracy) {
-        if (accuracy == null) {
-            return Criteria.ACCURACY_MEDIUM;
-        }
-        if (accuracy >= 1000) {
-            return Criteria.ACCURACY_LOW;
-        }
-        if (accuracy >= 100) {
-            return Criteria.ACCURACY_MEDIUM;
-        }
-        return Criteria.ACCURACY_HIGH;
-    }
-
     @Override
     public void onDestroy() {
         logger.debug("Destroying RawLocationProvider");

package/android/common/src/main/java/com/marianhello/bgloc/sensor/SensorFusionDetector.java

@@ -0,0 +1,199 @@
+package com.marianhello.bgloc.sensor;
+
+import android.content.Context;
+import android.hardware.Sensor;
+import android.hardware.SensorEvent;
+import android.hardware.SensorEventListener;
+import android.hardware.SensorManager;
+import android.os.Handler;
+import android.os.Looper;
+import android.os.PowerManager;
+
+import com.marianhello.bgloc.data.BackgroundLocation;
+
+/**
+ * v4.2 Phase 8 — Real sensor fusion detector.
+ *
+ * Samples linear acceleration (TYPE_LINEAR_ACCELERATION, gravity removed) and
+ * gyroscope (TYPE_GYROSCOPE) at SENSOR_DELAY_GAME (~50 Hz). Used to refine
+ * possibleCrash and to detect phoneUsageWhileDriving. Pure-Android, no JNI.
+ *
+ * Crash detection: |a| (m/s²) above {@code crashImpactG} g during a tripActive
+ * window emits {@link Listener#onPossibleCrash}. Combined with the GPS-derived
+ * heuristic in {@link com.marianhello.bgloc.driving.DrivingEventsDetector},
+ * this gives a far higher-confidence signal at low speeds (parking-lot impact)
+ * where GPS alone misses.
+ *
+ * phoneUsageWhileDriving: while {@code tripActive} is true, if the screen turns
+ * on and the user produces touch-shaped jitter on the device for a sustained
+ * window, fires {@link Listener#onPhoneUsageWhileDriving}. Conservative — designed
+ * to avoid false-positives from passenger usage by tying to {@code tripActive}.
+ */
+public class SensorFusionDetector implements SensorEventListener {
+
+    public interface Listener {
+        /** Triggered when |a| exceeds crashImpactG while tripActive. */
+        void onSensorCrash(BackgroundLocation lastLocation, double impactG);
+        /** Screen on + sustained device interaction during tripActive. */
+        void onPhoneUsageWhileDriving(BackgroundLocation lastLocation);
+    }
+
+    public static class Config {
+        public boolean enabled = false;
+        /** Crash threshold in g. 1g = 9.81 m/s². Default 3g. */
+        public double crashImpactG = 3.0;
+        /** Cooldown between repeated crash detections. */
+        public long   crashCooldownMs = 10_000;
+        /** Min sustained gyro+accel jitter window for phoneUsage. */
+        public long   phoneUsageWindowMs = 4_000;
+        /** Cooldown between repeated phone-usage events. */
+        public long   phoneUsageCooldownMs = 60_000;
+    }
+
+    private static final float G = 9.80665f;
+
+    private final Context appContext;
+    private final Listener listener;
+    private final SensorManager sensorManager;
+    private final Sensor linearAccel;
+    private final Sensor gyroscope;
+    private final PowerManager powerManager;
+    private final Handler handler;
+
+    private Config cfg = new Config();
+    private boolean started = false;
+    private boolean tripActive = false;
+    private BackgroundLocation lastLocation;
+
+    private long lastCrashAt = 0L;
+    private long lastPhoneUsageAt = 0L;
+
+    // phoneUsage state
+    private long jitterAboveSince = 0L;
+    private static final double JITTER_GYRO_RAD_S = 0.7;     // ~40 deg/s
+    private static final double JITTER_ACCEL_MPS2 = 0.5;     // small accel, hand movement
+
+    public SensorFusionDetector(Context context, Listener listener) {
+        this.appContext = context.getApplicationContext();
+        this.listener = listener;
+        this.sensorManager = (SensorManager) appContext.getSystemService(Context.SENSOR_SERVICE);
+        this.linearAccel = sensorManager != null ? sensorManager.getDefaultSensor(Sensor.TYPE_LINEAR_ACCELERATION) : null;
+        this.gyroscope = sensorManager != null ? sensorManager.getDefaultSensor(Sensor.TYPE_GYROSCOPE) : null;
+        this.powerManager = (PowerManager) appContext.getSystemService(Context.POWER_SERVICE);
+        this.handler = new Handler(Looper.getMainLooper());
+    }
+
+    public synchronized void setConfig(Config c) {
+        if (c != null) this.cfg = c;
+    }
+
+    public synchronized boolean isAvailable() {
+        return sensorManager != null && linearAccel != null;
+    }
+
+    /** Start sampling sensors. Idempotent. */
+    public synchronized void start() {
+        if (started || !cfg.enabled || sensorManager == null) return;
+        if (linearAccel != null) {
+            sensorManager.registerListener(this, linearAccel, SensorManager.SENSOR_DELAY_GAME, handler);
+        }
+        if (gyroscope != null) {
+            sensorManager.registerListener(this, gyroscope, SensorManager.SENSOR_DELAY_GAME, handler);
+        }
+        started = true;
+    }
+
+    /** Stop sampling. Idempotent. */
+    public synchronized void stop() {
+        if (!started) return;
+        if (sensorManager != null) sensorManager.unregisterListener(this);
+        started = false;
+        jitterAboveSince = 0L;
+    }
+
+    /** Called by detector host whenever the GPS layer marks tripActive on/off. */
+    public synchronized void setTripActive(boolean active) {
+        this.tripActive = active;
+        if (!active) jitterAboveSince = 0L;
+    }
+
+    /** Last known location for event payload. Updated by host. */
+    public synchronized void setLastLocation(BackgroundLocation loc) {
+        this.lastLocation = loc;
+    }
+
+    @Override public void onAccuracyChanged(Sensor sensor, int accuracy) { /* ignore */ }
+
+    @Override
+    public void onSensorChanged(SensorEvent event) {
+        Listener l;
+        Config c;
+        boolean tripActiveNow;
+        BackgroundLocation loc;
+        synchronized (this) {
+            l = this.listener;
+            c = this.cfg;
+            tripActiveNow = this.tripActive;
+            loc = this.lastLocation;
+        }
+        if (l == null || c == null || !c.enabled) return;
+
+        long now = System.currentTimeMillis();
+
+        if (event.sensor.getType() == Sensor.TYPE_LINEAR_ACCELERATION) {
+            float ax = event.values[0], ay = event.values[1], az = event.values[2];
+            double mag = Math.sqrt(ax * ax + ay * ay + az * az);
+            double gMag = mag / G;
+
+            // Crash: high impact during a trip.
+            if (tripActiveNow && c.crashImpactG > 0 && gMag >= c.crashImpactG
+                    && (now - lastCrashAt) >= c.crashCooldownMs) {
+                lastCrashAt = now;
+                l.onSensorCrash(loc, gMag);
+            }
+
+            // Phone usage signal: small accel jitter during trip + screen on.
+            evaluatePhoneUsage(now, mag, /*gyroMag*/ -1, c, l, tripActiveNow, loc);
+        } else if (event.sensor.getType() == Sensor.TYPE_GYROSCOPE) {
+            float gx = event.values[0], gy = event.values[1], gz = event.values[2];
+            double gyroMag = Math.sqrt(gx * gx + gy * gy + gz * gz);
+            evaluatePhoneUsage(now, /*accelMag*/ -1, gyroMag, c, l, tripActiveNow, loc);
+        }
+    }
+
+    private void evaluatePhoneUsage(long now,
+                                    double accelMag,
+                                    double gyroMag,
+                                    Config c,
+                                    Listener l,
+                                    boolean tripActiveNow,
+                                    BackgroundLocation loc) {
+        if (!tripActiveNow) { jitterAboveSince = 0L; return; }
+        if (powerManager == null || !isScreenOn()) { jitterAboveSince = 0L; return; }
+
+        boolean above = (accelMag >= 0 && accelMag >= JITTER_ACCEL_MPS2)
+                || (gyroMag >= 0 && gyroMag >= JITTER_GYRO_RAD_S);
+        if (above) {
+            if (jitterAboveSince == 0L) jitterAboveSince = now;
+            if ((now - jitterAboveSince) >= c.phoneUsageWindowMs
+                    && (now - lastPhoneUsageAt) >= c.phoneUsageCooldownMs) {
+                lastPhoneUsageAt = now;
+                jitterAboveSince = 0L;
+                l.onPhoneUsageWhileDriving(loc);
+            }
+        } else {
+            jitterAboveSince = 0L;
+        }
+    }
+
+    @SuppressWarnings("deprecation")
+    private boolean isScreenOn() {
+        if (powerManager == null) return false;
+        try {
+            // isInteractive added API 20; we target >= 21 elsewhere, but guard anyway.
+            return powerManager.isInteractive();
+        } catch (Throwable t) {
+            return powerManager.isScreenOn();
+        }
+    }
+}