Skip to main content

hpr_flightdata/
arts2_raw.rs

1//! Ozark Aerospace ARTS2 flight computer's raw data: the `.odf` file its PC software,
2//! DataAnalyzer, saves a downloaded flight to, and the sensors' counts as the software exports
3//! them to CSV.
4//!
5//! The ARTS2 reads an Analog Devices ADXL78 accelerometer, set for ±50 g, and a Motorola
6//! MPXA4100A pressure sensor with its processor's 10-bit converter, and records both at a rate
7//! its owner sets (*ARTS2 User Manual*, V1.0.0, Ozark Aerospace, 2007, Appendix A, p. 16; p. 7).
8//! *Flight → Save As* keeps a download as an `.odf` file (p. 14). The manual describes neither
9//! the `.odf`'s bytes nor a raw export; what follows was worked out from the three flights among
10//! the project's sample logs that hold both, each beside the software's interpreted export of the
11//! same flight ([`crate::arts2`]), with no other program's source read.
12//!
13//! # The `.odf`
14//!
15//! Little-endian throughout:
16//!
17//! | Offset | Bytes | What |
18//! |---|---|---|
19//! | 0 | 4 + 9 | the length 9, then `Ozark.odf` |
20//! | 13 | 20 | five 32-bit words, 3, 3, 1, 61 and 2 in every sample file; not read |
21//! | 33 | 256 | the board's settings and calibration (below) |
22//! | 289 | 4 | the number of records, `n` |
23//! | 293 | 12 | three 32-bit words, each the memory's size in records; equal, and at least `n` |
24//! | 305 | 8 `n` | the records |
25//! | 305 + 8 `n` | 124 | the software's own settings; not read |
26//!
27//! A file whose length isn't `305 + 8n + 124` is refused, as are three sizes that disagree or `n`
28//! over them. Of the settings block, the reader takes three things, at these offsets within it:
29//!
30//! - 10, a 16-bit word: the barometer's count on the pad, the "Zero Altitude baseline" the board
31//!   averages from 16 samples on entering flight mode (p. 17);
32//! - 12, a 16-bit word: eight times the accelerometer's count on the pad, its "Zero G baseline",
33//!   likewise averaged (p. 16), so that it keeps an eighth of a count;
34//! - 20, 22 and 24, three 16-bit words: the sums of 64 accelerometer readings the board takes
35//!   when calibrated on its side and on either end, "at +1g, −1g, and 0", which "are sent along
36//!   with flight data" (p. 16). In every sample file the middle one is the reading on its side.
37//!
38//! And at 8, a 16-bit word that is 2 in every sample file, all recorded at 50 a second; a file
39//! whose word isn't 2 is refused (the clock, below). Its other bytes, among them the two flight
40//! profiles' deployment settings, aren't decoded. Each record is four
41//! 16-bit words, in the order of the raw export's columns (below): the accelerometer's count, a
42//! byte of flags and low bits, the barometer's count and the board's state.
43//!
44//! **The first record** is the baselines, not a sample: its barometer count is the pad's, and its
45//! accelerometer count is the pad's eighth-count baseline cut to a whole count. A file whose first
46//! record isn't so is refused: its bytes are laid out otherwise than the sample files'. The
47//! software exports it as the flight's first row, at time 0, and so does the reader.
48//!
49//! **The clock.** The records are 0.02 s apart (50 a second), from the first: the rate DataAnalyzer
50//! gives every sample file's records in both its exports. The owner sets the rate, in each of the
51//! board's two flight profiles (pp. 6–7), and where the file keeps it isn't known: the sample files
52//! are all at one rate, so no byte can be shown to change with it. The reader fails closed on the
53//! one candidate, the settings word at 8, small and the same in every sample file: a file whose
54//! word isn't 2 is refused. If the rate is kept elsewhere, a file recorded at another rate is
55//! caught only by the climb check (below), loosely: a clock whose step is `k` times the true one
56//! makes the climb by the acceleration `k²` times larger over the same records, so the check
57//! passes a `k` from `√(r / (5/3))` to `√(r / 0.6)`, `r` the flight's ratio on its true clock: 0.67
58//! to 1.12 at the sample files' least ratio, 0.754, and 0.83 to 1.38 at their greatest, 1.145.
59//! Every record says so in a note.
60//!
61//! **Units.**
62//!
63//! | Record word | Column | Quantity | As read |
64//! |---|---|---|---|
65//! | 0 | `Acc(HI)` | [`Quantity::Acceleration`], along the board's long axis, toward its forward end, with the pad's reading taken out | from the calibration (below) |
66//! | 1 | `Acc/Baro(LO)` | [`Quantity::Unrecognized`] | the byte as written |
67//! | 2 | `Baro(HI)` | [`Quantity::Pressure`] | by the sensor's transfer function (below) |
68//! | 3 | `State` | [`Quantity::Number`] | the byte as written |
69//!
70//! The columns' names are the raw export's; the `.odf` names none.
71//!
72//! *The acceleration.* The ±1 g sums are 2 g apart, so a g is a 128th of their difference, in
73//! counts; the reading on the pad, nose up, lies near the end sum on the forward end's side, which
74//! sets the sign: `a = ±(count − pad) / per_g × g₀`. As the software's interpreted export does,
75//! the pad's reading is taken out, so the acceleration on the pad reads zero, gravity with it.
76//! That takes out gravity exactly only while the board points as it did on the pad: once the
77//! rocket tips over in the coast, the reading runs below the acceleration along the axis by
78//! `g₀ (cos θ_pad − cos θ)`, `θ` the board's angle from the vertical, up to a g. The first
79//! record, the baselines', reads the pad's whole count less its eighth-count baseline, up to
80//! 7/8 of a count below zero, not zero. The
81//! calibration is refused unless the ADXL78's data sheet bears it out (*ADXL78*, Rev. B, Analog
82//! Devices, 2010, Specifications, AD22280 for ±50 g, p. 3; the output is ratiometric to its
83//! 5 V supply, which the converter reads against, so a count is 5 V / 1,024): a g from 36.1 to
84//! 39.9 mV, 7.39 to 8.17 counts, and the side's reading within ±150 mV of half the supply,
85//! 512 ± 30.72 counts, between the two end sums; and the pad's reading nearer the end sum on its
86//! side than the side's, a tilt under 60°.
87//!
88//! *The pressure.* `P = (count / 1,024 + 0.1518) / 0.010 59` kPa, the sensor's nominal transfer
89//! function, `V_out = V_S (0.010 59 P − 0.1518)` (*MPX4100A*, Rev 9, Freescale, 2009, p. 5,
90//! p. 6), read against the supply as the converter's full scale. The pad's count must give a
91//! pressure in the sensor's rated 20 to 105 kPa (p. 3). The sensor's error band is ±1.5 kPa over
92//! that range from 0 to 85 °C (p. 6).
93//!
94//! **The climb check** is each unit's second check, and the clock's: over the first 2 s from the
95//! first record, the climb by the pressure, its pressure altitude in the U.S. Standard
96//! Atmosphere, 1976, at the window's end (the median of the 5 records within 0.04 s of it) less
97//! the pad's, over the climb by the acceleration integrated twice by the trapezoid rule from rest
98//! at the first record, must lie from 0.6 to 5/3, as for an AltOS raw download
99//! ([`crate::altos_eeprom`]), and the rocket must climb by both. The window is twice AltOS's 1 s:
100//! one count of this barometer is 92 Pa, 7.7 m of height near sea level and more at a higher
101//! site, so a 1 s window held two counts of one sample file's climb; 2 s holds at least 10 in
102//! each. A file whose climb
103//! can't be measured, or falls outside the band, is refused: its clock rests on that check as
104//! much as its units do, and a count kept as written can't be put on a clock nothing bears out.
105//!
106//! **The flags byte.** Its bits 3 and 2 are the barometer count's low two bits, in every record of
107//! every sample file; a record whose aren't is refused, a check that the record's words are where
108//! the reader takes them. Its other bits follow the flight (bits 5 and 4 set about the apogee,
109//! bits 1 and 0 before the main's), and bits 7 and 6 match the accelerometer count's low two
110//! bits in one sample file and in 57 to 62% of the others' records, so the byte is kept as
111//! written. So is `State`, which steps through 0, 1, 2, 3, 5, 6 and 7 in the flights in order;
112//! no document names them, so no event is taken from it.
113//!
114//! **The primary track.** The file holds no altitude, so [`FlightLog::time_s`] and
115//! [`FlightLog::altitude_m`] are empty, as for the Raven's raw `.FIPa`, and every word is a
116//! channel. [`Stated::figures`] holds the two baselines and the three calibration sums.
117//!
118//! # The raw CSV
119//!
120//! The software's raw export of the same records: a `MET,Acc(HI),Acc/Baro(LO),Baro(HI),State`
121//! header, then a row for each record, its time and its four words as whole numbers:
122//!
123//! ```text
124//! MET,Acc(HI),Acc/Baro(LO),Baro(HI),State
125//! 0.000,512,1,780,64
126//! 0.020,575,1,780,0
127//! ```
128//!
129//! In every sample file its rows are its `.odf`'s records, one for one. **Recognition**: the first
130//! line that isn't blank is that header, its names compared as written. The file holds no
131//! calibration, only the first record's whole-count baselines, so no column is converted, and
132//! `MET`, DataAnalyzer's clock, is kept as the time:
133//!
134//! | Column | Quantity | As read |
135//! |---|---|---|
136//! | `MET` | the clock, s | as written; each greater than the row before's |
137//! | `Acc(HI)`, `Baro(HI)` | [`Quantity::Unrecognized`] | the converter's counts, whole numbers 0 to 1,023, as written |
138//! | `Acc/Baro(LO)`, `State` | [`Quantity::Unrecognized`], [`Quantity::Number`] | whole numbers 0 to 255, as written |
139//!
140//! Every row must hold five numbers, and its flags byte the barometer's low bits as above, or the
141//! file is refused, naming the line. Read the flight's `.odf` for its values in units.
142
143use crate::error::LogError;
144use crate::log::{Channel, Figure, FlightLog, LogFormat, Quantity, Stated};
145
146/// The `.odf` format's name in errors.
147const ODF: &str = "ARTS2 .odf";
148
149/// The raw CSV format's name in errors.
150const CSV: &str = "ARTS2 raw CSV";
151
152/// The logger, as the record names it.
153const LOGGER: &str = "Ozark Aerospace ARTS2";
154
155/// The `.odf`'s first 13 bytes: the length 9, then the name.
156const MAGIC: &[u8; 13] = b"\x09\x00\x00\x00Ozark.odf";
157
158/// Where the settings block starts, and its length.
159const BLOCK_AT: usize = 33;
160const BLOCK_LEN: usize = 256;
161
162/// Where the record count is, then the three memory sizes, then the records.
163const COUNT_AT: usize = BLOCK_AT + BLOCK_LEN;
164const SIZES_AT: usize = COUNT_AT + 4;
165const RECORDS_AT: usize = SIZES_AT + 12;
166
167/// A record's length, bytes, and the software's settings' after the records.
168const RECORD_LEN: usize = 8;
169const TRAILER_LEN: usize = 124;
170
171/// Offsets within the settings block: the pad's barometer count, eight times its accelerometer
172/// count, and the three calibration sums.
173const PAD_BARO: usize = 10;
174const PAD_ACC_EIGHTHS: usize = 12;
175const CALIBRATION_SUMS: usize = 20;
176
177/// The settings word that may hold the rate, and its value in every sample file (module docs,
178/// *The clock*).
179const RATE_WORD: usize = 8;
180const RATE_CODE: u16 = 2;
181
182/// How many readings each calibration sum adds up (Appendix A, p. 16).
183const SUMMED: f64 = 64.0;
184
185/// The records' rate, a second: DataAnalyzer's exports put every sample file's 0.02 s apart.
186const RATE_HZ: f64 = 50.0;
187
188/// The raw CSV's header.
189const HEADER: [&str; 5] = ["MET", "Acc(HI)", "Acc/Baro(LO)", "Baro(HI)", "State"];
190
191/// The largest count of the 10-bit converter, and of a byte.
192const MAX_COUNT: u16 = 1_023;
193const MAX_BYTE: u16 = 255;
194
195/// Standard gravity, m/s².
196const STANDARD_GRAVITY: f64 = 9.806_65;
197
198/// One count of the converter, mV: 5 V over 1,024.
199const COUNT_MV: f64 = 5_000.0 / 1_024.0;
200
201/// The ADXL78's sensitivity for ±50 g (AD22280) at a 5 V supply, mV/g, least and most (Rev. B,
202/// p. 3).
203const ADXL78_MV_PER_G: std::ops::RangeInclusive<f64> = 36.1..=39.9;
204
205/// How far the ADXL78's output at zero g may lie from half its supply, mV (Rev. B, p. 3).
206const ADXL78_ZERO_G_MV: f64 = 150.0;
207
208/// The MPX4100A's rated pressures, Pa (Rev 9, p. 3).
209const MPX4100A_PA: std::ops::RangeInclusive<f64> = 20_000.0..=105_000.0;
210
211/// The climb check's window, records: 2 s at 50 a second.
212const CLIMB_WINDOW: usize = 100;
213
214/// Half the span, records, of those whose median pressure ends the window: 0.04 s.
215const CLIMB_END: usize = 2;
216
217/// The barometer's step, as the format's resolution ([`LogFormat::altitude_resolution_m`]): the
218/// files write no altitude, but the pressure moves by one count of the converter, 92.2 Pa (the
219/// transfer function's slope, module docs), 7.68 m near sea level (`Δh = Δp / (ρ₀ g₀)`). Aloft
220/// it is larger.
221pub const ALTITUDE_STEP_M: f64 = 1_000.0 / (1_024.0 * 0.010_59) / (1.225 * STANDARD_GRAVITY);
222
223/// Whether a file's bytes are an `.odf`: they open with the length 9 and `Ozark.odf`.
224pub fn recognizes_odf(bytes: &[u8]) -> bool {
225    bytes.starts_with(MAGIC)
226}
227
228/// Whether a file's text is the raw CSV: its first line that isn't blank is the header, its lines
229/// ending in CR, LF or both.
230pub fn recognizes_csv(text: &str) -> bool {
231    text.strip_prefix('\u{feff}')
232        .unwrap_or(text)
233        .split(['\r', '\n'])
234        .find(|line| !line.trim().is_empty())
235        .is_some_and(is_header)
236}
237
238/// Whether a line is the raw CSV's header.
239fn is_header(line: &str) -> bool {
240    line.trim().split(',').map(str::trim).eq(HEADER)
241}
242
243/// One record: the accelerometer's count, the flags byte, the barometer's count and the state.
244#[derive(Debug, Clone, Copy, PartialEq)]
245struct Record {
246    acc: u16,
247    flags: u16,
248    baro: u16,
249    state: u16,
250}
251
252impl Record {
253    /// Why the record's words can't be the board's, if they can't: a count over the converter's,
254    /// a byte over 255, or a flags byte whose bits 3 and 2 aren't the barometer count's low bits.
255    fn fault(&self) -> Option<String> {
256        if self.acc > MAX_COUNT || self.baro > MAX_COUNT {
257            return Some(format!(
258                "the counts {} and {} aren't both a 10-bit converter's",
259                self.acc, self.baro
260            ));
261        }
262        if self.flags > MAX_BYTE || self.state > MAX_BYTE {
263            return Some(format!(
264                "the flags {} and state {} aren't both a byte",
265                self.flags, self.state
266            ));
267        }
268        if (self.flags >> 2) & 3 != self.baro & 3 {
269            return Some(format!(
270                "the flags byte {} doesn't hold the barometer count {}'s low bits",
271                self.flags, self.baro
272            ));
273        }
274        None
275    }
276}
277
278/// The settings block's baselines and calibration.
279#[derive(Debug, Clone, Copy)]
280struct Calibration {
281    pad_baro: u16,
282    pad_acc_eighths: u16,
283    sums: [u16; 3],
284}
285
286/// The acceleration's conversion: the pad's count, the counts a g, and the sign.
287#[derive(Debug, Clone, Copy)]
288struct Axis {
289    pad: f64,
290    per_g: f64,
291    sign: f64,
292}
293
294impl Axis {
295    /// A count's acceleration, m/s².
296    fn acceleration(&self, count: u16) -> f64 {
297        self.sign * (f64::from(count) - self.pad) / self.per_g * STANDARD_GRAVITY
298    }
299}
300
301impl Calibration {
302    /// The acceleration's conversion, or why the data sheet doesn't bear the calibration out.
303    fn axis(&self) -> Result<Axis, String> {
304        let [a, side, b] = self.sums.map(|sum| f64::from(sum) / SUMMED);
305        let per_g = (b - a).abs() / 2.0;
306        let mv_per_g = per_g * COUNT_MV;
307        if !ADXL78_MV_PER_G.contains(&mv_per_g) {
308            return Err(format!(
309                "the calibration's ends, {a:.2} and {b:.2} counts, make a g {mv_per_g:.2} mV, \
310                 outside the ADXL78's 36.1 to 39.9"
311            ));
312        }
313        let off_mv = (side - 512.0) * COUNT_MV;
314        if off_mv.abs() > ADXL78_ZERO_G_MV || side <= a.min(b) || side >= a.max(b) {
315            return Err(format!(
316                "the calibration's side reading, {side:.2} counts, isn't zero g. It must lie \
317                 between the calibration's ends, {a:.2} and {b:.2}. It must also be within the \
318                 ADXL78's 150 mV of half its supply (it is {off_mv:.1} mV)"
319            ));
320        }
321        let pad = f64::from(self.pad_acc_eighths) / 8.0;
322        let near = if (pad - a).abs() < (pad - b).abs() {
323            a
324        } else {
325            b
326        };
327        if (pad - near).abs() >= (pad - side).abs() {
328            return Err(format!(
329                "the pad's reading, {pad:.3} counts, lies nearer the side's, {side:.2}, than \
330                 either end's: the board wasn't upright on the pad"
331            ));
332        }
333        Ok(Axis {
334            pad,
335            per_g,
336            sign: if near > side { 1.0 } else { -1.0 },
337        })
338    }
339}
340
341/// A barometer count's pressure, Pa, by the MPX4100A's nominal transfer function.
342fn pressure_pa(count: u16) -> f64 {
343    (f64::from(count) / 1_024.0 + 0.1518) / 0.010_59 * 1_000.0
344}
345
346/// A little-endian 16-bit word at an offset; the caller has checked the length.
347fn word(bytes: &[u8], at: usize) -> u16 {
348    u16::from_le_bytes([bytes[at], bytes[at + 1]])
349}
350
351/// A little-endian 32-bit word at an offset; the caller has checked the length.
352fn long(bytes: &[u8], at: usize) -> u32 {
353    u32::from_le_bytes([bytes[at], bytes[at + 1], bytes[at + 2], bytes[at + 3]])
354}
355
356/// A fault in an `.odf`'s bytes.
357fn fault(offset: usize, message: impl Into<String>) -> LogError {
358    LogError::Binary {
359        format: ODF,
360        offset,
361        message: message.into(),
362    }
363}
364
365/// Reads an ARTS2 `.odf` file.
366///
367/// # Errors
368///
369/// [`LogError::NotThisFormat`] if the bytes don't open as an `.odf`'s; [`LogError::Binary`] if
370/// they aren't laid out as the module docs say, the settings word that may hold the rate isn't
371/// the sample files', the calibration or the pad's pressure isn't borne out by the sensors' data
372/// sheets, or the climb check fails or can't be measured;
373/// [`LogError::NoData`] if the file holds no record after the baselines.
374pub fn read_odf(bytes: &[u8]) -> Result<FlightLog, LogError> {
375    if !recognizes_odf(bytes) {
376        return Err(LogError::NotThisFormat {
377            format: ODF,
378            message: "the file doesn't open with the length 9 and `Ozark.odf`".to_owned(),
379        });
380    }
381    if bytes.len() < RECORDS_AT + TRAILER_LEN {
382        return Err(fault(
383            bytes.len(),
384            format!(
385                "the file ends at {} bytes, before its {} of header and settings",
386                bytes.len(),
387                RECORDS_AT + TRAILER_LEN
388            ),
389        ));
390    }
391    let n = long(bytes, COUNT_AT) as usize;
392    let sizes = [0, 4, 8].map(|k| long(bytes, SIZES_AT + k) as usize);
393    if sizes.iter().any(|&size| size != sizes[0]) || n > sizes[0] {
394        return Err(fault(
395            COUNT_AT,
396            format!(
397                "{n} records and memory sizes {}, {} and {}: the sizes must agree and hold them",
398                sizes[0], sizes[1], sizes[2]
399            ),
400        ));
401    }
402    let expected = n
403        .checked_mul(RECORD_LEN)
404        .and_then(|records| records.checked_add(RECORDS_AT + TRAILER_LEN));
405    if expected != Some(bytes.len()) {
406        return Err(fault(
407            COUNT_AT,
408            format!(
409                "{n} records make a file of {} bytes, not {}",
410                expected.map_or_else(|| "too many".to_owned(), |size| size.to_string()),
411                bytes.len()
412            ),
413        ));
414    }
415    let block = |at: usize| word(bytes, BLOCK_AT + at);
416    let calibration = Calibration {
417        pad_baro: block(PAD_BARO),
418        pad_acc_eighths: block(PAD_ACC_EIGHTHS),
419        sums: [0, 2, 4].map(|k| block(CALIBRATION_SUMS + k)),
420    };
421    let mut records = Vec::with_capacity(n);
422    for k in 0..n {
423        let at = RECORDS_AT + k * RECORD_LEN;
424        let record = Record {
425            acc: word(bytes, at),
426            flags: word(bytes, at + 2),
427            baro: word(bytes, at + 4),
428            state: word(bytes, at + 6),
429        };
430        if let Some(why) = record.fault() {
431            return Err(fault(at, format!("record {k}: {why}")));
432        }
433        records.push(record);
434    }
435    let Some(first) = records.first() else {
436        return Err(LogError::NoData { format: ODF });
437    };
438    let pad_acc = f64::from(calibration.pad_acc_eighths) / 8.0;
439    if first.baro != calibration.pad_baro || f64::from(first.acc) != pad_acc.floor() {
440        return Err(fault(
441            RECORDS_AT,
442            format!(
443                "the first record's counts, {} and {}, aren't the pad's baselines, {} and {pad_acc}",
444                first.acc, first.baro, calibration.pad_baro
445            ),
446        ));
447    }
448    if records.len() < 2 {
449        return Err(LogError::NoData { format: ODF });
450    }
451    let rate_code = block(RATE_WORD);
452    if rate_code != RATE_CODE {
453        return Err(fault(
454            BLOCK_AT + RATE_WORD,
455            format!(
456                "the settings word {rate_code} at the rate's likely place isn't the {RATE_CODE} of \
457                 every sample file, all at 50 records a second. Another rate may be set, and the \
458                 reader can't yet read it"
459            ),
460        ));
461    }
462    let pad_pa = pressure_pa(calibration.pad_baro);
463    if !MPX4100A_PA.contains(&pad_pa) {
464        return Err(fault(
465            BLOCK_AT + PAD_BARO,
466            format!(
467                "the pad's barometer count {} is {:.0} Pa, outside the MPX4100A's 20 to 105 kPa",
468                calibration.pad_baro, pad_pa
469            ),
470        ));
471    }
472    let axis = calibration
473        .axis()
474        .map_err(|why| fault(BLOCK_AT + CALIBRATION_SUMS, why))?;
475
476    let time_s: Vec<f64> = (0..records.len()).map(|k| k as f64 / RATE_HZ).collect();
477    let acceleration: Vec<f64> = records.iter().map(|r| axis.acceleration(r.acc)).collect();
478    let pressure: Vec<f64> = records.iter().map(|r| pressure_pa(r.baro)).collect();
479    let climb = climb(pad_pa, &pressure, &acceleration).map_err(|why| fault(RECORDS_AT, why))?;
480
481    let channel = |column: &str, quantity, values: Vec<f64>| Channel {
482        column: column.to_owned(),
483        quantity,
484        time_s: time_s.clone(),
485        values,
486    };
487    let channels = vec![
488        channel(HEADER[1], Quantity::Acceleration, acceleration),
489        channel(
490            HEADER[2],
491            Quantity::Unrecognized,
492            records.iter().map(|r| f64::from(r.flags)).collect(),
493        ),
494        channel(HEADER[3], Quantity::Pressure, pressure),
495        channel(
496            HEADER[4],
497            Quantity::Number,
498            records.iter().map(|r| f64::from(r.state)).collect(),
499        ),
500    ];
501    let sums = calibration.sums.map(f64::from);
502    let figures = vec![
503        Figure::new(
504            "Zero Altitude baseline",
505            calibration.pad_baro.to_string(),
506            Some(Quantity::Pressure),
507            vec![pad_pa],
508        ),
509        Figure::new(
510            "Zero G baseline",
511            calibration.pad_acc_eighths.to_string(),
512            Some(Quantity::Unrecognized),
513            vec![pad_acc],
514        ),
515        Figure::new(
516            "calibration sums",
517            format!("{},{},{}", sums[0], sums[1], sums[2]),
518            Some(Quantity::Unrecognized),
519            sums.to_vec(),
520        ),
521    ];
522    let notes = vec![
523        format!(
524            "`Acc(HI)` read in m/s², along the board's axis with the pad's reading taken out: a g \
525             is {:.4} counts. That is {:.2} mV, within the ADXL78's 36.1 to 39.9. It comes from \
526             the calibration's ends, {:.2} and {:.2} counts. Its side reading is {:.2} counts, \
527             and the pad's baseline is {:.3} counts",
528            axis.per_g,
529            axis.per_g * COUNT_MV,
530            sums[0] / SUMMED,
531            sums[2] / SUMMED,
532            sums[1] / SUMMED,
533            axis.pad
534        ),
535        format!(
536            "`Baro(HI)` read in pascals, by the MPX4100A's nominal transfer function: the pad's \
537             count {} is {:.0} Pa",
538            calibration.pad_baro, pad_pa
539        ),
540        format!(
541            "`Acc(HI)` and `Baro(HI)` held to each other, and the clock at 50 records a second. \
542             Over the first 2 s the rocket climbs {:.1} m by the pressure in the standard \
543             atmosphere. By the acceleration integrated twice from rest, it climbs {:.1} m. \
544             The ratio is {:.3}, within 0.6 to 5/3",
545            climb.0,
546            climb.1,
547            climb.0 / climb.1
548        ),
549        "`Acc/Baro(LO)` and `State` kept as written: no document names their bits or codes"
550            .to_owned(),
551        "the clock is 50 records a second, the rate of every sample file. The file states none \
552         the reader can read, and the climb check bounds it only loosely"
553            .to_owned(),
554        "the first record is the pad's baselines, as the software's exports place it at time 0"
555            .to_owned(),
556        format!(
557            "not read: the settings block's {} other bytes, and the software's {TRAILER_LEN} \
558             after the records",
559            BLOCK_LEN - 12
560        ),
561    ];
562    Ok(FlightLog {
563        format: LogFormat::Arts2Odf,
564        logger: LOGGER.to_owned(),
565        serial_number: None,
566        firmware: None,
567        flight_number: None,
568        stated: Stated {
569            samples: Some(n),
570            figures,
571            ..Stated::default()
572        },
573        time_s: Vec::new(),
574        altitude_m: Vec::new(),
575        vertical_speed_m_s: None,
576        temperature_k: None,
577        battery_v: None,
578        channels,
579        events: Vec::new(),
580        notes,
581    })
582}
583
584/// The climb check's two climbs, m: by the pressure, and by the acceleration (module docs).
585fn climb(pad_pa: f64, pressure: &[f64], acceleration: &[f64]) -> Result<(f64, f64), String> {
586    if pressure.len() <= CLIMB_WINDOW + CLIMB_END {
587        return Err(format!(
588            "the climb check can't be measured: {} records end before its 2 s window, so \
589             nothing bears out the clock or the units",
590            pressure.len()
591        ));
592    }
593    let dt = 1.0 / RATE_HZ;
594    let (mut speed, mut by_acceleration) = (0.0, 0.0);
595    for pair in acceleration[..=CLIMB_WINDOW].windows(2) {
596        let next = speed + (pair[0] + pair[1]) / 2.0 * dt;
597        by_acceleration += (speed + next) / 2.0 * dt;
598        speed = next;
599    }
600    let mut near = pressure[CLIMB_WINDOW - CLIMB_END..=CLIMB_WINDOW + CLIMB_END].to_vec();
601    let end_pa = crate::filter::median(&mut near).unwrap_or(f64::NAN);
602    let atmosphere = hpr_atmos::ussa76::Ussa76::standard();
603    let height = |pa: f64| atmosphere.pressure_altitude_m(pa).unwrap_or(f64::NAN);
604    let by_pressure = height(end_pa) - height(pad_pa);
605    let ratio = by_pressure / by_acceleration;
606    if by_pressure > 0.0
607        && by_acceleration > 0.0
608        && crate::altos_eeprom::CLIMB_RATIO.contains(&ratio)
609    {
610        Ok((by_pressure, by_acceleration))
611    } else {
612        Err(format!(
613            "over the first 2 s the rocket climbs {by_pressure:.1} m by the pressure and \
614             {by_acceleration:.1} m by the acceleration. The climbs aren't both upward with a \
615             ratio within 0.6 to 5/3 (it is {ratio:.3}). Nothing bears out the clock or the \
616             units"
617        ))
618    }
619}
620
621/// Reads an ARTS2 raw CSV export.
622///
623/// # Errors
624///
625/// [`LogError::NotThisFormat`] if the first line that isn't blank isn't the header;
626/// [`LogError::Syntax`] for a row that doesn't hold five numbers, a count out of its range, a
627/// flags byte without the barometer's low bits, or a time not after the row before's;
628/// [`LogError::NoData`] if no row follows the header.
629pub fn read_csv(text: &str) -> Result<FlightLog, LogError> {
630    let mut lines =
631        crate::table::numbered_lines(text).skip_while(|(_, line)| line.trim().is_empty());
632    if !lines.next().is_some_and(|(_, line)| is_header(line)) {
633        return Err(LogError::NotThisFormat {
634            format: CSV,
635            message: format!(
636                "the first line that isn't blank isn't `{}`",
637                HEADER.join(",")
638            ),
639        });
640    }
641    let mut time_s = Vec::new();
642    let mut records = Vec::new();
643    for (line_number, line) in lines {
644        if line.trim().is_empty() {
645            continue;
646        }
647        let syntax = |message: String| LogError::Syntax {
648            format: CSV,
649            line: line_number,
650            message,
651        };
652        let cells: Vec<&str> = line.split(',').map(str::trim).collect();
653        let [met, acc, flags, baro, state] = cells[..] else {
654            return Err(syntax(format!("{} cells, not 5", cells.len())));
655        };
656        let time: f64 = met
657            .parse()
658            .ok()
659            .filter(|t: &f64| t.is_finite())
660            .ok_or_else(|| syntax(format!("`MET` {} isn't a number", crate::table::short(met))))?;
661        if time_s.last().is_some_and(|&last| time <= last) {
662            return Err(syntax(format!("`MET` {time} isn't after the row before's")));
663        }
664        let whole = |cell: &str, name: &str| {
665            cell.parse::<u16>().map_err(|_| {
666                syntax(format!(
667                    "`{name}` {} isn't a count",
668                    crate::table::short(cell)
669                ))
670            })
671        };
672        let record = Record {
673            acc: whole(acc, HEADER[1])?,
674            flags: whole(flags, HEADER[2])?,
675            baro: whole(baro, HEADER[3])?,
676            state: whole(state, HEADER[4])?,
677        };
678        if let Some(why) = record.fault() {
679            return Err(syntax(why));
680        }
681        time_s.push(time);
682        records.push(record);
683    }
684    if records.is_empty() {
685        return Err(LogError::NoData { format: CSV });
686    }
687    let channel = |k: usize, quantity, word: fn(&Record) -> u16| Channel {
688        column: HEADER[k].to_owned(),
689        quantity,
690        time_s: time_s.clone(),
691        values: records.iter().map(|r| f64::from(word(r))).collect(),
692    };
693    let channels = vec![
694        channel(1, Quantity::Unrecognized, |r| r.acc),
695        channel(2, Quantity::Unrecognized, |r| r.flags),
696        channel(3, Quantity::Unrecognized, |r| r.baro),
697        channel(4, Quantity::Number, |r| r.state),
698    ];
699    let notes = vec![
700        "`Acc(HI)` and `Baro(HI)` kept as written: the export holds the converter's counts and \
701         no calibration. The flight's `.odf` holds the same records with the board's, and reads \
702         in units"
703            .to_owned(),
704        "`Acc/Baro(LO)` and `State` kept as written: no document names their bits or codes"
705            .to_owned(),
706        "the first row is the pad's baselines, as whole counts, not a sample".to_owned(),
707    ];
708    Ok(FlightLog {
709        format: LogFormat::Arts2RawCsv,
710        logger: LOGGER.to_owned(),
711        serial_number: None,
712        firmware: None,
713        flight_number: None,
714        stated: Stated::default(),
715        time_s: Vec::new(),
716        altitude_m: Vec::new(),
717        vertical_speed_m_s: None,
718        temperature_k: None,
719        battery_v: None,
720        channels,
721        events: Vec::new(),
722        notes,
723    })
724}
725
726#[cfg(test)]
727mod tests {
728    use super::*;
729
730    /// The pressure's transfer function against a hand computation: count 780 is
731    /// (780 / 1,024 + 0.1518) / 0.010 59 = 86.2624 kPa.
732    #[test]
733    fn a_count_is_the_sensors_nominal_pressure() {
734        assert!(
735            (pressure_pa(780) - 86_262.39).abs() < 0.01,
736            "{}",
737            pressure_pa(780)
738        );
739    }
740
741    fn calibration(sums: [u16; 3], pad_eighths: u16) -> Calibration {
742        Calibration {
743            pad_baro: 780,
744            pad_acc_eighths: pad_eighths,
745            sums,
746        }
747    }
748
749    /// Ends 64 × 496 and 64 × 512 make a g 8 counts, 39.06 mV; the pad at 512 is on the high
750    /// end's side, so a count above it is upward: 520 is one g.
751    #[test]
752    fn the_calibration_gives_the_scale_and_the_sign() {
753        let axis = calibration([31_744, 32_256, 32_768], 4_096).axis().unwrap();
754        assert_eq!(axis.per_g, 8.0);
755        assert!((axis.acceleration(520) - STANDARD_GRAVITY).abs() < 1e-12);
756        // The board turned round: the pad on the low end's side, so counts fall upward.
757        let axis = calibration([31_744, 32_256, 32_768], 3_968).axis().unwrap();
758        assert!((axis.acceleration(488) - STANDARD_GRAVITY).abs() < 1e-12);
759    }
760
761    /// Each data-sheet band refuses: a g of 7 counts (34.2 mV), a side 40 counts off (195 mV),
762    /// a side outside its ends, and a pad nearer the side than either end.
763    #[test]
764    fn a_calibration_the_data_sheet_doesnt_bear_out_is_refused() {
765        let cases = [
766            ([31_808, 32_256, 32_704], 4_096, "outside the ADXL78"),
767            ([34_304, 34_816, 35_328], 4_416, "isn't zero g"),
768            ([31_744, 33_000, 32_768], 4_096, "isn't zero g"),
769            ([31_744, 32_256, 32_768], 4_064, "wasn't upright"),
770        ];
771        for (sums, pad, why) in cases {
772            let error = calibration(sums, pad).axis().unwrap_err();
773            assert!(error.contains(why), "{sums:?} {pad}: {error}");
774        }
775    }
776
777    /// At each band's edge: ends 947 apart make a g 7.398 counts, 36.12 mV, and read; 946,
778    /// 36.09 mV, are refused; 1,045, 39.86 mV, read; 1,046, 39.90 mV, are refused.
779    #[test]
780    fn a_calibration_at_the_bands_edges() {
781        let cases = [
782            (473, 474, true),
783            (473, 473, false),
784            (522, 523, true),
785            (523, 523, false),
786        ];
787        for (below, above, reads) in cases {
788            let sums = [32_256 - below, 32_256, 32_256 + above];
789            assert_eq!(calibration(sums, 4_100).axis().is_ok(), reads, "{sums:?}");
790        }
791    }
792
793    /// The flags byte must carry the barometer's low bits; a count over 1,023 or a byte over 255
794    /// is refused.
795    #[test]
796    fn a_records_words_are_checked() {
797        let good = Record {
798            acc: 512,
799            flags: 0b1100_0100,
800            baro: 777,
801            state: 0,
802        };
803        assert_eq!(good.fault(), None);
804        assert!(
805            Record { flags: 0, ..good }
806                .fault()
807                .unwrap()
808                .contains("low bits")
809        );
810        assert!(
811            Record { acc: 1_024, ..good }
812                .fault()
813                .unwrap()
814                .contains("10-bit")
815        );
816        assert!(
817            Record { state: 256, ..good }
818                .fault()
819                .unwrap()
820                .contains("byte")
821        );
822    }
823}