Colota - Android GPS Location tracker
Add Wi-Fi only sync toggle to gate uploads on unmetered connections
Max Dietrich6f583efcddda
diff --git a/README.md b/README.mdindex e92150fc..93312e05 100644--- a/README.md+++ b/README.md@@ -15,7 +15,7 @@ Colota sends your location to your own server over HTTP(S). It works offline, su- **Works Offline** — Fully functional without a server. Export as CSV, GeoJSON, GPX, or KML.- **Reliable Tracking** — Foreground service, auto-start on boot, exponential backoff retry.- **Geofencing** — Pause zones that automatically pause tracking.-- **Flexible Sync** — Instant, batch, or offline modes.+- **Flexible Sync** — Instant, batch, Wi-Fi only, or offline modes.- **Authentication** — Basic Auth, Bearer Token, or custom headers with AES-256-GCM encryption.## Screenshotsdiff --git a/apps/docs/docs/configuration/sync-presets.md b/apps/docs/docs/configuration/sync-presets.mdindex 7b40241b..52de9557 100644--- a/apps/docs/docs/configuration/sync-presets.md+++ b/apps/docs/docs/configuration/sync-presets.md@@ -14,3 +14,15 @@ Colota includes built-in presets that configure tracking interval, movement thre| **Custom** | 1s-∞ | 0m-∞ | 0s-∞ | Advanced users |Select a preset in **Settings** or choose **Custom** to configure each parameter individually.++## Wi-Fi Only Sync++When enabled, Colota queues locations locally and only uploads when connected to an unmetered network (Wi-Fi, Ethernet). Uploads are skipped on cellular data.++This is useful for:++- **Limited mobile data** — Avoid using cellular bandwidth for location uploads+- **Roaming** — Prevent expensive data charges while traveling abroad+- **Battery savings** — Reduce radio usage on metered connections++Toggle this in **Settings > Advanced Settings > Network Settings > Wi-Fi Only Sync**. Locations continue to be recorded and queued regardless of this setting — they sync automatically once Wi-Fi is available.diff --git a/apps/docs/docs/development/architecture.md b/apps/docs/docs/development/architecture.mdindex fb32e30d..f9679754 100644--- a/apps/docs/docs/development/architecture.md+++ b/apps/docs/docs/development/architecture.md@@ -112,7 +112,7 @@ Orchestrates batch location uploads with:### NetworkManager-HTTP client. Validates endpoints, enforces HTTPS for public hosts, injects auth headers, and caches connectivity checks.+HTTP client. Validates endpoints, enforces HTTPS for public hosts, injects auth headers, caches connectivity checks, and detects unmetered connections for Wi-Fi only sync.### GeofenceHelperdiff --git a/apps/docs/docs/guides/troubleshooting.md b/apps/docs/docs/guides/troubleshooting.mdindex 15623149..afd82449 100644--- a/apps/docs/docs/guides/troubleshooting.md+++ b/apps/docs/docs/guides/troubleshooting.md@@ -25,7 +25,7 @@ sidebar_position: 44. Verify network connectivity5. Check the queue count in **Data Management**-**Common causes**: Wrong URL, HTTPS required for non-localhost, expired SSL certificate, incorrect authentication, mismatched field mapping, self-signed certificate (not supported).+**Common causes**: Wrong URL, HTTPS required for non-localhost, expired SSL certificate, incorrect authentication, mismatched field mapping, self-signed certificate (not supported), **Wi-Fi Only Sync** enabled while on cellular data.## Debugging with adb logcat@@ -47,6 +47,12 @@ Key log tags:You can also use the **Location History** screen in the app to see recorded locations on a track map or as a list with their accuracy and timestamps.+## Locations not syncing on mobile data++If **Wi-Fi Only Sync** is enabled, uploads are skipped while on cellular data. Locations continue to be recorded and queued locally — they sync automatically when you connect to Wi-Fi.++To disable: **Settings > Advanced Settings > Network Settings > Wi-Fi Only Sync**.+## Database growing too large- Use **Clear Sent History** to remove synced locationsdiff --git a/apps/docs/docs/introduction.md b/apps/docs/docs/introduction.mdindex 4bdee599..d885131b 100644--- a/apps/docs/docs/introduction.md+++ b/apps/docs/docs/introduction.md@@ -14,7 +14,7 @@ Colota is a self-hosted GPS tracking app for Android. It sends your location to- **Works Offline** — Works without a server. Store location history locally and export as CSV, GeoJSON, GPX, or KML.- **Background Tracking** — Foreground service, auto-start on boot, retry with exponential backoff, battery-critical shutdown.- **Geofencing** — Create pause zones where tracking automatically pauses to save battery.-- **Sync Modes** — Instant, batch, or offline. Configurable intervals with automatic retry.+- **Sync Modes** — Instant, batch, or offline. Wi-Fi only sync, configurable intervals with automatic retry.- **Data Export** — Export location history in CSV, GeoJSON, GPX, or KML formats.- **Authentication** — Basic Auth, Bearer Token, or custom HTTP headers with AES-256-GCM encrypted storage.- **Dark Mode** — Full light and dark theme support.diff --git a/apps/mobile/android/app/src/main/java/com/colota/data/DatabaseHelper.kt b/apps/mobile/android/app/src/main/java/com/colota/data/DatabaseHelper.ktindex 45961b82..fb3778aa 100644--- a/apps/mobile/android/app/src/main/java/com/colota/data/DatabaseHelper.kt+++ b/apps/mobile/android/app/src/main/java/com/colota/data/DatabaseHelper.kt@@ -134,6 +134,7 @@ class DatabaseHelper private constructor(context: Context) :"maxRetries" to "5","retryInterval" to "30","isOfflineMode" to "false",+ "isWifiOnlySync" to "false","customFields" to "[]","hasCompletedSetup" to "false","tracking_enabled" to "false",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 e97016ba..ce0495a4 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@@ -569,6 +569,7 @@ class LocationForegroundService : Service() {retryIntervalSeconds = config.retryIntervalSeconds,maxRetries = config.maxRetries,isOfflineMode = config.isOfflineMode,+ isWifiOnlySync = config.isWifiOnlySync,authHeaders = secureStorage.getAuthHeaders(),httpMethod = config.httpMethod)diff --git a/apps/mobile/android/app/src/main/java/com/colota/service/ServiceConfig.kt b/apps/mobile/android/app/src/main/java/com/colota/service/ServiceConfig.ktindex 8a95d6ae..a13199bb 100644--- a/apps/mobile/android/app/src/main/java/com/colota/service/ServiceConfig.kt+++ b/apps/mobile/android/app/src/main/java/com/colota/service/ServiceConfig.kt@@ -24,6 +24,7 @@ data class ServiceConfig(val filterInaccurateLocations: Boolean = false,val retryIntervalSeconds: Int = 30,val isOfflineMode: Boolean = false,+ val isWifiOnlySync: Boolean = false,val fieldMap: String? = null,val customFields: String? = null,val httpMethod: String = "POST"@@ -42,6 +43,7 @@ data class ServiceConfig(filterInaccurateLocations = saved["filterInaccurateLocations"]?.toBoolean() ?: true,retryIntervalSeconds = saved["retryInterval"]?.toIntOrNull() ?: 300,isOfflineMode = saved["isOfflineMode"]?.toBoolean() ?: false,+ isWifiOnlySync = saved["isWifiOnlySync"]?.toBoolean() ?: false,fieldMap = saved["fieldMap"],customFields = saved["customFields"],httpMethod = saved["httpMethod"] ?: "POST"@@ -81,6 +83,7 @@ data class ServiceConfig(filterInaccurateLocations = config.getBooleanOrNull("filterInaccurateLocations") ?: dbConfig.filterInaccurateLocations,retryIntervalSeconds = config.getIntOrNull("retryInterval") ?: dbConfig.retryIntervalSeconds,isOfflineMode = config.getBooleanOrNull("isOfflineMode") ?: dbConfig.isOfflineMode,+ isWifiOnlySync = config.getBooleanOrNull("isWifiOnlySync") ?: dbConfig.isWifiOnlySync,fieldMap = fieldMapJson ?: dbConfig.fieldMap,customFields = customFieldsJson ?: dbConfig.customFields,httpMethod = config.getStringOrNull("httpMethod") ?: dbConfig.httpMethod@@ -101,6 +104,7 @@ data class ServiceConfig(filterInaccurateLocations = extras.getBooleanOrDefault("filterInaccurateLocations", dbConfig.filterInaccurateLocations),retryIntervalSeconds = extras.getIntOrDefault("retryInterval", dbConfig.retryIntervalSeconds),isOfflineMode = extras.getBooleanOrDefault("isOfflineMode", dbConfig.isOfflineMode),+ isWifiOnlySync = extras.getBooleanOrDefault("isWifiOnlySync", dbConfig.isWifiOnlySync),fieldMap = extras.getStringOrDefault("fieldMap", dbConfig.fieldMap),customFields = extras.getStringOrDefault("customFields", dbConfig.customFields),httpMethod = extras.getStringOrDefault("httpMethod", dbConfig.httpMethod) ?: "POST"@@ -119,6 +123,7 @@ data class ServiceConfig(putExtra("maxRetries", maxRetries)putExtra("retryInterval", retryIntervalSeconds)putExtra("isOfflineMode", isOfflineMode)+ putExtra("isWifiOnlySync", isWifiOnlySync)fieldMap?.let { putExtra("fieldMap", it) }customFields?.let { putExtra("customFields", it) }putExtra("httpMethod", httpMethod)diff --git a/apps/mobile/android/app/src/main/java/com/colota/sync/NetworkManager.kt b/apps/mobile/android/app/src/main/java/com/colota/sync/NetworkManager.ktindex 7474cb53..251baa96 100644--- a/apps/mobile/android/app/src/main/java/com/colota/sync/NetworkManager.kt+++ b/apps/mobile/android/app/src/main/java/com/colota/sync/NetworkManager.kt@@ -205,4 +205,22 @@ class NetworkManager(private val context: Context) {* Checks for an active, validated internet connection with caching.*/fun isNetworkAvailable(): Boolean = networkCache.get()++ private val unmeteredCache = TimedCache(NETWORK_CHECK_CACHE_MS) {+ try {+ val network = connectivityManager.activeNetwork+ val capabilities = connectivityManager.getNetworkCapabilities(network)+ capabilities != null &&+ capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED)+ } catch (e: Exception) {+ Log.e(TAG, "Unmetered check failed", e)+ false+ }+ }++ /**+ * Returns true when the active network is unmetered (Wi-Fi, Ethernet, etc.).+ * Cached for [NETWORK_CHECK_CACHE_MS] to avoid repeated IPC calls.+ */+ fun isUnmeteredConnection(): Boolean = unmeteredCache.get()}\ No newline at end of filediff --git a/apps/mobile/android/app/src/main/java/com/colota/sync/SyncManager.kt b/apps/mobile/android/app/src/main/java/com/colota/sync/SyncManager.ktindex 23f8c25b..31f4f3b1 100644--- a/apps/mobile/android/app/src/main/java/com/colota/sync/SyncManager.kt+++ b/apps/mobile/android/app/src/main/java/com/colota/sync/SyncManager.kt@@ -31,6 +31,7 @@ class SyncManager(private var retryIntervalSeconds: Int = 300private var maxRetries: Int = 5private var isOfflineMode: Boolean = false+ private var isWifiOnlySync: Boolean = falseprivate var authHeaders: Map<String, String> = emptyMap()private var httpMethod: String = "POST"@@ -51,6 +52,7 @@ class SyncManager(retryIntervalSeconds: Int,maxRetries: Int,isOfflineMode: Boolean,+ isWifiOnlySync: Boolean,authHeaders: Map<String, String>,httpMethod: String = "POST") {@@ -59,6 +61,7 @@ class SyncManager(this.retryIntervalSeconds = retryIntervalSecondsthis.maxRetries = maxRetriesthis.isOfflineMode = isOfflineMode+ this.isWifiOnlySync = isWifiOnlySyncthis.authHeaders = authHeadersthis.httpMethod = httpMethod}@@ -69,7 +72,8 @@ class SyncManager(val baseDelay = calculateNextSyncDelay()delay(baseDelay * 1000L)- if (isOfflineMode || !networkManager.isNetworkAvailable()) {+ if (isOfflineMode || !networkManager.isNetworkAvailable() ||+ (isWifiOnlySync && !networkManager.isUnmeteredConnection())) {continue}@@ -130,7 +134,8 @@ class SyncManager(}// Immediate send mode (syncInterval = 0)- if (syncIntervalSeconds == 0 && networkManager.isNetworkAvailable()) {+ if (syncIntervalSeconds == 0 && networkManager.isNetworkAvailable() &&+ !(isWifiOnlySync && !networkManager.isUnmeteredConnection())) {Log.d(TAG, "Instant send")val success = networkManager.sendToEndpoint(payload, endpoint, authHeaders, httpMethod)diff --git a/apps/mobile/android/app/src/test/java/com/Colota/service/ServiceConfigTest.kt b/apps/mobile/android/app/src/test/java/com/Colota/service/ServiceConfigTest.ktnew file mode 100644index 00000000..071cde6c--- /dev/null+++ b/apps/mobile/android/app/src/test/java/com/Colota/service/ServiceConfigTest.kt@@ -0,0 +1,84 @@+/**+ * Copyright (C) 2026 Max Dietrich+ * Licensed under the GNU AGPLv3. See LICENSE in the project root for details.+ */++package com.Colota.service++import com.Colota.data.DatabaseHelper+import io.mockk.every+import io.mockk.mockk+import org.junit.Assert.*+import org.junit.Test++class ServiceConfigTest {++ private fun mockDbHelper(settings: Map<String, String>): DatabaseHelper {+ return mockk {+ every { getAllSettings() } returns settings+ }+ }++ private val baseSettings = mapOf(+ "endpoint" to "https://example.com",+ "interval" to "5000",+ "minUpdateDistance" to "0",+ "syncInterval" to "0",+ "maxRetries" to "5",+ "accuracyThreshold" to "50.0",+ "filterInaccurateLocations" to "false",+ "retryInterval" to "30",+ "isOfflineMode" to "false",+ "isWifiOnlySync" to "false",+ "httpMethod" to "POST"+ )++ // --- fromDatabase ---++ @Test+ fun `fromDatabase defaults isWifiOnlySync to false`() {+ val db = mockDbHelper(baseSettings - "isWifiOnlySync")+ val config = ServiceConfig.fromDatabase(db)+ assertFalse(config.isWifiOnlySync)+ }++ @Test+ fun `fromDatabase reads isWifiOnlySync true`() {+ val db = mockDbHelper(baseSettings + ("isWifiOnlySync" to "true"))+ val config = ServiceConfig.fromDatabase(db)+ assertTrue(config.isWifiOnlySync)+ }++ @Test+ fun `fromDatabase reads isWifiOnlySync false`() {+ val db = mockDbHelper(baseSettings + ("isWifiOnlySync" to "false"))+ val config = ServiceConfig.fromDatabase(db)+ assertFalse(config.isWifiOnlySync)+ }++ // --- data class defaults ---++ @Test+ fun `default constructor sets isWifiOnlySync to false`() {+ val config = ServiceConfig()+ assertFalse(config.isWifiOnlySync)+ }++ @Test+ fun `constructor accepts isWifiOnlySync true`() {+ val config = ServiceConfig(isWifiOnlySync = true)+ assertTrue(config.isWifiOnlySync)+ }++ // --- isOfflineMode and isWifiOnlySync are independent ---++ @Test+ fun `isOfflineMode and isWifiOnlySync are independent`() {+ val db = mockDbHelper(+ baseSettings + ("isOfflineMode" to "true") + ("isWifiOnlySync" to "false")+ )+ val config = ServiceConfig.fromDatabase(db)+ assertTrue(config.isOfflineMode)+ assertFalse(config.isWifiOnlySync)+ }+}diff --git a/apps/mobile/src/components/features/settings/SyncStrategySettings.tsx b/apps/mobile/src/components/features/settings/SyncStrategySettings.tsxindex 8556df4d..b52c7ec4 100644--- a/apps/mobile/src/components/features/settings/SyncStrategySettings.tsx+++ b/apps/mobile/src/components/features/settings/SyncStrategySettings.tsx@@ -266,6 +266,33 @@ export function SyncStrategySettings({thumbColor={settings.maxRetries === 0 ? colors.primary : colors.border}/></View>++ {/* Wi-Fi Only Sync Toggle */}+ <View style={[styles.settingRow, styles.settingRowSpaced]}>+ <View style={styles.settingContent}>+ <Text style={[styles.settingLabel, { color: colors.text }]}>Wi-Fi Only Sync</Text>+ <Text style={[styles.settingHint, { color: colors.textSecondary }]}>+ Only upload when connected to Wi-Fi+ </Text>+ </View>+ <Switch+ value={settings.isWifiOnlySync}+ onValueChange={(value) => {+ const next = {+ ...settings,+ isWifiOnlySync: value,+ syncPreset: "custom" as const+ }+ onSettingsChange(next)+ onImmediateSave(next)+ }}+ trackColor={{+ false: colors.border,+ true: colors.primary + "80"+ }}+ thumbColor={settings.isWifiOnlySync ? colors.primary : colors.border}+ />+ </View></View><Divider />@@ -426,6 +453,9 @@ const styles = StyleSheet.create({...fonts.regular,lineHeight: 18},+ settingRowSpaced: {+ marginTop: 16+ },nestedSetting: {marginTop: 12,paddingLeft: 16,diff --git a/apps/mobile/src/services/NativeLocationService.ts b/apps/mobile/src/services/NativeLocationService.tsindex 80bac900..b5e03768 100644--- a/apps/mobile/src/services/NativeLocationService.ts+++ b/apps/mobile/src/services/NativeLocationService.ts@@ -63,6 +63,7 @@ class NativeLocationService {filterInaccurateLocations: settings.filterInaccurateLocations,accuracyThreshold: settings.accuracyThreshold,isOfflineMode: settings.isOfflineMode,+ isWifiOnlySync: settings.isWifiOnlySync,httpMethod: settings.httpMethod}diff --git a/apps/mobile/src/services/SettingsService.ts b/apps/mobile/src/services/SettingsService.tsindex bc62183c..d15a0dbe 100644--- a/apps/mobile/src/services/SettingsService.ts+++ b/apps/mobile/src/services/SettingsService.ts@@ -49,6 +49,7 @@ export const SettingsService = {case "filterInaccurateLocations":case "isOfflineMode":+ case "isWifiOnlySync":// Boolean → "true"/"false"stringValue = String(value)breakdiff --git a/apps/mobile/src/services/__tests__/NativeLocationService.test.ts b/apps/mobile/src/services/__tests__/NativeLocationService.test.tsindex e6cfdca0..ac0f048b 100644--- a/apps/mobile/src/services/__tests__/NativeLocationService.test.ts+++ b/apps/mobile/src/services/__tests__/NativeLocationService.test.ts@@ -89,6 +89,7 @@ describe("NativeLocationService", () => {filterInaccurateLocations: false,accuracyThreshold: 50,isOfflineMode: false,+ isWifiOnlySync: false,customFields: [],apiTemplate: "custom" as const,syncPreset: "instant" as const,@@ -119,6 +120,7 @@ describe("NativeLocationService", () => {filterInaccurateLocations: false,accuracyThreshold: 50,isOfflineMode: false,+ isWifiOnlySync: false,customFields: [],apiTemplate: "traccar" as const,syncPreset: "instant" as const,diff --git a/apps/mobile/src/types/global.ts b/apps/mobile/src/types/global.tsindex cf675df9..c9e7f7b7 100644--- a/apps/mobile/src/types/global.ts+++ b/apps/mobile/src/types/global.ts@@ -270,6 +270,7 @@ export interface Settings {retryInterval: numbermaxRetries: numberisOfflineMode: boolean+ isWifiOnlySync: boolean// UI StatesyncPreset: SyncPreset@@ -290,6 +291,7 @@ export const DEFAULT_SETTINGS: Settings = {syncPreset: "instant",maxRetries: 5,isOfflineMode: false,+ isWifiOnlySync: false,hasCompletedSetup: false,httpMethod: "POST"} as const