Metadata-Version: 2.4
Name: mti8-navigation
Version: 1.0.0
Summary: Real-time navigation system for the Xsens MTi-8 IMU/GNSS sensor
Author-email: Eshan Sengupta <eshansengupta2000@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/eshansengupta2000/MTi8-Navigation
Project-URL: Repository, https://github.com/eshansengupta2000/MTi8-Navigation.git
Project-URL: Documentation, https://github.com/eshansengupta2000/MTi8-Navigation/blob/main/README.md
Project-URL: Issues, https://github.com/eshansengupta2000/MTi8-Navigation/issues
Keywords: xsens,mti-8,imu,gnss,rtk,navigation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Requires-Dist: numpy>=1.21
Requires-Dist: PyQt5>=5.15
Requires-Dist: PyQtWebEngine>=5.15
Requires-Dist: pyqtgraph>=0.13
Requires-Dist: platformdirs>=3.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=1.0; python_version < "3.11"
Provides-Extra: threed
Requires-Dist: open3d>=0.14; extra == "threed"
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# MTi-8 Navigation System

Real-time navigation system for the [Xsens MTi-8](https://www.xsens.com/mti-8) IMU/GNSS sensor. Reads sensor data over serial, decodes the Xsens Xbus/MTData2 binary protocol, fuses GNSS with inertial navigation, and presents everything in a live dashboard.

## Capabilities

- **Full Xsens Xbus/MTData2 protocol decoding** -- quaternion, Euler, acceleration, gyro, magnetic, barometric, temperature, delta-v/q, UTC time, packet counter
- **UBX NAV-PVT GNSS decoding** -- position, velocity, accuracy, DOP, heading, fix type, satellite count, carrier phase
- **RTK correction pipeline** -- NTRIP v2 client + RTCM injection into the MTi-8 serial stream
- **Live PyQt5 dashboard** -- status cards, roll/pitch/yaw strip charts, Leaflet map with position marker and trail
- **Optional Open3D 3D scene** -- vehicle mesh, coordinate frames, trajectory point cloud
- **CSV logging** -- 65+ columns via background thread, zero missed writes
- **Serial auto-detection** -- scans USB ports for Xsens VID, tries all standard baud rates
- **Standalone diagnostic tools** -- baud rate sniffer, packet frequency analyzer, raw GNSS hex dumper

## Architecture

```
MTi-8 Hardware (USB-serial)
       │
  SerialReader (thread)
       │
  XbusParser ──► NavigationState (50+ fields, zero-alloc)
       │
       ├──► IMUParser ──────── attitude, accel, gyro
       ├──► GNSSParser ─────── position, velocity, accuracy
       ├──► GPSStatus ──────── health score, RTK status
       ├──► Dashboard ──────── PyQt5 labels, plots, map
       ├──► CSVLogger ──────── 65+ column CSV
       └──► SceneManager ───── Open3D vehicle + trajectory

NTRIPClient (thread)
       │
  RTCMInjector (thread) ──► MTi-8 serial port
```

**Threading:** SerialReader, NTRIP, RTCMInjector, and CSVLogger each run in their own thread. The Qt main loop handles dashboard redraw at 60 Hz and scene update at 30 Hz.

## Project Structure

```
src/mti8_navigation/
  main.py                  Entry point / CLI app launcher
  config.py                Config loader (TOML + defaults)
  defaults.py              Protocol constants, enums, immutable defaults
  setup_wizard.py          Interactive setup CLI
  sdk_setup.py             Driver detection + guidance

  xsens/                   Sensor protocol layer
    serial_reader.py       Threaded serial reader (auto-detect port/baud)
    xbus_parser.py         Xbus frame parser, updates NavigationState
    navigation_state.py    @dataclass, single source of truth
    quaternion.py          Pure-Python quaternion math
    imu_parser.py          IMU field accessor
    gnss_parser.py         GNSS field accessor
    decoder/               XDI field decoders (one per data type)

  rtk/                     RTK correction pipeline
    ntrip_client.py        NTRIP v2 client
    rtcm_injector.py       Injects RTCM into serial stream
    gps_status.py          GPS/RTK health aggregator

  visualization/           GUI layer
    dashboard.py           PyQt5 main window
    map.html               Leaflet.js map (bundled as package data)
    scene_manager.py       Open3D 3D scene
    vehicle3d.py           Procedural vehicle mesh
    trajectory.py          ENU trajectory management
    coordinate_frames.py   ECEF/ENU/NED transforms

  logger/
    csv_logger.py          Threaded CSV writer

  tools/                   Diagnostic utilities
    sniffer.py             Baud rate auto-detection
    packet_analyser.py     XDI packet frequency analyzer
    dump_gnss_pvt.py       Raw GNSS hex dumper
```

## Setup

### Install the package

```bash
# With 3D visualization support (Open3D)
pip install mti8-navigation[threed]

# Or without 3D (lighter installation)
pip install mti8-navigation
```

### Configure and run

```bash
# Interactive setup wizard (guides you through driver detection, NTRIP, port selection)
mti8nav-setup

# Start the navigation system
mti8nav
```

**Linux users:** The setup wizard will prompt you to add your user to the `dialout` group if needed.

**macOS/Windows:** USB drivers are usually built-in, but the setup wizard will guide you if needed.

### ⚠️ Security Note

If using NTRIP RTK corrections, the setup wizard stores your NTRIP credentials in the user config file (plaintext). **If you have hardcoded NTRIP credentials in old git history, please rotate them** — this repository was converted from a development project where credentials were committed. Use NTRIP accounts specific to this system, or a read-only token if your provider supports it.

## Configuration

User configuration lives in a TOML file created by `mti8nav-setup`:

- **Linux:** `~/.config/mti8nav/config.toml`
- **macOS:** `~/Library/Application Support/mti8nav/config.toml`
- **Windows:** `%APPDATA%\mti8nav\config.toml`

You can hand-edit the TOML file or rerun `mti8nav-setup` to update settings. Key sections:

| Section | Defaults |
|---|---|
| Serial | `/dev/ttyUSB0` @ 2M baud (auto-detected) |
| NTRIP | Caster `195.182.72.152:2111`, mountpoint `VRS_RTCM31` |
| Approx. Location | 54.7215N, 25.3377E, alt 202m |
| Filters | Attitude EMA alpha=0.2, median window=5 |
| GUI | 2000x900, 60Hz refresh, 30Hz scene |
| Debug | Off by default -- enable per subsystem |

## Diagnostic Tools

Standalone CLI tools for hardware debugging (no GUI needed):

```bash
# Auto-detect baud rate by counting valid frames
mti8nav-sniffer

# Show per-XDI packet frequency and estimated Hz
mti8nav-packet-analyser

# Raw hex dump of GNSS PVT and Status Word fields
mti8nav-dump-gnss
```

## Requirements

- Xsens MTi-8 connected via USB-to-serial adapter
- Python 3.7+
- MTi-8 configured to output MTData2 with quaternion, GNSS PVT, and status word XDI fields
