Skip to main content

Module altos_telem

Module altos_telem 

Source
Expand description

AltOS radio telemetry, as AltosUI saves the packets a TeleDongle hears to a .telem file: one TELEM line a packet, its bytes in hexadecimal.

An Altus Metrum flight computer sends a 32-byte packet over its radio several times a second; the ground station’s receiver, a TeleDongle, writes each packet it hears to its serial line as a text line, TELEM and then, in hexadecimal, a length byte, the packet, two bytes its radio adds, the signal strength (RSSI) and a link-quality byte whose top bit says the packet passed the radio’s CRC, and a checksum (AltOS Telemetry, Bdale Garbee and Keith Packard, v1.9.22.2, 2025, §4 “TeleDongle serial packet format”, p. 10). AltosUI saves every packet it receives (The Altus Metrum System, v1.9.22.2, 2025, §12.1, p. 27); the manual doesn’t show the file, and both sample files hold TELEM lines only, failed packets among them, one a line. The document is published under CC BY-SA 3.0; this reader restates its facts, not its tables.

Recognition. The first line that isn’t blank is TELEM, a space, and an even number of hexadecimal digits; no other layout HPR Sim reads opens so.

A line. Every line that isn’t blank must be such a packet, 36 bytes: the length byte 34 (the 32-byte packet and the two bytes the radio adds), the packet, the RSSI, the link-quality byte and the checksum, which is 0x5A plus every byte after the length byte up to, not including, the checksum, modulo 256. The document’s table puts its byte positions one place early, and its formula taken as written fails its own example; summing from the byte after the length through the link-quality byte passes the example and every line of both sample files. A line that isn’t a packet, has another length, or fails its checksum refuses the file (LogError::Syntax): the TeleDongle computed the checksum over its own line, so a failure is damage to the file. A packet whose link-quality byte says it failed the radio’s CRC is left out and counted in a note: its bytes are noise (13.6% and 4.1% of the two sample files’ packets).

A packet. The first five bytes are the board’s serial number (16 bits), its clock in ticks of 10 ms (16 bits) and the packet’s type, then 27 bytes the type lays out (§2.1, p. 2). The document doesn’t state the byte order; read little-endian, its own example’s position is 45.47° N, 122.74° W, and big-endian it isn’t a latitude, so little-endian it is. Every packet must name the same serial number, or the file is refused: two boards’ packets in one file would make two flights of one. The RSSI is a signed byte, in dBm as RSSI / 2 − 74 (§4); the document doesn’t say signed, but the manual’s receivers hear down to −111 dBm (§12.1, p. 27), which needs it, and read unsigned the sample files’ signals would be stronger than the transmitter. The link-quality byte’s other seven bits are kept as written.

The clock. The tick turns over every 655.36 s. Each packet’s tick is placed on the turn nearest the latest tick so far, so a GPS packet, which carries the earlier tick of its fix, is placed behind, not a turn ahead. The record’s clock is that tick in seconds, counted from the turn of the first packet heard, not from boost: how long the board had run before is unknown. A board switched off and on again restarts its tick, so a packet whose tick falls behind the last one of its own type starts a new power-on (within one, each type’s ticks never fall back). The record holds one power-on: the one whose sensor packets leave the pad (a state from boost to main), or, where none does, the last; packets of the others are left out and counted in a note, and a file in which two power-ons leave the pad is refused. The tick alone can’t tell everything apart: a silence of 327.68 s to 655.36 s, half a turn to a whole one, reads as a step back, and so as a power-on; a longer one reads as a turn less than it was; and a restart whose new tick lands ahead of the last, as when a board had run for more than half a turn before it, reads as a silence, the two power-ons one record.

What is read. The two sample files hold five packet types, and only those are decoded; the document lays out eleven more, for other boards, and a packet of one is counted in a note and not read: with no sample to check it, a misread unit wouldn’t show (the document’s own pressure unit is wrong, below). Each field is kept in the unit below where a second check bears it out, and as written otherwise:

