LifeCycle to OwnTracks Export#

Export your LifeCycle app data and upload it to OwnTracks for location tracking visualization and analysis.

Overview#

This tool consists of two scripts:

1. lifecycle_export.sh - Exports LifeCycle SQLite database to JSON files. You get this by using iMazing 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.
2. lifecycle_owntracks.py - Uploads exported location data to OwnTracks via MQTT. This requires a configured MQTT instance ideally with SSL.

Prerequisites#

Required Software#

• sqlite3 - For database export
• jq - For JSON processing (optional, used for record counting)
• Python 3.8+ - For the upload script
• uv (recommended) or pip for Python package management

Install dependencies:

# Using uv (automatically installs dependencies)
uv run lifecycle_owntracks.py --help

# Or install manually with pip
pip install paho-mqtt>=1.6.0

LifeCycle Data#

• iPhone backup created using tools like iMazing
• Extract the LifeCycle database file (life.db) from the backup
• The database contains location tracking data from the LifeCycle app

Quick Start#

1. Export LifeCycle Database#

# Basic usage (looks for life.db in current directory)
./lifecycle_export.sh

# Specify database path and output directory
./lifecycle_export.sh -d /path/to/life.db -o my_export_dir

2. Configure OwnTracks Upload#

Create a configuration file:

# Using uv (recommended)
uv run lifecycle_owntracks.py --create-config

# Or with regular Python
python3 lifecycle_owntracks.py --create-config

cp config.json.example config.json

Edit config.json with your MQTT settings:

{
  "mqtt_host": "your-mqtt-broker.com",
  "mqtt_port": 8883,
  "mqtt_user": "your-username", 
  "mqtt_pass": "your-password",
  "device_id": "lifecycle",
  "data_dir": "lifecycle_export",
  "state_file": "owntracks_upload_state.json",
  "max_accuracy": 500.0,
  "min_timestamp": 946684800,
  "motion_time_window": 300
}

3. Upload to OwnTracks#

# Upload all location data
uv run lifecycle_owntracks.py

# Upload with custom batch size
uv run lifecycle_owntracks.py --batch-size 100

# Update existing records with enhanced data
uv run lifecycle_owntracks.py --update

Detailed Usage#

Database Export Script#

./lifecycle_export.sh [OPTIONS]

Options:
  -d, --database FILE    Path to the LifeCycle database file (default: life.db)
  -o, --output DIR       Output directory for exported JSON files (default: lifecycle_export)  
  -h, --help             Display help message

The script exports these LifeCycle database tables:

• LocationEvent - Raw GPS coordinates and sensor data
• Visit - Stationary periods at locations
• Motion - Movement type detection (walk/run/drive/etc)
• Activity - Classified activities and behaviors
• Transit - Transportation between locations
• Additional reference tables (LocationPosition, LocationName, etc.)

Upload Script#

uv run lifecycle_owntracks.py [OPTIONS]
# or
python3 lifecycle_owntracks.py [OPTIONS]

Options:
  -c, --config FILE      Path to configuration file (default: config.json)
  --create-config        Create example configuration file and exit
  --update              Update existing records with enhanced data
  --batch-size N        Batch size for uploads (default: 50)
  -h, --help            Show help message

Configuration Options#

The upload script supports configuration via:

1. Configuration file (JSON format)
2. Environment variables

Environment Variables#

export MQTT_HOST=your-broker.com
export MQTT_PORT=8883  
export MQTT_USER=username
export MQTT_PASS=password
export DEVICE_ID=lifecycle
export DATA_DIR=lifecycle_export
export STATE_FILE=owntracks_upload_state.json

Configuration Parameters#

Features#

Enhanced Data Processing#

• Motion Activities: Correlates location data with motion classification (walking, driving, cycling, etc.)
• Barometric Pressure: Estimates atmospheric pressure from altitude data
• Quality Filtering: Filters out low-accuracy GPS readings
• Resume Support: Tracks upload progress and can resume interrupted uploads

OwnTracks Integration#

• Publishes location data in standard OwnTracks JSON format
• Includes extended attributes: altitude, speed, course, WiFi context
• Supports both initial upload and update modes
• MQTT with SSL/TLS security

Data Quality#

• Accuracy filtering (configurable threshold)
• Timestamp validation
• Duplicate detection and skipping
• Error handling with detailed logging

Troubleshooting#

Common Issues#

Database not found:

Error: Database file 'life.db' not found

• Ensure the LifeCycle database file is in the correct location
• Use -d option to specify the full path

MQTT connection failed:

❌ MQTT setup failed: Connection refused

• Verify MQTT broker settings (host, port, credentials)
• Check network connectivity and firewall settings
• Ensure SSL/TLS settings match your broker configuration

Missing location data:

❌ Location data file not found: lifecycle_export/LocationEvent.json

• Run the export script first: ./lifecycle_export.sh
• Check that the export completed successfully

Configuration errors:

❌ Missing or default configuration for: mqtt_host, mqtt_user, mqtt_pass

• Update your config.json file with actual values
• Or set the corresponding environment variables

Debugging#

Enable verbose output by examining the upload progress:

• Watch for accuracy filtering messages
• Monitor batch upload progress
• Check the state file for resume information

File Structure#

After running both scripts, you'll have:

lifecycle-to-owntracks/
├── lifecycle_export.sh                         # Database export script
├── lifecycle_owntracks.py            # Upload script  
├── config.json                        # Your MQTT configuration
├── config.json.example                # Example configuration
├── life.db                           # Your LifeCycle database
├── lifecycle_export/                 # Exported JSON files
│   ├── LocationEvent.json
│   ├── Motion.json
│   ├── Activity.json
│   └── ...
└── owntracks_upload_state.json       # Upload progress tracking

License#

This project is released under the MIT License.