Skip to content

Colota - Android GPS Location tracker

fix: backdate anchor point timestamp to prevent phantom location jump on zone exit Closes #258

Max Dietrich53fa639b79df
diff --git a/apps/docs/docs/api-reference.md b/apps/docs/docs/api-reference.md
index bc19edcf..19f5a677 100644
--- a/apps/docs/docs/api-reference.md
+++ b/apps/docs/docs/api-reference.md
@@ -69,10 +69,11 @@ All field names are [customizable](/docs/configuration/field-mapping).
### Anchor Points
-When entering or exiting a [pause zone](/docs/guides/geofencing#anchor-points), Colota sends a synthetic location at the geofence center. These payloads look like regular locations but have specific characteristics:
+When exiting a [pause zone](/docs/guides/geofencing#anchor-points), Colota sends a synthetic location at the geofence center. These payloads look like regular locations but have specific characteristics:
- `lat`/`lon` are the geofence center coordinates (not the actual GPS position)
- `acc` is set to the geofence radius in meters
+- `tst` is set to 1 second before the first real GPS fix after leaving the zone
- `alt`, `vel`, and `bear` are not included
- `batt` and `bs` reflect the current battery state
diff --git a/apps/docs/docs/development/architecture.md b/apps/docs/docs/development/architecture.md
index 1ed8ad44..c620b7be 100644
--- a/apps/docs/docs/development/architecture.md
+++ b/apps/docs/docs/development/architecture.md
@@ -88,7 +88,7 @@ An Android foreground service that runs continuously for GPS tracking. Manages:
- GPS location capture via the `LocationProvider` abstraction
- Pause zone detection (geofencing)
- Geofence entry delay - keeps recording for 3.5× the tracking interval before pausing on zone entry, logging real arrival points for backends like GeoPulse
-- Anchor points - a synthetic location saved on zone exit as a clean start point for the departing trip
+- Anchor points - a synthetic location saved on zone exit as a clean start point for the departing trip, timestamped 1s before the first real GPS fix
- Battery critical shutdown (below 5% while discharging)
- Location accuracy filtering
- Stationary detection - pauses GPS after 60s without movement and arms `MotionDetector` to resume on motion (suspended during entry delay and inside geofence pause zones)
diff --git a/apps/docs/docs/guides/geofencing.md b/apps/docs/docs/guides/geofencing.md
index 6269e8a6..0ae26aa0 100644
--- a/apps/docs/docs/guides/geofencing.md
+++ b/apps/docs/docs/guides/geofencing.md
@@ -61,4 +61,4 @@ When both **WiFi** and **motionless** pause are enabled, GPS only resumes when *
## Anchor Points
-When you exit a pause zone, Colota saves a synthetic location at the geofence center. This gives your new trip a clean start point rather than somewhere mid-road where GPS first locks in. Anchor points use the zone radius as their accuracy value and are saved and synced like regular locations.
+When you exit a pause zone, Colota saves a synthetic location at the geofence center. This gives your new trip a clean start point rather than somewhere mid-road where GPS first locks in. Anchor points use the zone radius as their accuracy value and are timestamped 1 second before the first real GPS fix after leaving the zone, ensuring correct chronological order.
diff --git a/apps/mobile/android/app/src/main/java/com/colota/service/LocationForegroundService.kt b/apps/mobile/android/app/src/main/java/com/colota/service/LocationForegroundService.kt
index 9ea31740..f2d980cb 100644
--- a/apps/mobile/android/app/src/main/java/com/colota/service/LocationForegroundService.kt
+++ b/apps/mobile/android/app/src/main/java/com/colota/service/LocationForegroundService.kt
@@ -780,16 +780,18 @@ class LocationForegroundService : Service() {
return null
}
+ val lastFix = lastKnownLocation
+ val anchorTimeMs = if (lastFix != null) lastFix.time - 1000 else System.currentTimeMillis()
+ val anchorTimeSec = anchorTimeMs / 1000
+
val (battery, batteryStatus) = deviceInfoHelper.getCachedBatteryStatus()
- val nowMs = System.currentTimeMillis()
- val timestampSec = nowMs / 1000
val currentFieldMap = fieldMap ?: emptyMap()
val syntheticLocation = android.location.Location("geofence").apply {
latitude = geofence.lat
longitude = geofence.lon
accuracy = geofence.radius.toFloat()
- time = nowMs
+ time = anchorTimeMs
}
return serviceScope?.launch {
@@ -802,7 +804,7 @@ class LocationForegroundService : Service() {
bearing = null,
battery = battery,
battery_status = batteryStatus,
- timestamp = timestampSec,
+ timestamp = anchorTimeSec,
endpoint = config.endpoint
)
@@ -812,7 +814,7 @@ class LocationForegroundService : Service() {
batteryStatus,
// emptyMap() keeps internal field names (lat/lon/vel/bear/...) so buildTraccarJsonPayload can read them directly
if (config.apiFormat == NetworkManager.FORMAT_TRACCAR_JSON) emptyMap() else currentFieldMap,
- timestampSec,
+ anchorTimeSec,
customFields
)
diff --git a/apps/mobile/android/app/src/test/java/com/Colota/service/LocationForegroundServiceTest.kt b/apps/mobile/android/app/src/test/java/com/Colota/service/LocationForegroundServiceTest.kt
index 0e27e480..657d017b 100644
--- a/apps/mobile/android/app/src/test/java/com/Colota/service/LocationForegroundServiceTest.kt
+++ b/apps/mobile/android/app/src/test/java/com/Colota/service/LocationForegroundServiceTest.kt
@@ -770,6 +770,33 @@ class LocationForegroundServiceTest {
) }
}
+ @Test
+ fun `anchor point timestamp is 1s before lastKnownLocation`() = testScope.runTest {
+ val location = mockLocation(lat = 52.1, lon = 13.1)
+ every { location.time } returns 1774863384000L // 09:36:24
+
+ setField("lastKnownLocation", location)
+ setField("insidePauseZone", true)
+ setField("currentZoneName", "Home")
+ setField("currentZoneGeofence", homeGeofence)
+
+ invokeExitPauseZone()
+
+ val expectedTimestamp = (1774863384000L - 1000L) / 1000L
+ verify { dbHelper.saveLocation(
+ latitude = homeGeofence.lat,
+ longitude = homeGeofence.lon,
+ accuracy = homeGeofence.radius,
+ altitude = null,
+ speed = null,
+ bearing = null,
+ battery = 80,
+ battery_status = 2,
+ timestamp = expectedTimestamp,
+ endpoint = "https://example.com"
+ ) }
+ }
+
@Test
fun `exitPauseZone skips anchor when no stored geofence`() = testScope.runTest {
setField("insidePauseZone", true)