PacketFieldChannelAs read
0x0A, TeleMetrum v2 and newer, sensorsstatestate, Quantity::Numberas written; each change an Event
prespressure, Quantity::PressurePa: the document says tenths of a pascal, but the files hold pascals (below)
temptemperature, Quantity::Temperaturehundredths of a °C, the document’s; K here
accelerationacceleration, Quantity::Accelerationsixteenths of a m/s², the document’s: the board’s own estimate along its axis
speedspeed, Quantity::Speedsixteenths of a m/s, the document’s: the board’s own estimate
heightheight, Quantity::AltitudeAboveGroundm above the pad, the document’s: the board’s own estimate
accel, v_batt, sense_d, sense_mthe same names, Quantity::Unrecognizedas written: the document gives them as the converters’ counts and no conversion
0x0B, TeleMetrum v2 and newer, calibrationground_presground_pressure, Quantity::PressurePa, as pres
ground_accel, accel_plus_g, accel_minus_gthe same names, Quantity::Unrecognizedas written: counts
0x05, GPS positionflagsnsat (its low four bits) and gps_flags (the byte), Quantity::Numberas written
latitude, longitudelatitude, longitudedegrees, from ten-millionths; a gap where the flags’ valid bit is clear
altitudegps_altitude, Quantity::GnssAltitudem; a gap where the valid bit is clear
year … second, pdop, hdop, vdop, modethe same names, Quantity::Numberas written: the year is two digits, the dilutions five times their value in the document
ground speed, climb rate, courseground_speed, climb_rate, course, Quantity::Unrecognizedas written: the document’s cm/s and “/2” are unchecked
0x06, GPS satellitesthe count, and 12 pairs of a satellite’s id and its signalsat_channels, svid_01 … svid_12, c_n_01 … c_n_12, Quantity::Numberas written
0x04, configurationflight number, settings, call sign, firmwarethe record’s FlightLog::flight_number and FlightLog::firmware; each configuration in a noteas written
every packetRSSI, link qualityrssi (dBm) and lqi, Quantity::NumberdBm by the document’s formula; the link quality as written

Pressure in pascals, not tenths. The document gives pres as “Pa * 10”. Read so, both sample files’ pads would be more than 15 km up; read as pascals they are at the height above sea level the export beside one of them states, and that export’s own pressures, in pascals, equal the telemetry’s at every tick where the export holds a fresh sample (the survey’s report, cargo xtask logs). So pres is read as pascals where the pressure on the pad, the median of the packets in the pad state or else the first packet’s, lies between 10 and 120 kPa read so, as every launch site’s does; otherwise the column is kept as written, Quantity::Unrecognized, with a note.

The flight’s states. The document names no state’s number. AltosUI’s exports write the number and the name side by side, and in every one of the sample exports 2 is pad, 3 boost, 4 fast, 5 coast, 6 drogue, 7 main and 8 landed; the events take those names, and another number is state N. The board’s estimates, acceleration, speed and height, are checked in the survey against each other and against the export.

The primary track. FlightLog::altitude_m is height on the sensor packets’ clock: the board’s own estimate of its height above the pad, which the telemetry sends in place of a barometric altitude and which may lean on its accelerometer as its speed does; the document doesn’t say how it is formed. FlightLog::temperature_k is the temperature; the vertical speed is absent, as the board’s speed leans on its accelerometer (as for AltOS’s CSV). Every other field is a channel on its own packets’ clock.

An invented line, a configuration packet: serial 1234 (d204), tick 256 (0001), type 04, then device type 11, flight 3, configuration 1.27, no apogee delay, main at 250 m, a log of 2,048 kB, call sign N0CALL and firmware 1.9.22; the RSSI byte f4, −12, is −80 dBm, and a8 sets the CRC bit, with a link quality of 40:

TELEM 22d2040001040b0300011b0000fa0000084e3043414c4c0000312e392e32320000f4a8c1

Functions§

read
Reads AltOS telemetry, as AltosUI saves it to a .telem file.
recognizes
Whether the text is AltOS telemetry: its first line that isn’t blank is TELEM, a space, and an even number of hexadecimal digits.