Metadata-Version: 2.4
Name: skytraq-datalog
Version: 0.1.1
Summary: Python driver for SkyTraq Venus GPS data loggers — download, decode and export datalog flash
Author-email: Teichi <tobias@teichmann.top>
Project-URL: Homepage, https://gitlab.com/Teigi/skytraq-datalog
Project-URL: Issues, https://gitlab.com/Teigi/skytraq-datalog/issues
Keywords: gps,skytraq,venus,datalog,gpx,nmea
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Requires-Dist: tqdm>=4.60
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pyright>=1.1; extra == "dev"
Dynamic: license-file

# skytraq-datalog

Python driver for **SkyTraq Venus GPS data loggers** (as used in the CanWay GPS app, circa 2012).
Downloads the device's flash datalog over USB-serial and exports it as GPX.

Ported from reverse-engineered C# using the SkyTraq binary protocol.

## Requirements

- Python 3.11+
- `pyserial >= 3.5`
- `tqdm >= 4.60`

## Installation

```bash
pip install skytraq-datalog
```

This installs the `skytraq-download` command.

## Usage

### Command line

Either use as module with `python -m skytraq` or as tool `skytraq-download`

```bash
# Download all tracks, one GPX file per trip
skytraq-download /dev/ttyUSB0

# Custom file prefix
skytraq-download /dev/ttyUSB0 --prefix my_hike

# All trips in one file
skytraq-download /dev/ttyUSB0 --single --out all_tracks.gpx

# Custom initial baud rate (driver switches to 115200 automatically)
skytraq-download /dev/ttyUSB0 --baud 38400

# Adjust the gap that separates trips (default: 10 minutes)
skytraq-download /dev/ttyUSB0 --gap 5
```

By default each trip is written to a separate file named by its UTC start time:
`tracks_2024-03-01_09-15-00.gpx`, `tracks_2024-03-01_14-32-00.gpx`, …

### Python API

```python
from skytraq.gps import SkytraqGPS
from skytraq.gpx import export_gpx, export_gpx_split

gps = SkytraqGPS("/dev/ttyUSB0")
points = gps.download_tracks()          # connects, downloads, reboots device

# One file per trip (split on >10 min gaps or device trip-start markers):
paths = export_gpx_split(points, "track")

# Or everything in one file:
export_gpx(points, "all_tracks.gpx")
```

## How it works

1. Opens the serial port and commands the device to switch to 115200 baud.
2. Queries flash log metadata (sector count, time/distance/speed thresholds).
3. Downloads raw 4096-byte flash sectors in batches, verifying each with an XOR checksum.
4. Reboots the device so it returns to its default baud rate.
5. Decodes each sector entry: GPS week number + time-of-week → UTC, ECEF → LLA, speed.
6. Writes GPX 1.1 files with `<trkpt>`, `<ele>`, `<time>`, and `<speed>` elements.

### Entry types decoded

| Type | Size | Notes |
|------|------|-------|
| `FIX_FULL` | 18 B | Absolute position (ECEF) + absolute timestamp |
| `FIX_HALF` | 8 B | Differential ECEF delta + delta TOW from previous entry |
| `FIX_POI` | 18 B | Point-of-interest, same encoding as FIX_FULL |
| `FIX_FULL_MULTI_HZ` | 20 B | High-frequency fix; direct LLA fixed-point + ms TOW |
| `FIX_POI_MULTI_HZ` | 20 B | High-frequency POI |
| `FIX_FULL_TRIP` | — | FIX_FULL promoted to trip-start by a flag bit |
| `FIX_FULL_TRIP_MULTI_HZ` | — | FIX_FULL_MULTI_HZ promoted to trip-start |

### Known limitations

- GPS leap-second offset is hard-coded to **15 seconds** (correct for data logged before 2017-01-01; add 1 second per subsequent leap second if needed).
- Altitude is **ellipsoidal height** (WGS-84). No EGM96 geoid correction is applied, so altitudes read roughly 10–50 m higher than mean sea level depending on location.

## Project layout

```
src/
├── __main__.py    # CLI entry point (skytraq-download)
├── gps.py         # SkytraqGPS driver: serial I/O, packet framing, commands
├── decompress.py  # Flash sector decoder: entry parsing, coordinate conversion
├── gpx.py         # GPX 1.1 writer and trip splitter
└── types.py       # Dataclasses (LogPoint, LogInfo, LLA, ECEF) and enums
```

## License

MIT
