Colota - Android GPS Location tracker
added info for api templates
Max Dietrich736c1f3d2c55
diff --git a/README.md b/README.mdindex 3c1f96cd..afed353b 100644--- a/README.md+++ b/README.md@@ -29,7 +29,8 @@ You can join the Google Group https://groups.google.com/g/colota-beta-testing/ a- **Optional REST API connection** to your own server- **Works completely offline** without any server- **HTTPS-encrypted** data transmission (HTTP allowed for localhost development)-- Compatible with **Dawarich**, **OwnTracks**, **Home Assistant**, **Traccar**, **NodeRED** or custom backend+- **Built-in API templates** for **Dawarich**, **OwnTracks**, and **Reitti**+- Works with any backend that accepts JSON over HTTP (e.g., Home Assistant, Traccar, NodeRED)- Free choice of backend system### π GPS Tracking@@ -60,6 +61,28 @@ You can join the Google Group https://groups.google.com/g/colota-beta-testing/ a- **Network-aware**: Auto-sync when network becomes available- **Queue management**: Automatic cleanup of permanently failed items+### π€ Data Export++- **Export location history** in 4 standard formats+- **CSV** for spreadsheets and data analysis+- **GeoJSON** for mapping tools (Mapbox, Leaflet, QGIS)+- **GPX** for GPS tools (Garmin, Strava, Google Earth)+- **KML** for Google Earth and Google Maps+- **Share exported files** directly from the app++### π Authentication++- **Multiple authentication methods**: None, Basic Auth, Bearer Token+- **Custom HTTP headers** for proxies and access control+- **AES-256-GCM encrypted storage** for all credentials on device++### π Reliability++- **Auto-start on boot** resumes tracking after device restart+- **Battery critical monitoring** stops tracking below 5% when unplugged+- **Server health check** with 3-stage fallback (health endpoint β HEAD β root domain)+- **Persistent foreground service** survives app restarts and system cleanup+### π Privacy & Security- **100% Open Source** (AGPL-3.0)@@ -90,23 +113,6 @@ You can join the Google Group https://groups.google.com/g/colota-beta-testing/ a</tr></table>-**Dark Mode** tbd--<table>- <tr>- <td><img src="" alt="Dashboard" width="200"/></td>- <td><img src="" alt="Geofences" width="200"/></td>- <td><img src="" alt="Settings" width="200"/></td>- <td><img src="" alt="Database" width="200"/></td>- </tr>- <tr>- <td align="center">Dashboard</td>- <td align="center">Geofences</td>- <td align="center">Settings</td>- <td align="center">Database</td>- </tr>-</table>----## Installation@@ -123,10 +129,13 @@ You can join the Google Group https://groups.google.com/g/colota-beta-testing/ a### Build from Source+> **Requirements:** Node.js >= 20, Android SDK, JDK 17++```bashgit clone https://github.com/dietrichmax/colota.gitcd colotanpm install+cd android./gradlew assembleRelease```@@ -150,6 +159,19 @@ APK will be in `android/app/build/outputs/apk/release/`## Server Setup+### API Templates++Colota includes built-in API templates for popular backends. Select a template in **Settings > API Settings** to auto-configure field mappings and custom fields.++| Template | Bearing Field | Custom Fields | Notes |+| ------------- | ------------- | -------------------------------- | ------------------------------ |+| **Dawarich** | `cog` | `_type: "location"` | OwnTracks-compatible format |+| **OwnTracks** | `cog` | `_type: "location"`, `tid: "AA"` | Standard OwnTracks HTTP format |+| **Reitti** | `bear` | `_type: "location"` | Standard field names |+| **Custom** | `bear` | _(none)_ | Fully user-defined |++All templates share the same base fields: `lat`, `lon`, `acc`, `alt`, `vel`, `batt`, `bs`, `tst`. The key differences are the bearing field name and auto-included custom fields.+### Dawarich Integration1. **Install Dawarich** (see [Dawarich docs](https://github.com/Freika/dawarich))@@ -157,11 +179,86 @@ APK will be in `android/app/build/outputs/apk/release/`2. **Get API Key** from Dawarich settings3. **Configure Colota**:++ - Go to **Settings > API Settings**+ - Select the **Dawarich** template+ - Set your endpoint:+ ```+ https://dawarich.yourdomain.com/api/v1/owntracks/points?api_key=YOUR_API_KEY+ ```+ - Choose a sync mode (e.g., Batch 5 minutes)++4. **Example payload** (auto-configured by template):+ ```json+ {+ "_type": "location",+ "lat": 51.495065,+ "lon": -0.043945,+ "acc": 12,+ "alt": 519,+ "vel": 0,+ "batt": 85,+ "bs": 2,+ "tst": 1704067200,+ "cog": 180.5+ }```- Endpoint: https://dawarich.yourdomain.com/api/v1/owntracks/points?api_key=YOUR_API_KEY- Field Mapping: Default (OwnTracks compatible)- Sync Mode: Batch (5 minutes)+ Note: Dawarich uses `cog` (course over ground) instead of `bear` for bearing.++### OwnTracks Integration++1. **Install OwnTracks Recorder** (see [OwnTracks docs](https://owntracks.org/booklet/))++2. **Configure Colota**:++ - Go to **Settings > API Settings**+ - Select the **OwnTracks** template+ - Set your endpoint URL++3. **Example payload** (auto-configured by template):+ ```json+ {+ "_type": "location",+ "tid": "AA",+ "lat": 51.495065,+ "lon": -0.043945,+ "acc": 12,+ "alt": 519,+ "vel": 0,+ "batt": 85,+ "bs": 2,+ "tst": 1704067200,+ "cog": 180.5+ }```+ The template adds `_type: "location"` and `tid: "AA"` (tracker ID) automatically.++### Reitti Integration++1. **Install Reitti** (see [Reitti documentation](https://github.com/Moo-Ack-Productions/reitti))++2. **Configure Colota**:++ - Go to **Settings > API Settings**+ - Select the **Reitti** template+ - Set your endpoint URL++3. **Example payload** (auto-configured by template):+ ```json+ {+ "_type": "location",+ "lat": 51.495065,+ "lon": -0.043945,+ "acc": 12,+ "alt": 519,+ "vel": 0,+ "batt": 85,+ "bs": 2,+ "tst": 1704067200,+ "bear": 180.5+ }+ ```+ Reitti uses standard field names (including `bear` for bearing).### Custom Backend@@ -172,6 +269,19 @@ APK will be in `android/app/build/outputs/apk/release/`- Returns 200-299 status code on success- Optional: Authentication via headers or query params+#### Authentication++Colota supports multiple authentication methods, configurable in **Settings > Authentication & Headers**:++| Method | Description | Header Sent |+| ------------------ | --------------------------- | ------------------------------- |+| **None** | No authentication (default) | - |+| **Basic Auth** | Username + password | `Authorization: Basic <base64>` |+| **Bearer Token** | API token / JWT | `Authorization: Bearer <token>` |+| **Custom Headers** | Any key-value pairs | As configured |++All credentials are stored encrypted on-device using AES-256-GCM via Android's EncryptedSharedPreferences. You can also add custom HTTP headers for proxies, API gateways, or services like Cloudflare Access.+**Example payload:**```json@@ -208,12 +318,12 @@ APK will be in `android/app/build/outputs/apk/release/`Choose from optimized presets or create custom settings:-| Preset | Interval | Distance | Sync Interval | Best For |-| --------------- | -------- | -------- | ------------- | --------------- |-| **Instant** | 2s | 5m | Instant | City navigation |-| **Balanced** | 5s | 10m | 5 minutes | Daily commute |-| **Power Saver** | 30s | 50m | 15 minutes | Long trips |-| **Custom** | 1s-β | 0m-β | 0s-β | Advanced users |+| Preset | Interval | Distance | Sync Interval | Retry Interval | Best For |+| --------------- | -------- | -------- | ------------- | -------------- | --------------- |+| **Instant** | 5s | 0m | Instant (0s) | 30s | City navigation |+| **Balanced** | 30s | 1m | 5 minutes | 5 minutes | Daily commute |+| **Power Saver** | 60s | 2m | 15 minutes | 15 minutes | Long trips |+| **Custom** | 1s-β | 0m-β | 0s-β | 30s-β | Advanced users |### GPS Settings@@ -222,7 +332,7 @@ Choose from optimized presets or create custom settings:| Tracking Interval | Time between GPS fixes | 5 seconds | 1s - hours || Movement Threshold | Minimum movement to trigger update | 0 meters | 0m - 1000m || Accuracy Threshold | Filter out fixes above this accuracy | 50 meters | 0m - 1000m |-| Filter Inaccurate | Enable/disable accuracy filtering | Enabled | On/Off |+| Filter Inaccurate | Enable/disable accuracy filtering | Disabled | On/Off |### Server Settings@@ -236,7 +346,10 @@ Choose from optimized presets or create custom settings:### Advanced Settings+- **API backend templates**: Pre-configured field mappings for Dawarich, OwnTracks, Reitti, or fully custom- **Custom field mapping** for any JSON structure+- **Custom static fields**: Add arbitrary key-value pairs included in every API payload (e.g., `_type: "location"`)+- **Authentication settings**: Configure Basic Auth, Bearer Token, or custom HTTP headers- **Retry strategy**: Exponential backoff with configurable intervals- **Queue management**: Automatic cleanup of failed items after max retries- **Network detection**: Auto-sync when connection becomes available@@ -292,13 +405,6 @@ Create zones where tracking automatically pauses:- Saves battery by stopping GPS in defined areas- Zone checks happen every location update (minimal overhead)-### Performance--- **Fast**: Geofence checks cached for 1 minute (optional optimization)-- **Accurate**: Uses great-circle distance calculation-- **Battery efficient**: No unnecessary GPS updates in zones-- **Instant**: Zone entry/exit detected within 1 GPS interval----## API Documentation@@ -341,7 +447,7 @@ Body: Any (ignored)- **4xx errors**: Logged, retried according to settings- **5xx errors**: Exponential backoff applied-- **Network timeout**: Retried with backoff (15s connection, 15s read)+- **Network timeout**: Retried with backoff (10s connection, 10s read)- **Max retries exceeded**: Item removed from queue and logged**Retry Strategy:**@@ -364,9 +470,10 @@ Colota is heavily optimized for long-running background tracking:### Optimizations Applied-- **Notification throttling**: Max 1 update per 5 seconds+- **Notification throttling**: Max 1 update per 10 seconds, plus 2-meter movement filter- **Batch processing**: 50 items per batch, 10 concurrent network requests- **Smart sync**: Only syncs when queue has items and network available+- **Battery critical shutdown**: Automatically stops tracking when battery drops below 5% (unplugged)### Battery Life Estimates@@ -414,11 +521,12 @@ _Based on typical Android device with 4000mAh battery_### Network Communication-- **HTTPS required** for non-localhost endpoints-- **HTTP allowed** for local development (127.0.0.1, 192.168.x.x, 10.x.x.x)+- **HTTPS required** for all public endpoints+- **HTTP allowed** only for private/local addresses (localhost, 127.0.0.1, 192.168.x.x, 10.x.x.x, 172.16-31.x.x)- No telemetry or analytics endpoints- Only communicates with **your configured server**- Network can be completely disabled (offline mode)+- Android network security config enforces cleartext restrictions### Permissions Required@@ -566,7 +674,7 @@ Contributions are welcome! Please follow these guidelines:- Clear app data: Settings β Apps β Colota β Storage β Clear Data- Reinstall app-- Check Android version compatibility (requires Android 8.0+)+- Check Android version compatibility (requires Android 7.0+ / API 24)- Report issue with crash logs: `adb logcat -d > crash.log`---@@ -597,8 +705,7 @@ A: To ensure that any modifications remain open source, especially for server-si**Q: How accurate is the tracking?**A: In ideal conditions (open sky, good GPS signal): 3-10 meters. In urban areas or buildings: 10-50 meters. Accuracy filtering helps remove poor GPS fixes.-**Q: Can I export my location history?**-A: Yes, through Data Management you can view raw database data. Future versions may include GPX/KML export.+**Q: Can I export my location history?** A: Yes! Go to the Export Data screen to export your full location history in **CSV**, **GeoJSON**, **GPX**, or **KML** format. Exported files can be shared directly from the app.**Q: Does this drain battery like other tracking apps?**A: Colota is optimized for efficiency with caching and batching. Expect 10-12 hours of high-accuracy tracking, better with optimized settings.