sim_flight_kalman.py

Replay a simulated or recorded rocket flight through a Python mirror of the AURORA Kalman filter and inspect the result graphically.

What it does

The script replicates the two-state (altitude, velocity) constant- acceleration Kalman filter from aurora/lib/filter/kalman.c together with the body-frame gravity tracker from aurora/lib/sensor/attitude.c, so that filter tuning and apogee detection can be analysed offline without flashing firmware.

Two data sources are supported:

  • Synthetic flight (default): a pressure signal is generated from the ISA barometric formula and a body-frame IMU stream (accel + gyro) is synthesized with a slow pitch-over after apogee.

  • Recorded flight (--flight DIR): the script loads telemetry from DIR/flights.influx and the state machine trace from DIR/state_audit, segments the log into individual flights on ARMED → BOOST transitions, and produces one plot per flight with state transitions drawn as vertical markers.

Plots cover pressure, altitude, vertical velocity, the body-frame gravity direction, the gravity-removed world-vertical acceleration, and the three-way apogee vote.

Usage

python3 tools/sim_flight_kalman.py [--flight DIR] [--show]
                                   [--theme {light,dark,both}]
                                   [--dt S] [--pre-boost S] [--cal S]
                                   [--post-main S]
                                   [--q-alt Q] [--q-vel Q] [--r-meas R]
                                   [--debounce N]

Data selection

  • --flight DIR — load real flight data from DIR (expects flights.influx and state_audit). Without this flag, a synthetic flight is generated.

  • --dt — resampling period in seconds for real flight data (default 0.02).

  • --pre-boost — seconds of pre-boost data to keep per flight (default 10).

  • --cal — length of the calibration window before BOOST (default 3).

  • --post-main — seconds of data to keep after the MAIN transition, trimming the long post-parachute tail (default 5).

Kalman tuning

The defaults match the values committed in Kconfig so runs are directly comparable to firmware behaviour.

  • --q-alt — process noise on altitude (default 0.1).

  • --q-vel — process noise on velocity (default 0.5).

  • --r-meas — measurement noise variance (default 4.0).

  • --debounce — apogee debounce ticks (default 3).

Output

  • --theme {light,dark,both} — render plots matching the Furo Sphinx docs theme (default both).

  • --show — open the plots in an interactive matplotlib window in addition to writing them to disk.

On run, the script produces a graph and saves it to a file called flight_simulation.png. Here is an example run:

Plot saved to flight_simulation.png
Ground ref pressure: 101340 Pa (1013.4 hPa)
True apogee:         500.0 m
Filter apogee:       496.4 m (t = 12.56 s)
flight_simulation_light.png flight_simulation_dark.png

Reuse from other scripts

sim_flight_kalman.py also exposes the helpers used by sweep_apogee.py:

  • parse_influx(path) — parse a recorded flights.influx telemetry dump.

  • parse_state_audit(path) — parse a state-machine audit log.

  • segment_flights(events) — split a trace into (boost_ms, end_ms) ranges on ARMED → BOOST transitions.

  • process_real_flight(...) — run one flight through the Python filter and return a dict of time series plus detected apogee indices.

Requirements

  • Python 3.10+

  • numpy, matplotlib