@josuelmm/cordova-background-geolocation 3.1.1 → 4.2.0

package/android/common/src/main/java/com/marianhello/bgloc/data/sqlite/SQLiteOpenHelper.java

@@ -8,6 +8,7 @@ import android.util.Log;
 
 import com.marianhello.bgloc.data.sqlite.SQLiteLocationContract.LocationEntry;
 import com.marianhello.bgloc.data.sqlite.SQLiteConfigurationContract.ConfigurationEntry;
+import com.marianhello.bgloc.data.sqlite.SQLiteSessionContract.SessionEntry;
 
 import java.util.ArrayList;
 
@@ -21,7 +22,7 @@ import static com.marianhello.bgloc.data.sqlite.SQLiteLocationContract.LocationE
 public class SQLiteOpenHelper extends android.database.sqlite.SQLiteOpenHelper {
     private static final String TAG = SQLiteOpenHelper.class.getName();
     public static final String SQLITE_DATABASE_NAME = "cordova_bg_geolocation.db";
-    public static final int DATABASE_VERSION = 19;
+    public static final int DATABASE_VERSION = 20;
 
     public static final String TEXT_TYPE = " TEXT";
     public static final String INTEGER_TYPE = " INTEGER";
@@ -66,6 +67,8 @@ public class SQLiteOpenHelper extends android.database.sqlite.SQLiteOpenHelper {
         execAndLogSql(db, SQL_CREATE_CONFIG_TABLE);
         execAndLogSql(db, SQL_CREATE_LOCATION_TABLE_TIME_IDX);
         execAndLogSql(db, SQL_CREATE_LOCATION_TABLE_BATCH_ID_IDX);
+        execAndLogSql(db, SessionEntry.SQL_CREATE_SESSION_TABLE);
+        execAndLogSql(db, SessionEntry.SQL_CREATE_SESSION_TABLE_TIME_IDX);
     }
 
     @Override
@@ -137,6 +140,9 @@ public class SQLiteOpenHelper extends android.database.sqlite.SQLiteOpenHelper {
                         " ADD COLUMN " + ConfigurationEntry.COLUMN_NAME_SHOW_TIME + INTEGER_TYPE);
                 alterSql.add("ALTER TABLE " + ConfigurationEntry.TABLE_NAME +
                         " ADD COLUMN " + ConfigurationEntry.COLUMN_NAME_SHOW_DISTANCE + INTEGER_TYPE);
+            case 19:
+                alterSql.add(SessionEntry.SQL_CREATE_SESSION_TABLE);
+                alterSql.add(SessionEntry.SQL_CREATE_SESSION_TABLE_TIME_IDX);
 
                 break; // DO NOT FORGET TO MOVE DOWN BREAK ON DB UPGRADE!!!
             default:
@@ -154,6 +160,7 @@ public class SQLiteOpenHelper extends android.database.sqlite.SQLiteOpenHelper {
         // we don't support db downgrade yet, instead we drop table and start over
         execAndLogSql(db, SQL_DROP_LOCATION_TABLE);
         execAndLogSql(db, SQL_DROP_CONFIG_TABLE);
+        execAndLogSql(db, SessionEntry.SQL_DROP_SESSION_TABLE);
         onCreate(db);
     }
 

package/android/common/src/main/java/com/marianhello/bgloc/data/sqlite/SQLiteSessionContract.java

@@ -0,0 +1,74 @@
+package com.marianhello.bgloc.data.sqlite;
+
+import android.provider.BaseColumns;
+
+import static com.marianhello.bgloc.data.sqlite.SQLiteOpenHelper.COMMA_SEP;
+import static com.marianhello.bgloc.data.sqlite.SQLiteOpenHelper.INTEGER_TYPE;
+import static com.marianhello.bgloc.data.sqlite.SQLiteOpenHelper.REAL_TYPE;
+import static com.marianhello.bgloc.data.sqlite.SQLiteOpenHelper.TEXT_TYPE;
+
+/**
+ * Contract for the "session" location table.
+ * Stores all locations for the current recording session (route).
+ * Cleared on startSession() and clearSession(); not cleared when sync succeeds.
+ */
+public final class SQLiteSessionContract {
+
+    public SQLiteSessionContract() {}
+
+    public static abstract class SessionEntry implements BaseColumns {
+        public static final String TABLE_NAME = "location_session";
+        public static final String COLUMN_NAME_NULLABLE = "NULLHACK";
+        public static final String COLUMN_NAME_TIME = "time";
+        public static final String COLUMN_NAME_ACCURACY = "accuracy";
+        public static final String COLUMN_NAME_VERTICAL_ACCURACY = "vertical_accuracy";
+        public static final String COLUMN_NAME_SPEED = "speed";
+        public static final String COLUMN_NAME_BEARING = "bearing";
+        public static final String COLUMN_NAME_ALTITUDE = "altitude";
+        public static final String COLUMN_NAME_LATITUDE = "latitude";
+        public static final String COLUMN_NAME_LONGITUDE = "longitude";
+        public static final String COLUMN_NAME_RADIUS = "radius";
+        public static final String COLUMN_NAME_HAS_ACCURACY = "has_accuracy";
+        public static final String COLUMN_NAME_HAS_VERTICAL_ACCURACY = "has_vertical_accuracy";
+        public static final String COLUMN_NAME_HAS_SPEED = "has_speed";
+        public static final String COLUMN_NAME_HAS_BEARING = "has_bearing";
+        public static final String COLUMN_NAME_HAS_ALTITUDE = "has_altitude";
+        public static final String COLUMN_NAME_HAS_RADIUS = "has_radius";
+        public static final String COLUMN_NAME_PROVIDER = "provider";
+        public static final String COLUMN_NAME_LOCATION_PROVIDER = "service_provider";
+        public static final String COLUMN_NAME_STATUS = "valid";
+        public static final String COLUMN_NAME_BATCH_START_MILLIS = "batch_start";
+        public static final String COLUMN_NAME_MOCK_FLAGS = "mock_flags";
+
+        public static final String SQL_CREATE_SESSION_TABLE =
+                "CREATE TABLE " + SessionEntry.TABLE_NAME + " (" +
+                        SessionEntry._ID + " INTEGER PRIMARY KEY AUTOINCREMENT," +
+                        SessionEntry.COLUMN_NAME_TIME + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_ACCURACY + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_VERTICAL_ACCURACY + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_SPEED + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_BEARING + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_ALTITUDE + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_LATITUDE + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_LONGITUDE + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_RADIUS + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_ACCURACY + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_VERTICAL_ACCURACY + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_SPEED + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_BEARING + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_ALTITUDE + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_RADIUS + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_PROVIDER + TEXT_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_LOCATION_PROVIDER + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_STATUS + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_BATCH_START_MILLIS + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_MOCK_FLAGS + INTEGER_TYPE +
+                        " )";
+
+        public static final String SQL_DROP_SESSION_TABLE =
+                "DROP TABLE IF EXISTS " + SessionEntry.TABLE_NAME;
+
+        public static final String SQL_CREATE_SESSION_TABLE_TIME_IDX =
+                "CREATE INDEX session_time_idx ON " + SessionEntry.TABLE_NAME + " (" + SessionEntry.COLUMN_NAME_TIME + ")";
+    }
+}

package/android/common/src/main/java/com/marianhello/bgloc/data/sqlite/SQLiteSessionLocationDAO.java

@@ -0,0 +1,169 @@
+package com.marianhello.bgloc.data.sqlite;
+
+import android.content.ContentValues;
+import android.content.Context;
+import android.database.Cursor;
+import android.database.sqlite.SQLiteDatabase;
+import com.marianhello.bgloc.data.BackgroundLocation;
+import com.marianhello.bgloc.data.SessionLocationDAO;
+
+import java.util.ArrayList;
+import java.util.Collection;
+
+public class SQLiteSessionLocationDAO implements SessionLocationDAO {
+
+    private static final String PREFS_NAME = "bgloc_session";
+    private static final String KEY_SESSION_ACTIVE = "session_active";
+
+    private final SQLiteDatabase db;
+    private final Context context;
+
+    public SQLiteSessionLocationDAO(Context context) {
+        this.context = context.getApplicationContext();
+        SQLiteOpenHelper helper = SQLiteOpenHelper.getHelper(this.context);
+        this.db = helper.getWritableDatabase();
+    }
+
+    @Override
+    public void startSession() {
+        db.delete(SQLiteSessionContract.SessionEntry.TABLE_NAME, null, null);
+        setSessionActive(true);
+    }
+
+    @Override
+    public void clearSession() {
+        db.delete(SQLiteSessionContract.SessionEntry.TABLE_NAME, null, null);
+        setSessionActive(false);
+    }
+
+    @Override
+    public boolean isSessionActive() {
+        return context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .getBoolean(KEY_SESSION_ACTIVE, false);
+    }
+
+    private void setSessionActive(boolean active) {
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .edit()
+                .putBoolean(KEY_SESSION_ACTIVE, active)
+                .apply();
+    }
+
+    @Override
+    public void persistSessionLocation(BackgroundLocation location) {
+        if (!isSessionActive() || location == null) return;
+        ContentValues values = getContentValues(location);
+        db.insertOrThrow(SQLiteSessionContract.SessionEntry.TABLE_NAME,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_NULLABLE, values);
+    }
+
+    @Override
+    public Collection<BackgroundLocation> getSessionLocations() {
+        Collection<BackgroundLocation> locations = new ArrayList<>();
+        String orderBy = SQLiteSessionContract.SessionEntry.COLUMN_NAME_TIME + " ASC";
+        Cursor cursor = null;
+        try {
+            cursor = db.query(
+                    SQLiteSessionContract.SessionEntry.TABLE_NAME,
+                    queryColumns(),
+                    null, null, null, null, orderBy);
+            while (cursor.moveToNext()) {
+                locations.add(hydrate(cursor));
+            }
+        } finally {
+            if (cursor != null) cursor.close();
+        }
+        return locations;
+    }
+
+    @Override
+    public int getSessionLocationsCount() {
+        Cursor cursor = null;
+        try {
+            cursor = db.rawQuery("SELECT COUNT(*) FROM " + SQLiteSessionContract.SessionEntry.TABLE_NAME, null);
+            return cursor.moveToFirst() ? cursor.getInt(0) : 0;
+        } finally {
+            if (cursor != null) cursor.close();
+        }
+    }
+
+    private BackgroundLocation hydrate(Cursor c) {
+        BackgroundLocation l = new BackgroundLocation(c.getString(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_PROVIDER)));
+        l.setTime(c.getLong(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_TIME)));
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ACCURACY)) == 1) {
+            l.setAccuracy(c.getFloat(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_ACCURACY)));
+        }
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_VERTICAL_ACCURACY)) == 1) {
+            l.setVerticalAccuracy(c.getFloat(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_VERTICAL_ACCURACY)));
+        }
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_SPEED)) == 1) {
+            l.setSpeed(c.getFloat(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_SPEED)));
+        }
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_BEARING)) == 1) {
+            l.setBearing(c.getFloat(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_BEARING)));
+        }
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ALTITUDE)) == 1) {
+            l.setAltitude(c.getDouble(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_ALTITUDE)));
+        }
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_RADIUS)) == 1) {
+            l.setRadius(c.getFloat(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_RADIUS)));
+        }
+        l.setLatitude(c.getDouble(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LATITUDE)));
+        l.setLongitude(c.getDouble(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LONGITUDE)));
+        l.setLocationProvider(c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LOCATION_PROVIDER)));
+        l.setLocationId(c.getLong(c.getColumnIndex(SQLiteSessionContract.SessionEntry._ID)));
+        l.setMockFlags(c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_MOCK_FLAGS)));
+        return l;
+    }
+
+    private ContentValues getContentValues(BackgroundLocation l) {
+        ContentValues values = new ContentValues();
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_PROVIDER, l.getProvider());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_TIME, l.getTime());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_ACCURACY, l.getAccuracy());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_VERTICAL_ACCURACY, l.getVerticalAccuracy());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_SPEED, l.getSpeed());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_BEARING, l.getBearing());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_ALTITUDE, l.getAltitude());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_RADIUS, l.getRadius());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LATITUDE, l.getLatitude());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LONGITUDE, l.getLongitude());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ACCURACY, l.hasAccuracy() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_VERTICAL_ACCURACY, l.hasVerticalAccuracy() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_SPEED, l.hasSpeed() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_BEARING, l.hasBearing() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ALTITUDE, l.hasAltitude() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_RADIUS, l.hasRadius() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LOCATION_PROVIDER, l.getLocationProvider());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_STATUS, 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_BATCH_START_MILLIS, 0L);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_MOCK_FLAGS, l.getMockFlags());
+        return values;
+    }
+
+    private String[] queryColumns() {
+        return new String[]{
+                SQLiteSessionContract.SessionEntry._ID,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_PROVIDER,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_TIME,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_ACCURACY,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_VERTICAL_ACCURACY,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_SPEED,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_BEARING,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_ALTITUDE,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_RADIUS,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_LATITUDE,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_LONGITUDE,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ACCURACY,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_VERTICAL_ACCURACY,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_SPEED,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_BEARING,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ALTITUDE,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_RADIUS,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_LOCATION_PROVIDER,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_STATUS,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_BATCH_START_MILLIS,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_MOCK_FLAGS
+        };
+    }
+}

