96 lines
5.7 KiB
Markdown
96 lines
5.7 KiB
Markdown
# 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.
|