Skip to main content

hpr_flightdata/
rrc3_rff.rs

1//! Missile Works' RRC3 raw flight files, `.rff`: what its mDACS software saves when it downloads a
2//! flight from the altimeter, before any export.
3//!
4//! The RRC3 records its pressure at 20 Hz, and its temperature and battery voltage at 1 Hz (*RRC3+
5//! / RRC3 User Manual* v1.71, p. 23). mDACS keeps the download as a .NET `BinaryFormatter` stream,
6//! the layout Microsoft publishes as MS-NRBF (*[MS-NRBF]: .NET Remoting: Binary Format Data
7//! Structure*, revision 13.0, 2024-11-19): a serialized `mDACS.AnalysisSupport+FlightRecord` whose
8//! flight data is a `List<Int16>`, the altimeter's memory as it came off the board, one 16-bit word
9//! a slot. The stream has no columns and no times:
10//!
11//! - a word below `0x4000` is a pressure, in tenths of a millibar (10 Pa): `0x4000` is 1,638.4
12//!   mbar, above the 1,200 mbar at which the RRC3 itself reports a pressure sensor fault (p. 9),
13//!   so no reading reaches it;
14//! - a word at or above `0x4000` is an auxiliary word, written in pairs once a second,
15//!   presumably the temperature and battery voltage the manual names, in counts: Debrief found
16//!   mDACS's export's temperature and voltage tracking them, though not linearly. The file holds
17//!   no calibration for them, and they are kept as written ([`Quantity::Unrecognized`]), in the
18//!   order the file writes them. A few stand alone, not in a pair (in each sample file, three: one
19//!   near apogee, one later, and a last `0xFFFF`); the first two fall where the manual's low-voltage
20//!   samples taken as the drogue and the main fire would (p. 23), but that is a guess, and they
21//!   are kept as written in a channel of their own. Three or more auxiliary words in a row, which
22//!   no sample file holds, are read as pairs from the first, with an odd last one kept alone;
23//! - the readings start at the first word, among the first eight, that a pressure on a
24//!   launch pad can be, at least 500 mbar (5,570 m in the standard atmosphere, above
25//!   any launch site): the words before it are kept, as written, in a note;
26//! - a zero word ends the log: the list's slots after it are unwritten.
27//!
28//! **Times.** The stream has none, so the pressure's clock is the RRC3's 20 Hz, from the manual,
29//! the `n`th reading at `n / 20` s, and the auxiliary pairs' times are the time of the reading
30//! before them. Two checks stand behind it: the pairs, one a second, must count the same seconds as
31//! the readings do at 20 a second, within 10% and two pairs, or the file is refused; and wherever
32//! the project's sample logs hold mDACS's export of the same flight, its pressures match the raw
33//! readings one for one, and its `Time` column is this 20 Hz clock as mDACS keeps it: 0.05 s
34//! summed in single precision, so that it runs a hundredth of a second ahead late in a long log
35//! (`cargo xtask logs` counts the pairs and compares them).
36//!
37//! **The record.** One [`Quantity::Pressure`] channel, `Pressure`, and the three auxiliary
38//! channels. The primary track is empty, with a note: the file holds no altitude, and working one
39//! out of the pressure is a reading, not this reader's to make (milestone [M7.2], the readings,
40//! takes it), as mDACS's export's `Altitude` is mDACS's.
41//!
42//! **Refused**, naming the byte: a stream with no `List<Int16>` of the flight record's, or more
43//! than one candidate for it; a list whose slots run past the file's end; readings that don't start
44//! among the first eight words; a word other than a zero after the zero that ends the
45//! log; fewer than two seconds of readings; and a clock check that fails.
46//!
47//! **Where this comes from.** The layout, the `0x4000` threshold, the 500 mbar floor, the
48//! preamble's length and the clock check follow the reader in Debrief
49//! (`lib/parsers/missileworksRff.ts`, MIT, the project owner's own; see `THIRD-PARTY-NOTICES.md`),
50//! which was worked out from a raw file and mDACS's export of the same flight; the record types
51//! and their fields are MS-NRBF's (§2.4.3.3 `ArraySinglePrimitive`, §2.5.3 `MemberReference`,
52//! §2.6.1 `SerializationHeaderRecord`). Where this reader departs from Debrief's: it keeps the
53//! auxiliary words, paired and single, and the preamble where Debrief drops them; it refuses a
54//! stream with two candidate lists where Debrief takes the longer; and it refuses data after the
55//! zero that ends the log where Debrief stops reading.
56//!
57//! [M7.2]: https://hpr.fusionspace.co/decisions-and-roadmap.html#m7-2
58
59use crate::error::LogError;
60use crate::log::{Channel, FlightLog, LogFormat, Quantity, Stated};
61
62/// The format's name in errors.
63const FORMAT: &str = "RRC3 .rff";
64
65/// The class mDACS serializes, written in ASCII in the stream's class record.
66const CLASS_NAME: &[u8] = b"mDACS.AnalysisSupport+FlightRecord";
67
68/// How far into the file the class name may first appear, bytes: the stream's header and the class
69/// record come first.
70const CLASS_WITHIN: usize = 4096;
71
72/// MS-NRBF's `ArraySinglePrimitive` record type (§2.1.2.1, `RecordTypeEnumeration` 15).
73const ARRAY_SINGLE_PRIMITIVE: u8 = 0x0f;
74
75/// MS-NRBF's primitive type code for a 16-bit signed integer (§2.1.2.3, `PrimitiveTypeEnumeration`
76/// 7).
77const PRIMITIVE_INT16: u8 = 7;
78
79/// MS-NRBF's `MemberReference` record type (§2.1.2.1, `RecordTypeEnumeration` 9).
80const MEMBER_REFERENCE: u8 = 0x09;
81
82/// The most slots a list may have, 2²⁴: at 20 words a second, over nine days of flight.
83const MAX_SLOTS: i32 = 1 << 24;
84
85/// The first word that isn't a pressure: `0x4000` tenths of a millibar is 1,638.4 mbar. A
86/// threshold, not a bit test: a word with bit 15 set and bit 14 clear is no pressure either.
87pub(crate) const AUXILIARY: u16 = 0x4000;
88
89/// The least pressure a reading on a launch pad can be, tenths of a millibar: 500 mbar, 5,570 m in
90/// the standard atmosphere, above any launch site.
91pub(crate) const PAD_FLOOR: u16 = 5_000;
92
93/// How many words may precede the first reading.
94pub(crate) const MAX_PREAMBLE: usize = 8;
95
96/// The RRC3's pressure rate, Hz (RRC3 manual p. 23).
97const RATE_HZ: f64 = 20.0;
98
99/// Pascals in a tenth of a millibar.
100const COUNT_PA: f64 = 10.0;
101
102/// Whether the bytes are an MS-NRBF stream holding mDACS's flight record: a serialization header
103/// record (type 0) whose major and minor versions are 1 and 0, and the record's class name within
104/// the first [`CLASS_WITHIN`] bytes.
105pub(crate) fn recognizes(bytes: &[u8]) -> bool {
106    bytes.len() >= 17
107        && bytes[0] == 0
108        && i32_at(bytes, 9) == Some(1)
109        && i32_at(bytes, 13) == Some(0)
110        && contains(&bytes[..bytes.len().min(CLASS_WITHIN)], CLASS_NAME)
111}
112
113/// A little-endian 32-bit integer at `at`, if the file is long enough.
114fn i32_at(bytes: &[u8], at: usize) -> Option<i32> {
115    let word = bytes.get(at..at.checked_add(4)?)?;
116    Some(i32::from_le_bytes([word[0], word[1], word[2], word[3]]))
117}
118
119/// Whether `needle` occurs in `haystack`.
120fn contains(haystack: &[u8], needle: &[u8]) -> bool {
121    haystack
122        .windows(needle.len())
123        .any(|window| window == needle)
124}
125
126/// The flight data's list: where its first slot is, bytes, and how many slots are filled.
127#[derive(Debug, Clone, Copy, PartialEq)]
128struct List {
129    at: usize,
130    size: usize,
131}
132
133/// The flight record's `List<Int16>`: an `ArraySinglePrimitive` record of 16-bit integers whose
134/// object id the list's `MemberReference` names just before it, the reference followed by the
135/// list's size, which may be less than the array's length (the rest is spare capacity). Each
136/// candidate is checked in constant work, so the scan is linear in the file's length.
137fn find_list(bytes: &[u8]) -> Result<List, LogError> {
138    let mut found: Option<(usize, List)> = None;
139    for record in 13..bytes.len().saturating_sub(9) {
140        if bytes[record] != ARRAY_SINGLE_PRIMITIVE || bytes[record + 9] != PRIMITIVE_INT16 {
141            continue;
142        }
143        let (Some(id), Some(length)) = (i32_at(bytes, record + 1), i32_at(bytes, record + 5))
144        else {
145            continue;
146        };
147        if id <= 0 || length <= 0 || length > MAX_SLOTS {
148            continue;
149        }
150        // The list's `_items` reference, then its `_size`, end 13 bytes before the array: a
151        // reference record is a type byte and an id, and the size and `_version` follow it.
152        let reference = record - 13;
153        if bytes[reference] != MEMBER_REFERENCE || i32_at(bytes, reference + 1) != Some(id) {
154            continue;
155        }
156        let Some(size) = i32_at(bytes, reference + 5) else {
157            continue;
158        };
159        if size <= 0 || size > length {
160            continue;
161        }
162        let (Ok(length), Ok(size)) = (usize::try_from(length), usize::try_from(size)) else {
163            continue;
164        };
165        let at = record + 10;
166        if at + 2 * length > bytes.len() {
167            return Err(binary(
168                record,
169                format!(
170                    "the flight data's list of {length} slots runs past the file's end, at {} \
171                     bytes",
172                    bytes.len()
173                ),
174            ));
175        }
176        if let Some((first, _)) = found {
177            return Err(binary(
178                record,
179                format!(
180                    "the stream holds two lists that could be the flight data's, at bytes \
181                     {first} and {record}"
182                ),
183            ));
184        }
185        found = Some((record, List { at, size }));
186    }
187    found.map(|(_, list)| list).ok_or_else(|| {
188        binary(
189            0,
190            "the stream holds no list of 16-bit words that its flight record names: the file may \
191             be cut short"
192                .to_owned(),
193        )
194    })
195}
196
197/// Reads an RRC3 `.rff` file.
198pub fn read(bytes: &[u8]) -> Result<FlightLog, LogError> {
199    if !recognizes(bytes) {
200        return Err(LogError::NotThisFormat {
201            format: FORMAT,
202            message: "the file isn't an MS-NRBF stream holding mDACS's flight record".to_owned(),
203        });
204    }
205    let list = find_list(bytes)?;
206    // Every index asked for is below `list.size`, at most the list's length, whose slots
207    // `find_list` checked lie inside the file: the indexing can't fail.
208    let word = |index: usize| {
209        let at = list.at + 2 * index;
210        u16::from_le_bytes([bytes[at], bytes[at + 1]])
211    };
212    let byte_of = |index: usize| list.at + 2 * index;
213
214    let start = (0..list.size.min(MAX_PREAMBLE))
215        .find(|&index| (PAD_FLOOR..AUXILIARY).contains(&word(index)))
216        .ok_or_else(|| {
217            binary(
218                list.at,
219                format!(
220                    "none of the log's first {MAX_PREAMBLE} words is a pressure on a launch pad, \
221                     at least 500 mbar. The reader doesn't guess where the readings start"
222                ),
223            )
224        })?;
225
226    let mut pressure = Vec::new();
227    let mut auxiliary: [Vec<f64>; 2] = [Vec::new(), Vec::new()];
228    let mut auxiliary_time = Vec::new();
229    let (mut lone, mut lone_time) = (Vec::new(), Vec::new());
230    let mut end = list.size;
231    let mut index = start;
232    while index < list.size {
233        let value = word(index);
234        if value == 0 {
235            end = index;
236            break;
237        }
238        if value < AUXILIARY {
239            pressure.push(f64::from(value) * COUNT_PA);
240            index += 1;
241        } else if index + 1 < list.size && word(index + 1) >= AUXILIARY {
242            // The time of the reading before the pair; the readings' clock starts at zero.
243            auxiliary_time.push(pressure.len().saturating_sub(1) as f64 / RATE_HZ);
244            auxiliary[0].push(f64::from(value));
245            auxiliary[1].push(f64::from(word(index + 1)));
246            index += 2;
247        } else {
248            lone_time.push(pressure.len().saturating_sub(1) as f64 / RATE_HZ);
249            lone.push(f64::from(value));
250            index += 1;
251        }
252    }
253    if let Some(after) = (end..list.size).find(|&index| word(index) != 0) {
254        return Err(binary(
255            byte_of(after),
256            format!(
257                "the log ends with a zero word at slot {end}, but slot {after} after it holds \
258                 {:#06x}",
259                word(after)
260            ),
261        ));
262    }
263    if (pressure.len() as f64) < 2.0 * RATE_HZ {
264        return Err(LogError::NoData { format: FORMAT });
265    }
266    let by_readings = pressure.len() as f64 / RATE_HZ;
267    let by_pairs = auxiliary_time.len() as f64;
268    if (by_pairs - by_readings).abs() > 0.1 * by_readings + 2.0 {
269        return Err(binary(
270            list.at,
271            format!(
272                "the log's {} once-a-second pairs and its {} readings at 20 a second, {by_readings} \
273                 s, don't agree on how long it ran. The words aren't laid out as this reader takes \
274                 them",
275                auxiliary_time.len(),
276                pressure.len()
277            ),
278        ));
279    }
280
281    let mut notes = vec![
282        format!(
283            "the file holds no times. The pressure is on the RRC3's 20 Hz clock (RRC3 manual p. \
284             23), which its {} once-a-second pairs bear out to within {:.1} s",
285            auxiliary_time.len(),
286            (by_pairs - by_readings).abs()
287        ),
288        "the record's primary track is empty: the file holds pressures, not an altitude".to_owned(),
289        "the once-a-second pairs are kept as written. They are presumably the temperature and \
290         battery voltage the RRC3 records at 1 Hz (RRC3 manual p. 23). The file holds no \
291         calibration for them"
292            .to_owned(),
293    ];
294    if start > 0 {
295        let preamble: Vec<String> = (0..start).map(|i| format!("{:#06x}", word(i))).collect();
296        notes.push(format!(
297            "the log opens with {start} words before its first reading, kept here as written: {}",
298            preamble.join(", ")
299        ));
300    }
301    if !lone.is_empty() {
302        notes.push(format!(
303            "{} auxiliary words stand alone, not in a pair; they are kept as written, as `single \
304             auxiliary word`",
305            lone.len()
306        ));
307    }
308    if end < list.size {
309        notes.push(format!(
310            "the log ends with a zero word at slot {end} of the list's {}",
311            list.size
312        ));
313    }
314
315    let time_s: Vec<f64> = (0..pressure.len()).map(|n| n as f64 / RATE_HZ).collect();
316    let [first, second] = auxiliary;
317    Ok(FlightLog {
318        format: LogFormat::Rrc3Rff,
319        logger: "Missile Works RRC3".to_owned(),
320        serial_number: None,
321        firmware: None,
322        flight_number: None,
323        stated: Stated::default(),
324        time_s: Vec::new(),
325        altitude_m: Vec::new(),
326        vertical_speed_m_s: None,
327        temperature_k: None,
328        battery_v: None,
329        channels: vec![
330            Channel {
331                column: "Pressure".to_owned(),
332                quantity: Quantity::Pressure,
333                time_s,
334                values: pressure,
335            },
336            Channel {
337                column: "auxiliary word 1".to_owned(),
338                quantity: Quantity::Unrecognized,
339                time_s: auxiliary_time.clone(),
340                values: first,
341            },
342            Channel {
343                column: "auxiliary word 2".to_owned(),
344                quantity: Quantity::Unrecognized,
345                time_s: auxiliary_time,
346                values: second,
347            },
348            Channel {
349                column: "single auxiliary word".to_owned(),
350                quantity: Quantity::Unrecognized,
351                time_s: lone_time,
352                values: lone,
353            },
354        ],
355        events: Vec::new(),
356        notes,
357    })
358}
359
360/// A refusal at a byte of the file.
361fn binary(offset: usize, message: String) -> LogError {
362    LogError::Binary {
363        format: FORMAT,
364        offset,
365        message,
366    }
367}