# LifeCycle to OwnTracks Export

Export your [LifeCycle app](https://northcube.com/lifecycle/) data and upload
it to [OwnTracks](https://owntracks.org/) 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](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.
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:
```bash
# 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

```bash
# 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:
```bash
# 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:
```json
{
  "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

```bash
# 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

```bash
./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

```bash
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
```bash
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

| Parameter | Description | Default |
|-----------|-------------|---------|
| `mqtt_host` | MQTT broker hostname | `your-mqtt-host.com` |
| `mqtt_port` | MQTT broker port | `8883` |
| `mqtt_user` | MQTT username | `your-username` |
| `mqtt_pass` | MQTT password | `your-password` |
| `device_id` | OwnTracks device identifier | `lifecycle` |
| `data_dir` | Directory containing exported JSON files | `lifecycle_export` |
| `state_file` | File to track upload progress | `owntracks_upload_state.json` |
| `max_accuracy` | Maximum GPS accuracy (meters) to accept | `500.0` |
| `min_timestamp` | Minimum Unix timestamp to process | `946684800` (Jan 1, 2000) |
| `motion_time_window` | Time window for motion data matching (seconds) | `300` |

## 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.