package/android/common/src/main/java/com/marianhello/bgloc/driving/DrivingEventsDetector.java

@@ -0,0 +1,265 @@
+package com.marianhello.bgloc.driving;
+
+import com.marianhello.bgloc.data.BackgroundLocation;
+
+/**
+ * v4.0 Phase 6 — Driver insights state machine (GPS-only).
+ *
+ * Pure-Java helper, no Android imports. Hosted by {@code LocationServiceImpl}, which
+ * feeds it every received location and surfaces emitted events via the plugin
+ * {@code MSG_ON_*} broadcast pipeline.
+ *
+ * Heuristics:
+ *   moving   = speed > minMovingSpeed
+ *   stopped  = !moving for stoppedDuration ms
+ *   tripStart = stopped → moving with speed >= minTripSpeed sustained for minTripDuration ms
+ *   tripEnd  = moving → stopped (after a tripStart)
+ *   speeding = first crossing above speedLimit (km/h); rearms on drop below
+ *
+ * Sensor-fusion events (hardBrake / sharpTurn / possibleCrash) are intentionally NOT
+ * implemented in this class. They require linear acceleration + gyroscope sampling and
+ * are planned for v4.1 in a separate {@code SensorFusionDetector}.
+ */
+public class DrivingEventsDetector {
+
+    public interface Listener {
+        void onMoving(BackgroundLocation location);
+        void onStopped(BackgroundLocation location);
+        void onTripStart(BackgroundLocation location);
+        /** distance in meters, durationMs in milliseconds. */
+        void onTripEnd(BackgroundLocation location, double distance, long durationMs);
+        void onSpeeding(BackgroundLocation location, double speedKmh, double limitKmh);
+        void onProviderChange(String provider);
+        // v4.1 GPS-derived driving events
+        /** GPS-derived deceleration (m/s²). Negative number, more negative = harder brake. */
+        void onHardBrake(BackgroundLocation location, double decelMps2);
+        /** GPS-derived acceleration (m/s²). */
+        void onRapidAcceleration(BackgroundLocation location, double accelMps2);
+        /** Bearing change rate (deg/s). */
+        void onSharpTurn(BackgroundLocation location, double degPerSec);
+        /** Velocity drop in km/h within {@code crashWindowMs} while tripActive. */
+        void onPossibleCrash(BackgroundLocation location, double velocityDropKmh);
+    }
+
+    public static class Config {
+        public boolean enabled = false;
+        public double speedLimitKmh = 0;        // 0 disables speeding
+        public double minMovingSpeedMps = 1.0;  // ~3.6 km/h
+        public long stoppedDurationMs = 60_000;
+        public double minTripSpeedMps = 3.0;    // ~10.8 km/h
+        public long minTripDurationMs = 30_000;
+        // v4.1 GPS-derived driving events. 0 disables each one.
+        public double hardBrakeMps2 = 3.5;      // -m/s² threshold (positive value)
+        public double rapidAccelMps2 = 3.5;     // m/s² threshold
+        public double sharpTurnDegPerSec = 30;  // deg/sec, requires speed > 5 m/s
+        public double crashImpactKmh = 25;      // velocity drop within crashWindow
+        public long   crashWindowMs = 2_000;    // window to evaluate the velocity drop
+    }
+
+    private final Listener listener;
+    private Config cfg = new Config();
+
+    // State
+    private boolean isMoving = false;
+    private boolean tripActive = false;
+    private long tripStartedAt = 0;
+    private double tripDistanceMeters = 0;
+    private double tripStartLat, tripStartLon;
+    private boolean hasTripStartCoord = false;
+
+    private long aboveTripSpeedSince = 0;   // first sample with speed >= minTripSpeed
+    private long belowMovingSinceMs = 0;    // first sample with speed < minMovingSpeed
+
+    private boolean wasSpeeding = false;
+    private String lastProvider;
+
+    private double prevLat, prevLon;
+    private boolean hasPrev = false;
+
+    // v4.1 GPS-derived deltas
+    private double prevSpeedMps = 0.0;
+    private long   prevSpeedAt = 0L;
+    private double prevBearingDeg = 0.0;
+    private boolean hasPrevBearing = false;
+    private long   prevBearingAt = 0L;
+    /** Cooldown so we don't refire the same event on every fix in a sustained brake. */
+    private long lastHardBrakeAt = 0L, lastRapidAccelAt = 0L, lastSharpTurnAt = 0L, lastCrashAt = 0L;
+    private static final long DRIVING_EVENT_COOLDOWN_MS = 4_000L;
+
+    public DrivingEventsDetector(Listener listener) {
+        this.listener = listener;
+    }
+
+    public synchronized void setConfig(Config c) {
+        if (c != null) this.cfg = c;
+    }
+
+    /** Reset internal state. Called when service stops. */
+    public synchronized void reset() {
+        prevSpeedMps = 0.0;
+        prevSpeedAt = 0L;
+        prevBearingDeg = 0.0;
+        hasPrevBearing = false;
+        prevBearingAt = 0L;
+        lastHardBrakeAt = lastRapidAccelAt = lastSharpTurnAt = lastCrashAt = 0L;
+        isMoving = false;
+        tripActive = false;
+        tripStartedAt = 0;
+        tripDistanceMeters = 0;
+        hasTripStartCoord = false;
+        aboveTripSpeedSince = 0;
+        belowMovingSinceMs = 0;
+        wasSpeeding = false;
+        lastProvider = null;
+        hasPrev = false;
+    }
+
+    public synchronized void onLocation(BackgroundLocation loc) {
+        if (!cfg.enabled || loc == null) return;
+        long now = System.currentTimeMillis();
+        double speed = loc.hasSpeed() ? loc.getSpeed() : 0.0;
+
+        // Provider change
+        String provider = loc.getProvider();
+        if (provider != null && !provider.equals(lastProvider)) {
+            lastProvider = provider;
+            if (listener != null) listener.onProviderChange(provider);
+        }
+
+        // Distance accumulator (very simple: planar haversine approximation via
+        // Location.distanceBetween is not used here to keep this class platform-free;
+        // consumer can swap to BackgroundLocation.distanceTo in onTripEnd if desired).
+        double curLat = loc.getLatitude();
+        double curLon = loc.getLongitude();
+        if (hasPrev && tripActive) {
+            tripDistanceMeters += haversineMeters(prevLat, prevLon, curLat, curLon);
+        }
+        prevLat = curLat;
+        prevLon = curLon;
+        hasPrev = true;
+
+        // Moving / stopped state
+        boolean nowMoving = speed >= cfg.minMovingSpeedMps;
+        if (nowMoving) {
+            belowMovingSinceMs = 0;
+            if (!isMoving) {
+                isMoving = true;
+                if (listener != null) listener.onMoving(loc);
+            }
+            // Trip start arming
+            if (!tripActive) {
+                if (speed >= cfg.minTripSpeedMps) {
+                    if (aboveTripSpeedSince == 0) aboveTripSpeedSince = now;
+                    if (now - aboveTripSpeedSince >= cfg.minTripDurationMs) {
+                        tripActive = true;
+                        tripStartedAt = now;
+                        tripDistanceMeters = 0;
+                        tripStartLat = curLat;
+                        tripStartLon = curLon;
+                        hasTripStartCoord = true;
+                        if (listener != null) listener.onTripStart(loc);
+                    }
+                } else {
+                    aboveTripSpeedSince = 0;
+                }
+            }
+        } else {
+            aboveTripSpeedSince = 0;
+            if (belowMovingSinceMs == 0) belowMovingSinceMs = now;
+            if (isMoving && (now - belowMovingSinceMs) >= cfg.stoppedDurationMs) {
+                isMoving = false;
+                if (listener != null) listener.onStopped(loc);
+                if (tripActive) {
+                    long durMs = now - tripStartedAt;
+                    double dist = tripDistanceMeters;
+                    tripActive = false;
+                    if (listener != null) listener.onTripEnd(loc, dist, durMs);
+                }
+            }
+        }
+
+        // Speeding (km/h)
+        if (cfg.speedLimitKmh > 0) {
+            double kmh = speed * 3.6;
+            if (kmh > cfg.speedLimitKmh) {
+                if (!wasSpeeding) {
+                    wasSpeeding = true;
+                    if (listener != null) listener.onSpeeding(loc, kmh, cfg.speedLimitKmh);
+                }
+            } else {
+                // Rearm: emit again on next crossing.
+                wasSpeeding = false;
+            }
+        }
+
+        // v4.1 GPS-derived driving events (only meaningful during an active trip)
+        if (tripActive && prevSpeedAt > 0) {
+            long dtMs = now - prevSpeedAt;
+            if (dtMs > 0 && dtMs <= 5_000) {
+                double dt = dtMs / 1000.0;
+                double dv = speed - prevSpeedMps; // m/s
+                double accel = dv / dt;            // m/s²
+
+                if (cfg.hardBrakeMps2 > 0
+                        && accel <= -cfg.hardBrakeMps2
+                        && (now - lastHardBrakeAt) >= DRIVING_EVENT_COOLDOWN_MS) {
+                    lastHardBrakeAt = now;
+                    if (listener != null) listener.onHardBrake(loc, accel);
+                }
+                if (cfg.rapidAccelMps2 > 0
+                        && accel >= cfg.rapidAccelMps2
+                        && (now - lastRapidAccelAt) >= DRIVING_EVENT_COOLDOWN_MS) {
+                    lastRapidAccelAt = now;
+                    if (listener != null) listener.onRapidAcceleration(loc, accel);
+                }
+
+                // Possible crash: sustained velocity drop greater than crashImpactKmh in <= crashWindow.
+                if (cfg.crashImpactKmh > 0 && dtMs <= cfg.crashWindowMs) {
+                    double dropKmh = (prevSpeedMps - speed) * 3.6; // positive when slowing down
+                    if (dropKmh >= cfg.crashImpactKmh
+                            && speed < 1.5 // ended near stop
+                            && prevSpeedMps * 3.6 >= cfg.crashImpactKmh
+                            && (now - lastCrashAt) >= DRIVING_EVENT_COOLDOWN_MS) {
+                        lastCrashAt = now;
+                        if (listener != null) listener.onPossibleCrash(loc, dropKmh);
+                    }
+                }
+            }
+        }
+
+        // Sharp turn (bearing change rate) — requires meaningful speed to avoid GPS jitter.
+        if (cfg.sharpTurnDegPerSec > 0 && loc.hasBearing() && speed >= 5.0 && hasPrevBearing) {
+            long dtMs = now - prevBearingAt;
+            if (dtMs > 0 && dtMs <= 5_000) {
+                double bearing = loc.getBearing();
+                double diff = Math.abs(bearing - prevBearingDeg);
+                if (diff > 180) diff = 360 - diff;
+                double rate = diff * 1000.0 / dtMs;
+                if (rate >= cfg.sharpTurnDegPerSec
+                        && (now - lastSharpTurnAt) >= DRIVING_EVENT_COOLDOWN_MS) {
+                    lastSharpTurnAt = now;
+                    if (listener != null) listener.onSharpTurn(loc, rate);
+                }
+            }
+            prevBearingDeg = loc.getBearing();
+            prevBearingAt = now;
+        } else if (loc.hasBearing()) {
+            prevBearingDeg = loc.getBearing();
+            prevBearingAt = now;
+            hasPrevBearing = true;
+        }
+
+        prevSpeedMps = speed;
+        prevSpeedAt = now;
+    }
+
+    private static double haversineMeters(double lat1, double lon1, double lat2, double lon2) {
+        double R = 6371000.0;
+        double dLat = Math.toRadians(lat2 - lat1);
+        double dLon = Math.toRadians(lon2 - lon1);
+        double a = Math.sin(dLat/2) * Math.sin(dLat/2)
+                + Math.cos(Math.toRadians(lat1)) * Math.cos(Math.toRadians(lat2))
+                * Math.sin(dLon/2) * Math.sin(dLon/2);
+        return 2 * R * Math.asin(Math.sqrt(a));
+    }
+}

