Colota - Android GPS Location tracker
Fix/battery stop while paused (#453)
Max Dietrich7c34b31ae3ef
diff --git a/apps/docs/docs/development/architecture.md b/apps/docs/docs/development/architecture.mdindex bc560ee5..332e4a4a 100644--- a/apps/docs/docs/development/architecture.md+++ b/apps/docs/docs/development/architecture.md@@ -150,7 +150,7 @@ An Android foreground service that runs continuously for GPS tracking. Manages:- 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, timestamped 1s before the first real GPS fix-- Battery critical shutdown (below 5% while discharging)+- Battery critical shutdown (below 5% while unplugged), detected via a battery-broadcast receiver so it fires even while GPS is paused in a zone- Location accuracy filtering- Stationary detection - pauses GPS after 60s without movement; resume is driven by the shared `MotionStateDetector` (accelerometer variance, with SIG_MOTION as a fast-path for sharp wake events). Suspended during entry delay and inside geofence pause zones.- Queuing data for server syncdiff --git a/apps/mobile/android/app/src/main/java/com/colota/service/BatteryMonitor.kt b/apps/mobile/android/app/src/main/java/com/colota/service/BatteryMonitor.ktnew file mode 100644index 00000000..d448c7cc--- /dev/null+++ b/apps/mobile/android/app/src/main/java/com/colota/service/BatteryMonitor.kt@@ -0,0 +1,63 @@+/**+ * Copyright (C) 2026 Max Dietrich+ * Licensed under the GNU AGPLv3. See LICENSE in the project root for details.+ */++package com.Colota.service++import android.content.BroadcastReceiver+import android.content.Context+import android.content.Intent+import android.content.IntentFilter+import androidx.core.content.ContextCompat+import com.Colota.util.AppLogger+import com.Colota.util.DeviceInfoHelper++/**+ * Fires [onCritical] when the battery drops below the critical threshold while unplugged.+ *+ * Watches ACTION_BATTERY_CHANGED instead of checking on each GPS fix, so the stop still happens+ * while a zone pause has GPS turned off. Deep Doze batches the broadcast, so a crossing while+ * paused may only be caught at the next maintenance window.+ */+class BatteryMonitor(+ private val context: Context,+ private val deviceInfoHelper: DeviceInfoHelper,+ private val onCritical: () -> Unit,+) {+ private val receiver = object : BroadcastReceiver() {+ override fun onReceive(context: Context?, intent: Intent?) {+ if (deviceInfoHelper.isBatteryCritical()) onCritical()+ }+ }++ private var registered = false++ /** Idempotent. The sticky broadcast is delivered on register, so starting already below the+ * threshold stops right away. */+ fun start() {+ if (registered) return+ ContextCompat.registerReceiver(+ context,+ receiver,+ IntentFilter(Intent.ACTION_BATTERY_CHANGED),+ ContextCompat.RECEIVER_NOT_EXPORTED+ )+ registered = true+ AppLogger.d(TAG, "Battery monitor registered")+ }++ fun stop() {+ if (!registered) return+ registered = false+ try {+ context.unregisterReceiver(receiver)+ } catch (e: IllegalArgumentException) {+ AppLogger.w(TAG, "Battery monitor already unregistered: ${e.message}")+ }+ }++ companion object {+ private const val TAG = "BatteryMonitor"+ }+}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.ktindex 6bbed6e8..66f8f6bc 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@@ -57,6 +57,7 @@ class LocationForegroundService : Service() {private lateinit var profileHelper: ProfileHelperprivate lateinit var profileManager: ProfileManagerprivate lateinit var conditionMonitor: ConditionMonitor+ private lateinit var batteryMonitor: BatteryMonitor// ── Service infrastructure ──@Volatile private var serviceScope: CoroutineScope? = null@@ -67,6 +68,10 @@ class LocationForegroundService : Service() {@Volatile private var motionDetector: MotionStateDetector? = null@Volatile private var lastKnownLocation: Location? = null+ /** Re-entry guard for stopForegroundServiceWithReason: the battery monitor can fire again+ * before onDestroy unregisters it. */+ @Volatile private var isStopping = false+/** Debounces the burst of PROVIDERS_CHANGED broadcasts when system Location toggles (one per provider). */@Volatile private var lastBroadcastLocationEnabled: Boolean = true@@ -180,6 +185,7 @@ class LocationForegroundService : Service() {notificationManager = getSystemService(NOTIFICATION_SERVICE) as NotificationManagerdbHelper = DatabaseHelper.getInstance(this)deviceInfoHelper = DeviceInfoHelper(this)+ batteryMonitor = BatteryMonitor(this, deviceInfoHelper) { onBatteryCritical() }lastBroadcastLocationEnabled = deviceInfoHelper.isLocationEnabled()networkManager = NetworkManager(this)geofenceHelper = GeofenceHelper(this)@@ -302,6 +308,7 @@ class LocationForegroundService : Service() {dbHelper.saveSetting(SettingsKeys.TRACKING_ENABLED, "true")dbHelper.saveSetting(SettingsKeys.STOPPED_BY_BATTERY, "false")BatteryRecoveryScheduler.cancel(this)+ batteryMonitor.start()}when (action) {@@ -384,6 +391,7 @@ class LocationForegroundService : Service() {cancelHeartbeat()unregisterLocationProvidersReceiver()unregisterDebugMotionReceiver()+ batteryMonitor.stop()conditionMonitor.stop()stopLocationUpdates()syncManager.stopPeriodicSync()@@ -417,7 +425,7 @@ class LocationForegroundService : Service() {locationUpdateCallback = callbacklastFixAtMs = SystemClock.elapsedRealtime()- if (deviceInfoHelper.isBatteryCritical(threshold = 5)) {+ if (deviceInfoHelper.isBatteryCritical()) {val (level, _) = deviceInfoHelper.getCachedBatteryStatus()AppLogger.d(TAG, "Battery critical ($level%) and unplugged - stopping service")stopForegroundServiceWithReason("Battery below 5% - tracking paused", stoppedByBattery = true)@@ -701,12 +709,6 @@ class LocationForegroundService : Service() {val (battery, batteryStatus) = deviceInfoHelper.getCachedBatteryStatus()- if (deviceInfoHelper.isBatteryCritical()) {- AppLogger.d(TAG, "Battery critical ($battery%) during tracking - stopping")- stopForegroundServiceWithReason("Battery below 5% - tracking paused", stoppedByBattery = true)- return- }-val timestampSec = location.time / 1000serviceScope?.launch {@@ -1110,7 +1112,15 @@ class LocationForegroundService : Service() {)}+ /** Fired by [batteryMonitor] on a critical-battery broadcast. */+ private fun onBatteryCritical() {+ AppLogger.i(TAG, "Battery critical and unplugged - stopping (battery monitor)")+ stopForegroundServiceWithReason("Battery below 5% - tracking paused", stoppedByBattery = true)+ }+private fun stopForegroundServiceWithReason(reason: String, stoppedByBattery: Boolean = false) {+ if (isStopping) return+ isStopping = trueAppLogger.i(TAG, "Stopping: $reason")// Reset profile indicator in JS UIdiff --git a/apps/mobile/android/app/src/main/java/com/colota/util/DeviceInfoHelper.kt b/apps/mobile/android/app/src/main/java/com/colota/util/DeviceInfoHelper.ktindex a805d8f1..7e825303 100644--- a/apps/mobile/android/app/src/main/java/com/colota/util/DeviceInfoHelper.kt+++ b/apps/mobile/android/app/src/main/java/com/colota/util/DeviceInfoHelper.kt@@ -34,6 +34,9 @@ class DeviceInfoHelper(private val context: Context) {companion object {private const val TAG = "DeviceInfoHelper"++ /** Battery percentage below which tracking stops to preserve the remaining charge. */+ const val CRITICAL_BATTERY_PERCENT = 5}fun getDeviceInfo(): WritableMap {@@ -53,8 +56,8 @@ class DeviceInfoHelper(private val context: Context) {fun getCachedBatteryStatus(): Pair<Int, Int> = batteryCache.get()fun getBatteryStatus(): Pair<Int, Int> {- val snap = readBatterySticky()- return Pair(snap.level, snap.status)+ val battery = readBatterySticky()+ return Pair(battery.level, battery.status)}fun getBatteryStatusString(): String {@@ -62,9 +65,9 @@ class DeviceInfoHelper(private val context: Context) {return "$level% (${BatteryStatus.toDisplayString(status)})"}- fun isBatteryCritical(threshold: Int = 5): Boolean {- val (level, status) = getCachedBatteryStatus()- return level < threshold && status == BatteryStatus.DISCHARGING+ fun isBatteryCritical(threshold: Int = CRITICAL_BATTERY_PERCENT): Boolean {+ val battery = readBatterySticky()+ return battery.level < threshold && !battery.isPlugged}/** True when device is connected to any power source (AC, USB, wireless). */diff --git a/apps/mobile/android/app/src/test/java/com/Colota/service/BatteryMonitorTest.kt b/apps/mobile/android/app/src/test/java/com/Colota/service/BatteryMonitorTest.ktnew file mode 100644index 00000000..3ccd2332--- /dev/null+++ b/apps/mobile/android/app/src/test/java/com/Colota/service/BatteryMonitorTest.kt@@ -0,0 +1,82 @@+package com.Colota.service++import android.content.BroadcastReceiver+import android.content.Context+import android.content.Intent+import com.Colota.util.AppLogger+import com.Colota.util.DeviceInfoHelper+import io.mockk.*+import org.junit.After+import org.junit.Assert.assertEquals+import org.junit.Before+import org.junit.Test++/**+ * BatteryMonitor fires the critical callback from the ACTION_BATTERY_CHANGED broadcast+ * (not the GPS stream), and register/unregister are idempotent.+ */+class BatteryMonitorTest {++ private lateinit var context: Context+ private lateinit var deviceInfoHelper: DeviceInfoHelper+ private var criticalCount = 0+ private lateinit var monitor: BatteryMonitor++ @Before+ fun setUp() {+ context = mockk(relaxed = true)+ deviceInfoHelper = mockk()+ criticalCount = 0+ monitor = BatteryMonitor(context, deviceInfoHelper) { criticalCount++ }++ mockkObject(AppLogger)+ every { AppLogger.d(any(), any()) } just Runs+ every { AppLogger.w(any(), any()) } just Runs+ }++ @After+ fun tearDown() {+ unmockkObject(AppLogger)+ }++ private fun fireBatteryBroadcast() {+ val field = BatteryMonitor::class.java.getDeclaredField("receiver").apply { isAccessible = true }+ val receiver = field.get(monitor) as BroadcastReceiver+ receiver.onReceive(context, Intent(Intent.ACTION_BATTERY_CHANGED))+ }++ @Test+ fun `fires callback when battery is critical`() {+ every { deviceInfoHelper.isBatteryCritical() } returns true++ fireBatteryBroadcast()++ assertEquals(1, criticalCount)+ }++ @Test+ fun `does not fire callback when battery is not critical`() {+ every { deviceInfoHelper.isBatteryCritical() } returns false++ fireBatteryBroadcast()++ assertEquals(0, criticalCount)+ }++ @Test+ fun `start is idempotent and stop unregisters once`() {+ monitor.start()+ monitor.start()+ monitor.stop()+ monitor.stop()++ verify(exactly = 1) { context.unregisterReceiver(any()) }+ }++ @Test+ fun `stop without start does not unregister`() {+ monitor.stop()++ verify(exactly = 0) { context.unregisterReceiver(any()) }+ }+}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.ktindex 0c7529ff..e4755094 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@@ -44,6 +44,7 @@ class LocationForegroundServiceTest {private lateinit var notificationHelper: NotificationHelperprivate lateinit var profileManager: ProfileManagerprivate lateinit var conditionMonitor: ConditionMonitor+ private lateinit var batteryMonitor: BatteryMonitorprivate lateinit var secureStorage: SecureStorageHelperprivate lateinit var networkManager: NetworkManagerprivate lateinit var androidNotificationManager: NotificationManager@@ -63,6 +64,7 @@ class LocationForegroundServiceTest {notificationHelper = mockk(relaxed = true)profileManager = mockk(relaxed = true)conditionMonitor = mockk(relaxed = true)+ batteryMonitor = mockk(relaxed = true)secureStorage = mockk(relaxed = true)networkManager = mockk(relaxed = true)androidNotificationManager = mockk(relaxed = true)@@ -135,6 +137,7 @@ class LocationForegroundServiceTest {setField("notificationHelper", notificationHelper)setField("profileManager", profileManager)setField("conditionMonitor", conditionMonitor)+ setField("batteryMonitor", batteryMonitor)setField("secureStorage", secureStorage)setField("networkManager", networkManager)setField("notificationManager", androidNotificationManager)@@ -557,16 +560,6 @@ class LocationForegroundServiceTest {verify { location.setSpeed(2.0f) }}- @Test- fun `handleLocationUpdate stops service when battery critical during tracking`() = testScope.runTest {- every { deviceInfoHelper.isBatteryCritical() } returns true- val location = mockLocation()-- invokeHandleLocationUpdate(location)-- verify(exactly = 0) { dbHelper.saveLocation(any(), any(), any(), any(), any(), any(), any(), any(), any(), any()) }- }-@Testfun `handleLocationUpdate starts entry delay when location enters geofence`() = testScope.runTest {every { geofenceHelper.getPauseZone(any()) } returns homeGeofence@@ -1554,63 +1547,47 @@ class LocationForegroundServiceTest {// =========================================================================@Test- fun `stopForBattery clears active profile event`() = testScope.runTest {+ fun `stopForBattery clears active profile event`() {every { profileManager.getActiveProfileName() } returns "Charging"- every { deviceInfoHelper.isBatteryCritical() } returns true- val location = mockLocation()- invokeHandleLocationUpdate(location)+ invokeOnBatteryCritical()verify { LocationServiceModule.sendProfileSwitchEvent(null, null) }}@Test- fun `stopForBattery sends tracking stopped event`() = testScope.runTest {- every { deviceInfoHelper.isBatteryCritical() } returns true- val location = mockLocation()-- invokeHandleLocationUpdate(location)+ fun `stopForBattery sends tracking stopped event`() {+ invokeOnBatteryCritical()verify { LocationServiceModule.sendTrackingStoppedEvent("Battery below 5% - tracking paused") }}@Test- fun `stopForBattery saves tracking_enabled false`() = testScope.runTest {- every { deviceInfoHelper.isBatteryCritical() } returns true- val location = mockLocation()-- invokeHandleLocationUpdate(location)+ fun `stopForBattery saves tracking_enabled false`() {+ invokeOnBatteryCritical()verify { dbHelper.saveSetting("tracking_enabled", "false") }}@Test- fun `stopForBattery does not send profile event when no active profile`() = testScope.runTest {+ fun `stopForBattery does not send profile event when no active profile`() {every { profileManager.getActiveProfileName() } returns null- every { deviceInfoHelper.isBatteryCritical() } returns true- val location = mockLocation()- invokeHandleLocationUpdate(location)+ invokeOnBatteryCritical()verify(exactly = 0) { LocationServiceModule.sendProfileSwitchEvent(any(), any()) }}@Test- fun `stopForBattery marks stopped_by_battery so charger can auto-resume`() = testScope.runTest {- every { deviceInfoHelper.isBatteryCritical() } returns true- val location = mockLocation()-- invokeHandleLocationUpdate(location)+ fun `stopForBattery marks stopped_by_battery so charger can auto-resume`() {+ invokeOnBatteryCritical()verify { dbHelper.saveSetting("stopped_by_battery", "true") }}@Test- fun `stopForBattery arms the charger recovery worker`() = testScope.runTest {- every { deviceInfoHelper.isBatteryCritical() } returns true- val location = mockLocation()-- invokeHandleLocationUpdate(location)+ fun `stopForBattery arms the charger recovery worker`() {+ invokeOnBatteryCritical()verify { BatteryRecoveryScheduler.schedule(any()) }}@@ -1623,6 +1600,17 @@ class LocationForegroundServiceTest {verify(exactly = 0) { BatteryRecoveryScheduler.schedule(any()) }}+ @Test+ fun `battery critical via monitor stops and arms recovery even while wifi paused`() {+ // GPS is off while wifi-paused, so the stop has to come from the battery monitor.+ setField("isWifiPaused", true)++ invokeOnBatteryCritical()++ verify { dbHelper.saveSetting("stopped_by_battery", "true") }+ verify { BatteryRecoveryScheduler.schedule(any()) }+ }+// =========================================================================// enterPauseZone - pause flag registration// =========================================================================@@ -1980,6 +1968,12 @@ class LocationForegroundServiceTest {method.invoke(service, reason, stoppedByBattery)}+ private fun invokeOnBatteryCritical() {+ val method = LocationForegroundService::class.java.getDeclaredMethod("onBatteryCritical")+ method.isAccessible = true+ method.invoke(service)+ }+private fun invokeEnterPauseZone(geofence: GeofenceHelper.Geofence) {val method = LocationForegroundService::class.java.getDeclaredMethod("enterPauseZone", GeofenceHelper.Geofence::class.javadiff --git a/apps/mobile/android/app/src/test/java/com/Colota/util/DeviceInfoHelperTest.kt b/apps/mobile/android/app/src/test/java/com/Colota/util/DeviceInfoHelperTest.ktindex 436bb48b..3f597432 100644--- a/apps/mobile/android/app/src/test/java/com/Colota/util/DeviceInfoHelperTest.kt+++ b/apps/mobile/android/app/src/test/java/com/Colota/util/DeviceInfoHelperTest.kt@@ -12,7 +12,7 @@ import org.junit.After/*** Tests for DeviceInfoHelper using a real instance:- * - isBatteryCritical (via spyk + stubbed getCachedBatteryStatus)+ * - isBatteryCritical (via mocked battery intent)* - getBatteryStatusString (via spyk + stubbed getCachedBatteryStatus)* - getBatteryStatus (via mocked battery intent)*/@@ -41,66 +41,74 @@ class DeviceInfoHelperTest {// --- isBatteryCritical ---@Test- fun `battery at 4 percent discharging is critical`() {- every { helper.getCachedBatteryStatus() } returns Pair(4, 1)+ fun `low battery while unplugged is critical`() {+ mockBatteryIntent(level = 4, scale = 100, status = BatteryManager.BATTERY_STATUS_DISCHARGING, plugged = 0)assertTrue(helper.isBatteryCritical(5))}@Test- fun `battery at 5 percent discharging is not critical`() {- every { helper.getCachedBatteryStatus() } returns Pair(5, 1)+ fun `battery exactly at threshold while unplugged is not critical`() {+ mockBatteryIntent(level = 5, scale = 100, status = BatteryManager.BATTERY_STATUS_DISCHARGING, plugged = 0)assertFalse(helper.isBatteryCritical(5))}@Test- fun `battery at 1 percent discharging is critical`() {- every { helper.getCachedBatteryStatus() } returns Pair(1, 1)+ fun `battery at 1 percent while unplugged is critical`() {+ mockBatteryIntent(level = 1, scale = 100, status = BatteryManager.BATTERY_STATUS_DISCHARGING, plugged = 0)assertTrue(helper.isBatteryCritical(5))}@Test- fun `battery at 0 percent discharging is critical`() {- every { helper.getCachedBatteryStatus() } returns Pair(0, 1)+ fun `battery at 0 percent while unplugged is critical`() {+ mockBatteryIntent(level = 0, scale = 100, status = BatteryManager.BATTERY_STATUS_DISCHARGING, plugged = 0)assertTrue(helper.isBatteryCritical(5))}@Test- fun `battery at 4 percent charging is not critical`() {- every { helper.getCachedBatteryStatus() } returns Pair(4, 2)+ fun `low battery plugged via AC is not critical`() {+ mockBatteryIntent(level = 4, scale = 100, status = BatteryManager.BATTERY_STATUS_CHARGING, plugged = BatteryManager.BATTERY_PLUGGED_AC)assertFalse(helper.isBatteryCritical(5))}@Test- fun `battery at 4 percent full is not critical`() {- every { helper.getCachedBatteryStatus() } returns Pair(4, 3)+ fun `low battery plugged via USB is not critical`() {+ mockBatteryIntent(level = 4, scale = 100, status = BatteryManager.BATTERY_STATUS_CHARGING, plugged = BatteryManager.BATTERY_PLUGGED_USB)assertFalse(helper.isBatteryCritical(5))}@Test- fun `battery at 4 percent unknown status is not critical`() {- every { helper.getCachedBatteryStatus() } returns Pair(4, 0)+ fun `low battery plugged in but reported not charging is not critical`() {+ // Plugged but NOT_CHARGING (charge-limited / thermal) - must not stop.+ mockBatteryIntent(level = 4, scale = 100, status = BatteryManager.BATTERY_STATUS_NOT_CHARGING, plugged = BatteryManager.BATTERY_PLUGGED_AC)assertFalse(helper.isBatteryCritical(5))}@Test- fun `battery at 50 percent discharging is not critical`() {- every { helper.getCachedBatteryStatus() } returns Pair(50, 1)+ fun `low battery with unknown status while unplugged is critical`() {+ // Gated on plugged state, not status - so unknown+unplugged still stops.+ mockBatteryIntent(level = 4, scale = 100, status = BatteryManager.BATTERY_STATUS_UNKNOWN, plugged = 0)+ assertTrue(helper.isBatteryCritical(5))+ }++ @Test+ fun `healthy battery while unplugged is not critical`() {+ mockBatteryIntent(level = 50, scale = 100, status = BatteryManager.BATTERY_STATUS_DISCHARGING, plugged = 0)assertFalse(helper.isBatteryCritical(5))}@Testfun `custom threshold 10 percent works`() {- every { helper.getCachedBatteryStatus() } returns Pair(9, 1)+ mockBatteryIntent(level = 9, scale = 100, status = BatteryManager.BATTERY_STATUS_DISCHARGING, plugged = 0)assertTrue(helper.isBatteryCritical(10))- every { helper.getCachedBatteryStatus() } returns Pair(10, 1)+ mockBatteryIntent(level = 10, scale = 100, status = BatteryManager.BATTERY_STATUS_DISCHARGING, plugged = 0)assertFalse(helper.isBatteryCritical(10))}@Testfun `custom threshold 1 percent works`() {- every { helper.getCachedBatteryStatus() } returns Pair(0, 1)+ mockBatteryIntent(level = 0, scale = 100, status = BatteryManager.BATTERY_STATUS_DISCHARGING, plugged = 0)assertTrue(helper.isBatteryCritical(1))- every { helper.getCachedBatteryStatus() } returns Pair(1, 1)+ mockBatteryIntent(level = 1, scale = 100, status = BatteryManager.BATTERY_STATUS_DISCHARGING, plugged = 0)assertFalse(helper.isBatteryCritical(1))}diff --git a/fastlane/metadata/android/en-US/changelogs/40.txt b/fastlane/metadata/android/en-US/changelogs/40.txtindex 47575771..3ae553f9 100644--- a/fastlane/metadata/android/en-US/changelogs/40.txt+++ b/fastlane/metadata/android/en-US/changelogs/40.txt@@ -1,2 +1,3 @@- Add notes to individual points. Tap a point on the map in Location History or a trip to annotate it.- Exports now include bearing and battery status for every point, in all formats.+- Tracking now auto-resumes when you connect a charger after a low-battery stop.