Export Lifecycle app GPS locations to Owntracks
anil.recoil.org
1# LifeCycle to OwnTracks Export
2
3Export your [LifeCycle app](https://northcube.com/lifecycle/) data and upload
4it to [OwnTracks](https://owntracks.org/) for location tracking visualization
5and analysis.
6
7## Overview
8
9This tool consists of two scripts:
10
111. **`lifecycle_export.sh`** - Exports LifeCycle SQLite database to JSON files. You get this by using [iMazing](https://imazing.com/) to copy the Life Cycle app from the backup. Then unzip that `Life Cycle.imazingapp` file and cd to `Container/Library` which will contain a `life.db` that is the core sqlite3 database used by the app. This `lifecycle_export.sh` script will dump that into JSON.
122. **`lifecycle_owntracks.py`** - Uploads exported location data to OwnTracks via MQTT. This requires a configured MQTT instance ideally with SSL.
13
14## Prerequisites
15
16### Required Software
17- **sqlite3** - For database export
18- **jq** - For JSON processing (optional, used for record counting)
19- **Python 3.8+** - For the upload script
20- **uv** (recommended) or pip for Python package management
21
22Install dependencies:
23```bash
24# Using uv (automatically installs dependencies)
25uv run lifecycle_owntracks.py --help
26
27# Or install manually with pip
28pip install paho-mqtt>=1.6.0
29```
30
31### LifeCycle Data
32- iPhone backup created using tools like iMazing
33- Extract the LifeCycle database file (`life.db`) from the backup
34- The database contains location tracking data from the LifeCycle app
35
36## Quick Start
37
38### 1. Export LifeCycle Database
39
40```bash
41# Basic usage (looks for life.db in current directory)
42./lifecycle_export.sh
43
44# Specify database path and output directory
45./lifecycle_export.sh -d /path/to/life.db -o my_export_dir
46```
47
48### 2. Configure OwnTracks Upload
49
50Create a configuration file:
51```bash
52# Using uv (recommended)
53uv run lifecycle_owntracks.py --create-config
54
55# Or with regular Python
56python3 lifecycle_owntracks.py --create-config
57
58cp config.json.example config.json
59```
60
61Edit `config.json` with your MQTT settings:
62```json
63{
64 "mqtt_host": "your-mqtt-broker.com",
65 "mqtt_port": 8883,
66 "mqtt_user": "your-username",
67 "mqtt_pass": "your-password",
68 "device_id": "lifecycle",
69 "data_dir": "lifecycle_export",
70 "state_file": "owntracks_upload_state.json",
71 "max_accuracy": 500.0,
72 "min_timestamp": 946684800,
73 "motion_time_window": 300
74}
75```
76
77### 3. Upload to OwnTracks
78
79```bash
80# Upload all location data
81uv run lifecycle_owntracks.py
82
83# Upload with custom batch size
84uv run lifecycle_owntracks.py --batch-size 100
85
86# Update existing records with enhanced data
87uv run lifecycle_owntracks.py --update
88```
89
90## Detailed Usage
91
92### Database Export Script
93
94```bash
95./lifecycle_export.sh [OPTIONS]
96
97Options:
98 -d, --database FILE Path to the LifeCycle database file (default: life.db)
99 -o, --output DIR Output directory for exported JSON files (default: lifecycle_export)
100 -h, --help Display help message
101```
102
103The script exports these LifeCycle database tables:
104- **LocationEvent** - Raw GPS coordinates and sensor data
105- **Visit** - Stationary periods at locations
106- **Motion** - Movement type detection (walk/run/drive/etc)
107- **Activity** - Classified activities and behaviors
108- **Transit** - Transportation between locations
109- Additional reference tables (LocationPosition, LocationName, etc.)
110
111### Upload Script
112
113```bash
114uv run lifecycle_owntracks.py [OPTIONS]
115# or
116python3 lifecycle_owntracks.py [OPTIONS]
117
118Options:
119 -c, --config FILE Path to configuration file (default: config.json)
120 --create-config Create example configuration file and exit
121 --update Update existing records with enhanced data
122 --batch-size N Batch size for uploads (default: 50)
123 -h, --help Show help message
124```
125
126### Configuration Options
127
128The upload script supports configuration via:
129
1301. **Configuration file** (JSON format)
1312. **Environment variables**
132
133#### Environment Variables
134```bash
135export MQTT_HOST=your-broker.com
136export MQTT_PORT=8883
137export MQTT_USER=username
138export MQTT_PASS=password
139export DEVICE_ID=lifecycle
140export DATA_DIR=lifecycle_export
141export STATE_FILE=owntracks_upload_state.json
142```
143
144#### Configuration Parameters
145
146| Parameter | Description | Default |
147|-----------|-------------|---------|
148| `mqtt_host` | MQTT broker hostname | `your-mqtt-host.com` |
149| `mqtt_port` | MQTT broker port | `8883` |
150| `mqtt_user` | MQTT username | `your-username` |
151| `mqtt_pass` | MQTT password | `your-password` |
152| `device_id` | OwnTracks device identifier | `lifecycle` |
153| `data_dir` | Directory containing exported JSON files | `lifecycle_export` |
154| `state_file` | File to track upload progress | `owntracks_upload_state.json` |
155| `max_accuracy` | Maximum GPS accuracy (meters) to accept | `500.0` |
156| `min_timestamp` | Minimum Unix timestamp to process | `946684800` (Jan 1, 2000) |
157| `motion_time_window` | Time window for motion data matching (seconds) | `300` |
158
159## Features
160
161### Enhanced Data Processing
162- **Motion Activities**: Correlates location data with motion classification (walking, driving, cycling, etc.)
163- **Barometric Pressure**: Estimates atmospheric pressure from altitude data
164- **Quality Filtering**: Filters out low-accuracy GPS readings
165- **Resume Support**: Tracks upload progress and can resume interrupted uploads
166
167### OwnTracks Integration
168- Publishes location data in standard OwnTracks JSON format
169- Includes extended attributes: altitude, speed, course, WiFi context
170- Supports both initial upload and update modes
171- MQTT with SSL/TLS security
172
173### Data Quality
174- Accuracy filtering (configurable threshold)
175- Timestamp validation
176- Duplicate detection and skipping
177- Error handling with detailed logging
178
179## Troubleshooting
180
181### Common Issues
182
183**Database not found:**
184```
185Error: Database file 'life.db' not found
186```
187- Ensure the LifeCycle database file is in the correct location
188- Use `-d` option to specify the full path
189
190**MQTT connection failed:**
191```
192❌ MQTT setup failed: Connection refused
193```
194- Verify MQTT broker settings (host, port, credentials)
195- Check network connectivity and firewall settings
196- Ensure SSL/TLS settings match your broker configuration
197
198**Missing location data:**
199```
200❌ Location data file not found: lifecycle_export/LocationEvent.json
201```
202- Run the export script first: `./lifecycle_export.sh`
203- Check that the export completed successfully
204
205**Configuration errors:**
206```
207❌ Missing or default configuration for: mqtt_host, mqtt_user, mqtt_pass
208```
209- Update your `config.json` file with actual values
210- Or set the corresponding environment variables
211
212### Debugging
213
214Enable verbose output by examining the upload progress:
215- Watch for accuracy filtering messages
216- Monitor batch upload progress
217- Check the state file for resume information
218
219## File Structure
220
221After running both scripts, you'll have:
222
223```
224lifecycle-to-owntracks/
225├── lifecycle_export.sh # Database export script
226├── lifecycle_owntracks.py # Upload script
227├── config.json # Your MQTT configuration
228├── config.json.example # Example configuration
229├── life.db # Your LifeCycle database
230├── lifecycle_export/ # Exported JSON files
231│ ├── LocationEvent.json
232│ ├── Motion.json
233│ ├── Activity.json
234│ └── ...
235└── owntracks_upload_state.json # Upload progress tracking
236```
237
238## License
239
240This project is released under the MIT License.