package/android/common/src/main/java/com/marianhello/bgloc/http/UrlTemplateResolver.java

@@ -0,0 +1,115 @@
+package com.marianhello.bgloc.http;
+
+import com.marianhello.bgloc.data.BackgroundLocation;
+
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.Locale;
+import java.util.Map;
+import java.util.TimeZone;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Resolves placeholders like {lat}, {lon}, {timestamp_iso}, {device_id}, ...
+ * in a URL template using a single BackgroundLocation and an optional queryParams map.
+ *
+ * Placeholders not found in the location/queryParams are left as-is so that
+ * partial templates (e.g. only static keys for batch mode) keep working.
+ *
+ * Usage:
+ *   String url = UrlTemplateResolver.resolve(template, location, queryParams);
+ *   // location may be null for batch mode (only queryParams keys are resolved).
+ */
+public final class UrlTemplateResolver {
+
+    private static final Pattern PLACEHOLDER = Pattern.compile("\\{([a-zA-Z0-9_]+)\\}");
+
+    private UrlTemplateResolver() { /* no instances */ }
+
+    public static String resolve(String template, BackgroundLocation location, Map<String, ?> queryParams) {
+        if (template == null || template.isEmpty()) return template;
+        Map<String, String> ctx = buildContext(location, queryParams);
+        Matcher m = PLACEHOLDER.matcher(template);
+        StringBuffer sb = new StringBuffer(template.length());
+        while (m.find()) {
+            String key = m.group(1);
+            String value = ctx.get(key);
+            if (value != null) {
+                m.appendReplacement(sb, Matcher.quoteReplacement(urlEncode(value)));
+            } else {
+                // Leave placeholder as-is if no value available.
+                m.appendReplacement(sb, Matcher.quoteReplacement(m.group(0)));
+            }
+        }
+        m.appendTail(sb);
+        return sb.toString();
+    }
+
+    public static boolean hasPlaceholders(String template) {
+        if (template == null) return false;
+        return PLACEHOLDER.matcher(template).find();
+    }
+
+    private static Map<String, String> buildContext(BackgroundLocation loc, Map<String, ?> queryParams) {
+        Map<String, String> ctx = new HashMap<String, String>();
+
+        // queryParams first so location-derived values can override if user wants
+        if (queryParams != null) {
+            for (Map.Entry<String, ?> e : queryParams.entrySet()) {
+                if (e.getValue() != null) {
+                    ctx.put(e.getKey(), String.valueOf(e.getValue()));
+                }
+            }
+        }
+
+        if (loc != null) {
+            ctx.put("latitude", String.valueOf(loc.getLatitude()));
+            ctx.put("longitude", String.valueOf(loc.getLongitude()));
+            ctx.put("lat", String.valueOf(loc.getLatitude()));
+            ctx.put("lon", String.valueOf(loc.getLongitude()));
+
+            long timeMs = loc.getTime();
+            ctx.put("time", String.valueOf(timeMs));
+            ctx.put("timestamp", String.valueOf(timeMs));
+            ctx.put("timestamp_iso", isoUtc(timeMs));
+
+            if (loc.hasSpeed()) ctx.put("speed", String.valueOf(loc.getSpeed()));
+            if (loc.hasAltitude()) ctx.put("altitude", String.valueOf(loc.getAltitude()));
+            if (loc.hasBearing()) ctx.put("bearing", String.valueOf(loc.getBearing()));
+            if (loc.hasAccuracy()) ctx.put("accuracy", String.valueOf(loc.getAccuracy()));
+
+            if (loc.getProvider() != null) ctx.put("provider", loc.getProvider());
+            // is_moving derived from speed when available (>0.5 m/s ~ walking pace).
+            if (loc.hasSpeed()) {
+                ctx.put("is_moving", loc.getSpeed() > 0.5f ? "true" : "false");
+            }
+            // {activity} is not produced by BackgroundLocation by default; the user can supply
+            // a value via queryParams (already populated above).
+        }
+
+        return ctx;
+    }
+
+    /**
+     * URL-encode a placeholder value for use in URL paths and query strings.
+     * Spaces become %20, not + (which is form-encoding).
+     */
+    private static String urlEncode(String s) {
+        if (s == null) return "";
+        try {
+            String enc = java.net.URLEncoder.encode(s, "UTF-8");
+            // URLEncoder uses application/x-www-form-urlencoded; convert "+" back to "%20" for URL safety.
+            return enc.replace("+", "%20");
+        } catch (Exception e) {
+            return s;
+        }
+    }
+
+    private static String isoUtc(long ms) {
+        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'", Locale.US);
+        sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
+        return sdf.format(new Date(ms));
+    }
+}