hpr_flightdata/lib.rs
1//! Flight-log importers, the canonical flight record, smoothing and time alignment, and the
2//! readings taken from a flight with the provenance of each.
3//!
4//! [Start here][guide-start] says what works today and what is planned.
5//!
6//! [guide-start]: https://hpr.fusionspace.co/start-here.html
7//! [roadmap]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/ROADMAP.md
8//! [adr-046]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/DECISIONS.md#adr-046-debrief-folded-in-and-flight-log-analysis-that-stands-without-the-simulator-2026-09-20
9//!
10//! This crate doesn't depend on the simulator, and [must not][adr-046]. Reading a flight log and
11//! working out what it says is a use of this project in its own right. It serves someone who has
12//! a log and neither a design file nor any wish to simulate anything. Comparing a flight with a
13//! simulation of it is `hpr-forensics`, which depends on both.
14//!
15//! Every reading carries where it came from: measured by an instrument, derived from what was
16//! measured, or clipped because the sensor saturated. A reading the log can't support is withheld
17//! with a reason rather than printed.
18//!
19//! Status: pre-alpha. [`import::read`] recognizes a log's layout from its content. It reads the
20//! log into the record every reader produces ([`log::FlightLog`]). The readers for altimeters and
21//! flight computers:
22//!
23//! - PerfectFlite's `.pf2`, its CSV and text exports, and its older `.pfa` ([`perfectflite`]).
24//! - AltOS's CSV, and a table of AltOS's own columns with no `version` header ([`altos`]). It also
25//! reads an AltOS export a spreadsheet re-saved with formula cells, each formula kept as text.
26//! - AltOS's radio telemetry as AltosUI saves it ([`altos_telem`]).
27//! - AltOS's radio telemetry decoded to a table ([`altos_telem_csv`]).
28//! - AltOS's raw downloads: the board's own log as AltosUI saves it to an `.eeprom` file
29//! ([`altos_eeprom`]). It's checked against AltosUI's export of the same flight in all 9 samples
30//! that have one.
31//! - The Featherweight Raven's FIP CSV ([`raven`]). A FIP export that lost its header line is read
32//! under the header the caller states ([`raven::read_rows`]).
33//! - The Blue Raven's CSV ([`blueraven`]).
34//! - The Blue Raven's USB download to a serial terminal, each line held to its CRC
35//! ([`blueraven_usb`]).
36//! - The Featherweight app's summaries of a Blue Raven's or a GPS tracker's flight
37//! ([`fwsummary`]).
38//! - Missile Works RRC3's CSV ([`rrc3`]).
39//! - Two raw downloads, the Raven's `.FIPa` ([`raven_fipa`]) and the RRC3's `.rff`
40//! ([`rrc3_rff`]). Each is checked against its maker's export of the same flight where the
41//! sample logs hold one. That's 55 of the 57 `.FIPa` files and 1 of the 6 `.rff`.
42//! - Eggtimer's CSV, an Eggtimer TRS's terminal text, and an Eggtimer's download saved as RTF
43//! ([`eggtimer`]).
44//! - AltimeterCloud's CSV ([`altimetercloud`]).
45//! - Entacore AIM's CSV ([`entacore`]).
46//! - AerospaceNU's SillyGoose logs ([`sillygoose`]).
47//! - AerospaceNU's flight computer board's CSV ([`aerospacenu_fcb`]) and its ground station's
48//! text ([`aerospacenu_gs`]).
49//! - Silicdyne Fluctus's CSV ([`fluctus`]).
50//! - The ARTS2's interpreted data ([`arts2`]).
51//! - The ARTS2's `.odf` and its raw CSV export ([`arts2_raw`]). The `.odf` is read in units held
52//! to the interpreted export of the same flight.
53//! - The R-DAS's raw text, its counts kept as written ([`rdas`]).
54//! - A phone app's `launch` CSV ([`phone_launch`]).
55//! - A course's Teensy data logger, one sensor's reading a line ([`teensy`]).
56//! - One team's radio telemetry packets, `255:…:254`, as its flight computer logged them, as a
57//! receiver heard them, and inside an RTF document ([`packets`]).
58//! - A MARSA altimeter's download and a spreadsheet's re-save of it ([`marsa`]).
59//!
60//! An AltiMAX's own `.ALS` file is read too ([`altimax_als`]), as are an Entacore AIM's `.xtra`
61//! files and raw dumps of its memory ([`entacore_raw`]). Each of these layouts was worked out from
62//! one sample flight and held to the maker's conversion of it.
63//!
64//! Five GPS logs are read, every column kept as a channel on its own clock:
65//!
66//! - Featherweight's tracker and ground-station CSV ([`fwgps`]).
67//! - KML ([`kml`]).
68//! - NMEA 0183 ([`nmea`]).
69//! - Missile Works' RTx tracker's `.rtx` file and its CSV and text exports ([`rtx`]).
70//! - GPX 1.0 and 1.1, checked on invented files only ([`gpx`]).
71//!
72//! Files from other loggers, and files that hold other files:
73//!
74//! - A table from a logger no other reader knows is read by the units its header states
75//! ([`generic`]). Each unit is held to the column's name and values. The caller can give a
76//! column mapping instead.
77//! - A team flight computer's binary records are read by a layout the caller states. They come
78//! from a raw file ([`records`]) or a serial console's capture of them as base64 ([`capture`]).
79//! - A mapping or a layout can come from the JSON file a person writes for their own logger
80//! ([`custom`]). That's how the command line and Python take them.
81//! - A zip archive of a flight's files is unpacked in memory, within a bound, and each file is
82//! read on its own ([`archive`]).
83//! - An Excel workbook's sheets are written out as text, each cell as the workbook stores it, and
84//! each sheet is read on its own ([`workbook`]).
85//! - An older Excel `.xls` worksheet's cells are written out as text ([`xls`]). An AltiMAX
86//! altimeter's export is one such worksheet ([`altimax`]).
87//!
88//! [`readings`] takes a first set of readings from the record. They're liftoff, apogee, the top
89//! speed and acceleration, burnout, landing, the flight time, and the descents under the drogue
90//! and the main. Each states the bound its error stays within. On the synthetic flights' tuning
91//! set, logged from 500 to half a sample a second and in the other conditions [`readings`] lists,
92//! every reading given stayed within its bound. The guide's [reading a flight log][guide-log]
93//! page shows them on a log, and [the layouts read][guide-layouts] lists what each
94//! reader keeps. The rest of the readings, smoothing and reconstruction are planned ([the
95//! roadmap][roadmap]).
96//!
97//! [guide-layouts]: https://hpr.fusionspace.co/format/flight-logs.html
98//!
99//! [guide-log]: https://hpr.fusionspace.co/reading-a-flight-log.html
100//!
101//! ```
102//! use hpr_flightdata::{perfectflite, readings};
103//!
104//! // A few rows of an invented PerfectFlite log: feet and seconds.
105//! let mut text = String::from("PerfectFlite Pnut\nData: (Time, Altitude, Velocity)\n");
106//! for (i, feet) in [0, 0, 0, 40, 90, 120, 130, 130, 120, 90, 40, 5, 0, 0, 0, 0].iter().enumerate() {
107//! text.push_str(&format!("{}, {feet}, 0\n", i as f64 * 0.5));
108//! }
109//! let log = perfectflite::read(&text)?;
110//! let read = readings::read(&log);
111//! let apogee = read.apogee.value().expect("the log climbs");
112//! assert_eq!(apogee.altitude_m, 130.0 * 0.3048);
113//! assert_eq!(apogee.time_s, 3.25); // midway between the two samples at the top
114//! # Ok::<(), hpr_flightdata::error::LogError>(())
115//! ```
116
117// Outside bytes reach casts here. An `as` cast of a length or count truncates silently where
118// `usize` is 32 bits (wasm32), and one from a float saturates: each cast is checked with
119// `try_from`, or its `allow` says why it is exact or meant.
120#![warn(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
121#![cfg_attr(
122 test,
123 allow(
124 clippy::cast_possible_truncation,
125 clippy::cast_sign_loss,
126 reason = "a test builds its own inputs, so it sets its casts' ranges"
127 )
128)]
129pub mod aerospacenu_fcb;
130pub mod aerospacenu_gs;
131pub mod altimax;
132pub mod altimax_als;
133pub mod altimetercloud;
134pub mod altos;
135pub mod altos_eeprom;
136pub mod altos_telem;
137pub mod altos_telem_csv;
138pub mod archive;
139pub mod arts2;
140pub mod arts2_raw;
141pub mod blueraven;
142pub mod blueraven_usb;
143pub mod capture;
144pub mod custom;
145pub mod eggtimer;
146pub mod entacore;
147pub mod entacore_raw;
148pub mod error;
149pub mod filter;
150pub mod fluctus;
151pub mod fwgps;
152pub mod fwsummary;
153pub mod generic;
154pub mod ghost;
155pub mod gpx;
156pub mod import;
157pub mod kml;
158pub mod log;
159pub mod marsa;
160pub mod nmea;
161pub mod packets;
162pub mod perfectflite;
163pub mod phone_launch;
164pub mod raven;
165pub mod raven_fipa;
166pub mod rdas;
167pub mod readings;
168pub mod records;
169pub mod rrc3;
170pub mod rrc3_rff;
171pub mod rtx;
172pub mod sillygoose;
173pub mod smoother;
174mod table;
175pub mod teensy;
176pub mod timeline;
177pub mod workbook;
178pub mod xls;
179
180#[cfg(test)]
181mod synthetic;