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}