5.7 KiB

Raw Blame History

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:

┌──────────────────────────────────────────────────────────┐
│                      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.

5.7 KiB Raw Blame History Unescape Escape