# MotorSignal — Telemetry Pipeline Architecture

This document describes the runtime sensor pipeline, coordinate frames, sampling frequencies, and state machine architecture of the MotorSignal application.

---

## 1. Pipeline Overview & Sampling Rates

MotorSignal uses an asynchronous dual-input sensor architecture with a high-rate fused telemetry output:

```text
┌──────────────────────────────────────────────────────────┐
│                      SENSING INPUTS                      │
│                                                          │
│  GNSS Receiver (Google Fused Provider):                  │
│    • Interval: 100 ms (~10 Hz)                           │
│    • Accuracy: LocationAccuracy.bestForNavigation        │
│                                                          │
│  IMU (3-Axis Accelerometer & Gyroscope):                 │
│    • Interval: 20 ms (~50 Hz)                            │
│    • Sensors: Linear Acceleration, Gyroscope, Gravity    │
└────────────────────────────┬─────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────┐
│               SENSOR FUSION & FILTERING                  │
│                                                          │
│  Speed Processing:                                       │
│    • Dynamic Fast-Tracking EMA (α=0.90 accel, 0.75 cruise│
│    • Jitter Deadband (< 0.6 m/s treated as 0.0 MPH)      │
│                                                          │
│  Lean Angle Processing:                                  │
│    • Roll/Pitch Complementary Filter (base α=0.94)       │
│    • Dynamic Acceleration Decoupling (α=0.998 on launch) │
│                                                          │
│  3D G-Force Projection:                                  │
│    • Phone linear acceleration projected into bike frame │
│    • Vibration Low-Pass Filter (α=0.40, gate 0.02g)      │
└────────────────────────────┬─────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────┐
│              TELEMETRY VALIDATION LAYER                  │
│                                                          │
│  • Nan / Infinity Numeric Sanity Checks                  │
│  • Rate-of-Change & Physical Limit Bounds               │
│  • Confidence Scoring (GPS, Speed, Lean, G-Force)        │
│  • State Classification (Stationary, Accel, Braking)     │
└────────────────────────────┬─────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────┐
│                  TELEMETRY OUTPUT STREAM                 │
│                                                          │
│  • Heartbeat Rate: 50 ms (~20 Hz)                        │
│  • Event Dispatch: Immediate on GPS / IMU fixes          │
│  • Consumer 1: Evolution / Classic UI Cockpit            │
│  • Consumer 2: Drift SQLite (5-second batching)          │
│  • Consumer 3: Black-Box Field Test Logger               │
└──────────────────────────────────────────────────────────┘
```

> **Note on Terminology**: GNSS input operates at $\approx 10\text{ Hz}$ ($100\text{ms}$ interval) while the telemetry stream delivers $\approx 20\text{ Hz}$ ($50\text{ms}$ interval) updates by combining the latest filtered GNSS position with high-rate $50\text{ Hz}$ IMU sensor fusion.

---

## 2. Coordinate Conventions

### Screen & Vehicle Coordinate Systems
* **Portrait Mount**:
  * $+X$: Right lateral
  * $+Y$: Forward longitudinal
  * $+Z$: Upward vertical
* **Landscape Left Mount**:
  * $+X$: Forward longitudinal
  * $+Y$: Left lateral (inverted to $+Y$ right)
  * $+Z$: Upward vertical

### Angular Conventions
* **Lean Angle (Roll)**:
  * **$0.0^\circ$**: Upright motorcycle.
  * **Positive ($+\theta$)**: Right-hand lean / cornering.
  * **Negative ($-\theta$)**: Left-hand lean / cornering.
* **Pitch Angle**:
  * **Positive ($+\phi$)**: Wheelie / nose-up acceleration.
  * **Negative ($-\phi$)**: Stoppie / nose-down braking.

---

## 3. Database Persistence & Crash Resilience

* **Batch Buffer**: Telemetry samples are buffered in memory and flushed via `db.batch` every 5 seconds.
* **Bounded Capacity**: The buffer is capped at 1,000 samples to protect memory during transient SQLite locks.
* **Incremental Ride Summaries**: Ongoing stats (distance, top speed, max lean, moving/stopped time) are incrementally written to the `Rides` table every 5 seconds.
* **Auto-Recovery**: On startup, unfinished sessions (`endTime.isNull()`) are recovered with the timestamp of the last recorded telemetry breadcrumb.