Skip to content

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.md
index 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.
## Screenshots
diff --git a/apps/docs/docs/configuration/sync-presets.md b/apps/docs/docs/configuration/sync-presets.md
index 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.md
index 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.
### GeofenceHelper
diff --git a/apps/docs/docs/guides/troubleshooting.md b/apps/docs/docs/guides/troubleshooting.md
index 15623149..afd82449 100644
--- a/apps/docs/docs/guides/troubleshooting.md
+++ b/apps/docs/docs/guides/troubleshooting.md
@@ -25,7 +25,7 @@ sidebar_position: 4
4. Verify network connectivity
5. 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 locations
diff --git a/apps/docs/docs/introduction.md b/apps/docs/docs/introduction.md
index 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.kt
index 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.kt
index 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.kt
index 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.kt
index 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 file
diff --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.kt
index 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 = 300
private var maxRetries: Int = 5
private var isOfflineMode: Boolean = false
+ private var isWifiOnlySync: Boolean = false
private 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 = retryIntervalSeconds
this.maxRetries = maxRetries
this.isOfflineMode = isOfflineMode
+ this.isWifiOnlySync = isWifiOnlySync
this.authHeaders = authHeaders
this.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.kt
new file mode 100644
index 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.tsx
index 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.ts
index 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.ts
index 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)
break
diff --git a/apps/mobile/src/services/__tests__/NativeLocationService.test.ts b/apps/mobile/src/services/__tests__/NativeLocationService.test.ts
index 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.ts
index 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: number
maxRetries: number
isOfflineMode: boolean
+ isWifiOnlySync: boolean
// UI State
syncPreset: SyncPreset
@@ -290,6 +291,7 @@ export const DEFAULT_SETTINGS: Settings = {
syncPreset: "instant",
maxRetries: 5,
isOfflineMode: false,
+ isWifiOnlySync: false,
hasCompletedSetup: false,
httpMethod: "POST"
} as const