Expand description
AltOS raw flight downloads, as AltosUI saves a flight computer’s memory to a .eeprom file:
the board’s own log, record by record, in a JSON form or an older text form.
An Altus Metrum flight computer logs its sensors 100 times a second in the climb and 10 times
a second in the descent, in records of 8 bytes (TeleMetrum v1), 16 (TeleMetrum v2 and newer,
EasyMini) or 32 (TeleMega, EasyMega) (The Altus Metrum System, Bdale Garbee and Keith
Packard, v1.9.22.2, 2025, Appendix F, Table 11, p. 77). AltosUI saves a flight it downloads as
a .eeprom file. Altus Metrum publishes no layout for the records, so this reader’s layout was
worked out from the 14 sample files and the AltosUI exports (CSV) of the same flights beside 9
of them, and is held to those exports in the survey (cargo xtask logs); no AltOS or AltosUI
source code was read. The manual and AltOS Telemetry (v1.9.22.2) are published under CC
BY-SA 3.0; this reader restates facts from them, not their text.
Recognition. The JSON form opens with a JSON object that names log_format and product;
the text form holds, within its first 1,000 lines, a Config version: line and a
manufacturer altusmetrum.org line, as the board prints its configuration. No other layout
HPR Sim reads does either.
The two forms. The JSON form is the board’s configuration as a JSON object, then the memory’s bytes, two hexadecimal digits each, whitespace between them. The text form is a serial console’s transcript: the configuration as the board prints it, then one record a line, a type letter, the tick in hexadecimal and the record’s other bytes, all but its checksum. In both, a record is a type byte, a checksum byte, a 16-bit tick (low byte first) and the type’s fields.
- Record size follows the log format the configuration states (
log_format,log-format): 8 bytes for format 1; 16 for 6, 7 and 14; 32 for 15, 16 and 22. Any other number refuses the file, by number: read at a wrong size, misaligned bytes would make a plausible flight. A file that states no log format, as firmware before 1.0 didn’t, is format 1 if its product is a TeleMetrum v1, as AltosUI does (“Those ancient versions didn’t report the log format, so just use the product name instead”, the manual’s release notes for version 1.4, §H.43.2, p. 128); any other product refuses it. Format 1’s text prints its four field bytes as two 16-bit words. - Checksum. In the JSON form, every record’s bytes sum, with 0x5A, to 0 modulo 256, the seed
of the line checksum of the TeleDongle, the radio receiver AltosUI listens through (AltOS
Telemetry §4, p. 10): every record of the seven JSON sample files passes (the survey’s
report counts them). One that fails refuses the file (
LogError::Binary). The text form prints no checksum. - Erased memory. A record of all 0xFF bytes is erased flash, after the flight’s last record, and is skipped and counted; a data record after one refuses the file, as the memory’s order is then unknown. Memory that ends partway through a record is refused, erased or not.
- A malformed line in the text form’s records refuses the file, but the last line of a file that ends without a line break, as a download cut short does, is left out with a note: it may be cut mid-value however well it reads.
- The configuration may be printed more than once in a transcript; the first copy is read,
and a later one that differs in the log format, serial number, product, barometer constants
or accelerometer calibration refuses the file.
2147483647in the JSON means not set.
The clock. The tick counts 100 a second (AltOS Companion Port, v1.9.22.2, Table 1;
Appendix F’s 100 samples a second) and turns over every 655.36 s. Each record’s tick goes on
the turn nearest the latest tick so far. The file’s order isn’t time order: the samples from
before boost, kept in a ring buffer, are written after the flight record, a state record ahead
of sensor records with earlier ticks, and a GPS record carries its fix’s earlier tick; so the
records are put in tick order, the file’s order kept among equal ticks. A record more than
10 s from the latest tick, a silence no logging rate leaves, ends the flight: it and every
record after it are left out, counted in a note (one sample file ends with another session’s
records, more than 10 s later). Records repeated exactly, the same bytes at the same tick, as
old firmware wrote some, are dropped and counted. Time zero is the flight record’s tick, the
board’s detection of boost, as in AltosUI’s exports: the samples from the pad have negative
times. A file needs exactly one flight record (F), or it is refused.
What is read. Each field is in SI where a cited conversion and a second check bear the
unit out, and kept as written (Quantity::Unrecognized for counts, Quantity::Number for
codes and flags) otherwise:
| Board (format) | Field | Channel | As read |
|---|---|---|---|
| all with an MS5607, the barometer chip (6, 7, 14, 15, 16, 22) | the barometer’s D1 and D2 | pressure, temperature | Pa and K, by the data sheet’s compensation (below); d1, d2 as written without its constants |
| TeleMetrum v1 (1) | pressure count | pressure | Pa, by the MP3H6115A’s transfer function (below) |
| all but EasyMini | the high-g accelerometer’s count | acceleration | m/s² along the flight path, from the file’s own calibration (below); accel as written without one |
| TeleMega v4.0 and v6.0, EasyMega v2.0 (15, 16, 22) | pyro battery, igniters A–D, apogee and main senses (the voltages across the pyro channels that show continuity) | pyro, igniter_a … igniter_d, drogue_voltage, main_voltage | V, as AltOS Telemetry converts a 15 V Mega’s: count / 4095 × 3.3 V × 127 / 27 (p. 3); as written on any other Mega |
| every board | battery and other senses | v_batt, sense_a, sense_m | as written: the factors that fit the exports have no source |
| TeleMetrum v1 (1) | the die temperature of the CC1111, the radio microcontroller whose converter reads the board’s sensors | temp | as written: no document gives the conversion AltosUI uses, and the CC1111 data sheet’s constants don’t reproduce its export |
| EasyMega v2, TeleMega v6 (16, 22) | the nine words of the IMU, the inertial unit’s accelerometer, gyroscope and magnetometer | imu_accel_0 … imu_mag_2 | as written: their scales fit the exports but have no source |
| every board | state | state | as written; each change an Event |
| boards with GPS | latitude, longitude | latitude, longitude | degrees, from ten-millionths, as AltOS Telemetry’s GPS packet (Table 15, pp. 6–7); a gap without a valid fix |
| altitude | gps_altitude | m, as the GPS packet’s; with the configuration’s altitude-32, its high 16 bits too | |
| flags, time, date, dilutions, course, speed, climb, satellites | gps_flags, nsat, hour …, year …, pdop …, course, ground_speed, climb_rate, svid, c_n | as written: the date is two digits and needn’t be the flight’s |
Pressure and temperature, MS5607. The data sheet’s first-order compensation and, below
20 °C, its second order (TE Connectivity, MS5607-02BA03, 03/2024, Figure 2, p. 8, and Figure
3, p. 9), in integers, each division by 2ⁿ a floor (an arithmetic shift): truncating instead
gives different pressures below 20 °C, and a unit test pins the floor. Second checks: the pad’s
pressure (the median of the samples before boost, or the first sample’s) must lie from 10 to
120 kPa and within 1% of the flight record’s ground pressure, the pad’s temperature within the
sensor’s operating range, −40 to 85 °C (p. 8), or the file is refused: any failing means
misread bytes. On a board with an accelerometer the climb check below holds the pressure and
the acceleration to each other too; failing it keeps the acceleration as counts. A board
without the constants, or whose JSON marks an MS5611, keeps d1 and d2 as written.
Pressure, TeleMetrum v1. The MP3H6115A’s output is Vout = Vs (0.009 P − 0.095), P in kPa
(Freescale, MP3H6115A, rev. 5.1, 2012, “Transfer Function”, p. 5), read by the CC1111’s
12-bit converter, whose single-ended result, 0 to 2,047, reaches 2,047 at its reference and is
held in the top bits of its two result registers (TI, CC1110Fx/CC1111Fx, SWRS033H,
§12.10.2.6, p. 143, and ADCH/ADCL, p. 144): full scale is 2,047 × 16 = 32,752. So
P = (count / 32,752 + 0.095) / 0.009 kPa, the converter’s reference being the sensor’s own
supply (the board’s design, which no document states). Second checks: the pad’s pressure must
lie from 10 to 120 kPa, or the file is refused, and the climb check below must pass, or the
counts are kept as written, pres, the band alone rejecting almost no count; the export of the
same flight agrees within half its 0.01 Pa print step (the survey’s report).
Acceleration. AltosUI calibrates the accelerometer with the board’s antenna end up, then down
(the manual, §12.6.20, p. 42), giving its counts at +1 g and −1 g (accel_cal_plus,
accel_cal_minus, or the text form’s Accel cal +1g: P -1g: M). The record’s
acceleration is (ground − count) / ((minus − plus) / 2) × 9.806 65 m/s², ground the
flight record’s reading on the pad, 9.806 65 m/s² standard gravity (CGPM, 1901): 0 on the pad,
positive forward along the flight path, gravity out. A board mounted antenna down logs flipped
counts and keeps a flipped calibration (the JSON’s _cooked values) whose span is the same, so
the result doesn’t depend on which pair is read, as long as both counts come from one pair;
the configuration’s pad_orientation is a stated figure. Without a calibration, with one
outside a 16-bit count’s range, with a span that isn’t positive, without a ground reading or
without a pressure in pascals to check it against, or failing the climb check below, the counts
are kept as written, accel.
The climb check. On a board with an accelerometer, the climb over the first second after boost by the pressure, its pressure altitude in the U.S. Standard Atmosphere, 1976 (ISO 2533:1975’s below 32 km), must agree with the climb by the acceleration integrated twice from rest on the pad: their ratio from 0.6 to 5/3. Outside it, or where the samples don’t cover that second or leave a gap in it of more than 0.1 s, neither unit is borne out: the acceleration’s counts are kept as written, and a TeleMetrum v1’s pressure’s, which has no other check, too (an MS5607 board’s pressure keeps its flight record’s check). On 11 of the 12 sample files with an accelerometer the ratio runs from 0.859 to 1.400; the twelfth reads about 2, so its counts are kept (the survey’s report prints each). The band catches swapped or misplaced fields, a wrong sign, and a calibration off by 2 or more on a flight whose ratio is near 1. Without a calibration an MS5607 board’s pressure’s second checks are the pad’s alone, and a TeleMetrum v1’s pressure is kept as written.
Not read. The TeleMega v4’s IMU (format 15): its one sample file’s IMU never ran, so its layout is unconfirmed. Any Mega whose flight record’s IMU fields are all zero: its records’ IMU bytes are then stale buffer bytes, not readings. Bytes a record type leaves over from the record before (the tails of state, sense, GPS and satellite records) are never read. A record type the board’s layout doesn’t hold is counted in a note.
The flight’s states. AltosUI’s exports write each state’s number beside its name; the
events take the exports’ names, 2 pad, 3 boost, 4 fast, 5 coast, 6 drogue, 7 main,
8 landed, and another number state N.
What the file says about itself. FlightLog::serial_number and
FlightLog::firmware are the configuration’s; FlightLog::flight_number is the flight
record’s, not the JSON’s stored_flight or flights, which needn’t name the flight the file
holds. Stated::figures holds the flight record’s ground pressure (Pa) and ground
accelerometer reading, the calibration, the pad orientation, the IMU’s pad readings and the
configuration’s main deployment height and apogee delay, as written, in SI where the text form
names the unit.
The primary track. The file holds no altitude, so FlightLog::time_s and
FlightLog::altitude_m are empty, as for the Raven’s raw .FIPa; every field is a channel
on its records’ clock, in tick order.
An invented record, a TeleMetrum v2’s (format 7) flight record in the JSON form: type F,
checksum, tick 0x0164 (356), flight 3, ground reading 25 counts, ground pressure 98,000 Pa, and
four unused bytes:
46 90 64 01 03 00 19 00 d0 7e 01 00 00 00 00 00The same record in the text form, its checksum not printed and its tick printed as one
hexadecimal number, 164, while the other bytes keep their order:
F 164 03 00 19 00 d0 7e 01 00 00 00 00 00Constants§
- ALTITUDE_
STEP_ M - The format’s resolution (
LogFormat::altitude_resolution_m): the file writes no altitude, and its coarsest pressure is a TeleMetrum v1’s, whose counts step by 4 in the sample files (the survey’s report prints each file’s smallest pressure step): 4 / 32,752 / 0.009 kPa, 13.6 Pa, or 1.13 m near sea level (Δh = Δp / (ρ₀ g₀)). An MS5607 board’s steps by a whole pascal. - CLIMB_
RATIO - The ratios of the climb by the pressure to the climb by the acceleration that the climb check accepts: 0.6 to 5/3, symmetric about 1 in log terms. On 11 of the 12 sample files with an accelerometer the ratio lies from 0.859 to 1.400 (the survey’s report prints each file’s): the barometer reads the pressure at its ports, which the airflow past them can lower in the climb, and a high-g accelerometer counts few steps a g. The band leaves those at least a fifth to spare on either side, and the twelfth, at about 2, outside: its two sensors disagree by a factor no port or step explains, so neither unit is taken on trust there.
Functions§
- read
- Reads an AltOS
.eepromfile. - recognizes
- Whether the text is an AltOS
.eepromfile, in either form.