2 Keith Packard <keithp@keithp.com>; Bdale Garbee <bdale@gag.com>
5 :copyright: Bdale Garbee and Keith Packard 2021
12 :pdf-style: altusmetrum
15 include::header.adoc[]
17 == Packet Format Design
19 AltOS telemetry data is split into multiple different packets,
20 all the same size, but each includs an identifier so that the
21 ground station can distinguish among different types. A single
22 flight board will transmit multiple packet types, each type on
23 a different schedule. The ground software need look for only a
24 single packet size, and then decode the information within the
25 packet and merge data from multiple packets to construct the
26 full flight computer state.
28 Each AltOS packet is 32 bytes long. This size was chosen based
29 on the known telemetry data requirements. The power of two
30 size allows them to be stored easily in flash memory without
31 having them split across blocks or leaving gaps at the end.
33 All packet types start with a five byte header which encodes
34 the device serial number, device clock value and the packet
35 type. The remaining 27 bytes encode type-specific data.
39 This section first defines the packet header common to all packets
40 and then the per-packet data layout.
44 .Telemetry Packet Header
45 [options="border",cols="2,3,3,9"]
47 |Offset |Data Type |Name |Description
48 |0 |uint16_t |serial |Device serial Number
49 |2 |uint16_t |tick |Device time in 100ths of a second
50 |4 |uint8_t |type |Packet type
54 Each packet starts with these five bytes which serve to identify
55 which device has transmitted the packet, when it was transmitted
56 and what the rest of the packet contains.
58 === TeleMetrum v1.x, TeleMini v1.0 and TeleNano Sensor Data
61 [options="border",cols="1,3"]
64 |0x01 |TeleMetrum v1.x Sensor Data
65 |0x02 |TeleMini v1.0 Sensor Data
66 |0x03 |TeleNano Sensor Data
69 TeleMetrum v1.x, TeleMini v1.0 and TeleNano share this same
70 packet format for sensor data. Each uses a distinct
71 packet type so that the receiver knows which data
72 values are valid and which are undefined.
74 Sensor Data packets are transmitted once per second on
75 the ground, 10 times per second during ascent and once
76 per second during descent and landing
78 .Sensor Packet Contents
79 [options="border",cols="2,3,3,9"]
81 |Offset |Data Type |Name |Description
82 |5 |uint8_t |state |Flight state
83 |6 |int16_t |accel |accelerometer (TM only)
84 |8 |int16_t |pres |pressure sensor
85 |10 |int16_t |temp |temperature sensor
86 |12 |int16_t |v_batt |battery voltage
87 |14 |int16_t |sense_d |drogue continuity sense (TM/Tm)
88 |16 |int16_t |sense_m |main continuity sense (TM/Tm)
89 |18 |int16_t |acceleration |m/s² * 16
90 |20 |int16_t |speed |m/s * 16
91 |22 |int16_t |height |m
92 |24 |int16_t |ground_pres |Average barometer reading on ground
93 |26 |int16_t |ground_accel |TM
94 |28 |int16_t |accel_plus_g |TM
95 |30 |int16_t |accel_minus_g |TM
99 === TeleMega Sensor Data
101 .TeleMega Packet Type
102 [options="border",cols="1,3"]
105 |0x08 |TeleMega IMU Sensor Data
106 |0x09 |TeleMega Kalman and Voltage Data
109 TeleMega has a lot of sensors, and so it splits the sensor
110 data into two packets. The raw IMU data are sent more often;
111 the voltage values don't change very fast, and the Kalman
112 values can be reconstructed from the IMU data.
114 IMU Sensor Data packets are transmitted once per second on the
115 ground, 10 times per second during ascent and once per second
116 during descent and landing
118 Kalman and Voltage Data packets are transmitted once per second on the
119 ground, 5 times per second during ascent and once per second
120 during descent and landing
122 The high-g accelerometer is reported separately from the data
123 for the 9-axis IMU (accel/gyro/mag). The 9-axis IMU is mounted
124 so that the X axis is "across" the board (along the short
125 axis0, the Y axis is "along" the board (along the long axis,
126 with the high-g accelerometer) and the Z axis is "through" the
127 board (perpendicular to the board). Rotation measurements are
128 around the respective axis, so Y rotation measures the spin
129 rate of the rocket while X and Z rotation measure the tilt
132 The overall tilt angle of the rocket is computed by first
133 measuring the orientation of the rocket on the pad using the 3
134 axis accelerometer, and then integrating the overall tilt rate
135 from the 3 axis gyroscope to compute the total orientation
136 change of the airframe since liftoff.
138 .TeleMega IMU Sensor Packet Contents
139 [options="border",cols="2,3,3,9"]
141 |Offset |Data Type |Name |Description
142 |5 |uint8_t |orient |Angle from vertical in degrees
143 |6 |int16_t |accel |High G accelerometer
144 |8 |int32_t |pres |pressure (Pa * 10)
145 |12 |int16_t |temp |temperature (°C * 100)
146 |14 |int16_t |accel_x |X axis acceleration (across)
147 |16 |int16_t |accel_y |Y axis acceleration (along)
148 |18 |int16_t |accel_z |Z axis acceleration (through)
149 |20 |int16_t |gyro_x |X axis rotation (across)
150 |22 |int16_t |gyro_y |Y axis rotation (along)
151 |24 |int16_t |gyro_z |Z axis rotation (through)
152 |26 |int16_t |mag_x |X field strength (across)
153 |28 |int16_t |mag_y |Y field strength (along)
154 |30 |int16_t |mag_z |Z field strength (through)
158 .TeleMega Kalman and Voltage Data Packet Contents
159 [options="border",cols="2,3,3,9"]
161 |Offset |Data Type |Name |Description
162 |5 |uint8_t |state |Flight state
163 |6 |int16_t |v_batt |battery voltage
164 |8 |int16_t |v_pyro |pyro battery voltage
165 |10 |int8_t[6] |sense |pyro continuity sense
166 |16 |int32_t |ground_pres |Average barometer reading on ground
167 |20 |int16_t |ground_accel |Average accelerometer reading on ground
168 |22 |int16_t |accel_plus_g |Accel calibration at +1g
169 |24 |int16_t |accel_minus_g |Accel calibration at -1g
170 |26 |int16_t |acceleration |m/s² * 16
171 |28 |int16_t |speed |m/s * 16
172 |30 |int16_t |height |m
176 === TeleMetrum v2 and newer Sensor Data
178 .TeleMetrum v2 Packet Type
179 [options="border",cols="1,3"]
182 |0x0A |TeleMetrum v2 Sensor Data
183 |0x0B |TeleMetrum v2 Calibration Data
186 TeleMetrum v2 and newer have higher resolution barometric data than
187 TeleMetrum v1, and so the constant calibration data is
188 split out into a separate packet.
190 TeleMetrum v2 and newer Sensor Data packets are transmitted once per second on the
191 ground, 10 times per second during ascent and once per second
192 during descent and landing
194 TeleMetrum v2 and newer Calibration Data packets are always transmitted once per second.
196 .TeleMetrum v2 and newer Sensor Packet Contents
197 [options="border",cols="2,3,3,9"]
199 |Offset |Data Type |Name |Description
200 |5 |uint8_t |state |Flight state
201 |6 |int16_t |accel |accelerometer
202 |8 |int32_t |pres |pressure sensor (Pa * 10)
203 |12 |int16_t |temp |temperature sensor (°C * 100)
204 |14 |int16_t |acceleration |m/s² * 16
205 |16 |int16_t |speed |m/s * 16
206 |18 |int16_t |height |m
207 |20 |int16_t |v_batt |battery voltage
208 |22 |int16_t |sense_d |drogue continuity sense
209 |24 |int16_t |sense_m |main continuity sense
210 |26 |pad[6] |pad bytes |
214 .TeleMetrum v2 and newer Calibration Data Packet Contents
215 [options="border",cols="2,3,3,9"]
217 |Offset |Data Type |Name |Description
218 |5 |pad[3] |pad bytes |
219 |8 |int32_t |ground_pres |Average barometer reading on ground
220 |12 |int16_t |ground_accel |Average accelerometer reading on ground
221 |14 |int16_t |accel_plus_g |Accel calibration at +1g
222 |16 |int16_t |accel_minus_g |Accel calibration at -1g
223 |18 |pad[14] |pad bytes |
227 === TeleMini v3.0 Sensor Data
230 [options="border",cols="1,3"]
233 |0x11 |TeleMini v3.0 Sensor Data
236 TeleMini v3.0 uses this
237 packet format for sensor data.
239 Sensor Data packets are transmitted once per second on
240 the ground, 10 times per second during ascent and once
241 per second during descent and landing
243 .Sensor Packet Contents
244 [options="border",cols="2,3,3,9"]
246 |Offset |Data Type |Name |Description
247 |5 |uint8_t |state |Flight state
248 |6 |int16_t |v_batt |battery voltage
249 |8 |int16_t |sense_a |apogee continuity sense
250 |10 |int16_t |sense_m |main continuity sense
251 |12 |int32_t |pres |pressure sensor (Pa * 10)
252 |16 |int16_t |temp |temperature sensor (°C * 100)
253 |18 |int16_t |acceleration |m/s² * 16
254 |20 |int16_t |speed |m/s * 16
255 |22 |int16_t |height |m
256 |24 |int16_t |ground_pres |Average barometer reading on ground
257 |28 |pad[4] |pad bytes |
262 === Configuration Data
264 .Configuration Packet Type
265 [options="border",cols="1,3"]
268 |0x04 |Configuration Data
271 This provides a description of the software installed on the
272 flight computer as well as any user-specified configuration data.
274 Configuration data packets are transmitted once per second
275 during all phases of the flight
277 .Configuration Packet Contents
278 [options="border",cols="2,3,3,9"]
280 |Offset |Data Type |Name |Description
281 |5 |uint8_t |type |Device type
282 |6 |uint16_t |flight |Flight number
283 |8 |uint8_t |config_major |Config major version
284 |9 |uint8_t |config_minor |Config minor version
285 |10 |uint16_t |apogee_delay |Apogee deploy delay in seconds
286 |12 |uint16_t |main_deploy |Main deploy alt in meters
287 |14 |uint16_t |flight_log_max |Maximum flight log size (kB)
288 |16 |char |callsign[8] |Radio operator identifier
289 |24 |char |version[8] |Software version identifier
296 [options="border",cols="1,3"]
302 This packet provides all of the information available from the
303 GPS receiver—position, time, speed and precision
306 GPS Location packets are transmitted once per second during
307 all phases of the flight
309 .GPS Location Packet Contents
310 [options="border",cols="2,3,3,9"]
312 |Offset |Data Type |Name |Description
313 |5 |uint8_t |flags |See GPS Flags table below
314 |6 |int16_t |altitude |m
315 |8 |int32_t |latitude |degrees * 107
316 |12 |int32_t |longitude |degrees * 107
318 |17 |uint8_t |month |
321 |20 |uint8_t |minute |
322 |21 |uint8_t |second |
323 |22 |uint8_t |pdop |* 5
324 |23 |uint8_t |hdop |* 5
325 |24 |uint8_t |vdop |* 5
326 |25 |uint8_t |mode |See GPS Mode table below
327 |26 |uint16_t |ground_speed |cm/s
328 |28 |int16_t |climb_rate |cm/s
329 |30 |uint8_t |course |/ 2
330 |31 |uint8_t |unused[1] |
334 Packed into a one byte field are status flags and the
335 count of satellites used to compute the position
336 fix. Note that this number may be lower than the
337 number of satellites being tracked; the receiver will
338 not use information from satellites with weak signals
339 or which are close enough to the horizon to have
340 significantly degraded position accuracy.
343 [options="border",cols="1,2,7"]
345 |Bits |Name |Description
346 |0-3 |nsats |Number of satellites in solution
347 |4 |valid |GPS solution is valid
348 |5 |running |GPS receiver is operational
349 |6 |date_valid |Reported date is valid
350 |7 |course_valid |ground speed, course and climb rates are valid
353 Here are all of the valid GPS operational modes. Altus
354 Metrum products will only ever report 'N' (not valid),
355 'A' (Autonomous) modes or 'E' (Estimated). The
356 remaining modes are either testing modes or require
360 [options="border",cols="1,3,7"]
362 |Mode |Name |Description
363 |N |Not Valid |All data are invalid
364 |A |Autonomous mode |
365 Data are derived from satellite data
367 |D |Differential Mode |
368 Data are augmented with differential data from a
369 known ground station. The SkyTraq unit in TeleMetrum
370 does not support this mode
373 Data are estimated using dead reckoning from the
377 Data were entered manually
380 GPS receiver testing mode
384 === GPS Satellite Data
386 .GPS Satellite Data Packet Type
387 [options="border",cols="1,3"]
390 |0x06 |GPS Satellite Data
393 This packet provides space vehicle identifiers and
394 signal quality information in the form of a C/N1
395 number for up to 12 satellites. The order of the svids
398 GPS Satellite data are transmitted once per second
399 during all phases of the flight.
401 .GPS Satellite Data Contents
402 [options="border",cols="2,3,3,9"]
404 |Offset |Data Type |Name |Description
405 |5 |uint8_t |channels |Number of reported satellite information
406 |6 |sat_info_t |sats[12] |See Per-Satellite data table below
407 |30 |uint8_t |unused[2] |
411 .GPS Per-Satellite data (sat_info_t)
412 [options="border",cols="2,3,3,9"]
414 |Offset |Data Type |Name |Description
415 |0 |uint8_t |svid |Space Vehicle Identifier
416 |1 |uint8_t |c_n_1 |C/N1 signal quality indicator
422 .Companion Data Packet Type
423 [options="border",cols="1,3"]
426 |0x07 |Companion Data
429 When a companion board is attached to TeleMega or
430 TeleMetrum, it can provide telemetry data to be
431 included in the downlink. The companion board can
432 provide up to 12 16-bit data values.
434 The companion board itself specifies the transmission
435 rate. On the ground and during descent, that rate is
436 limited to one packet per second. During ascent, that
437 rate is limited to 10 packets per second.
439 .Companion Data Contents
440 [options="border",cols="2,3,3,9"]
442 |Offset |Data Type |Name |Description
443 |5 |uint8_t |board_id |Type of companion board attached
444 |6 |uint8_t |update_period |How often telemetry is sent, in 1/100ths of a second
445 |7 |uint8_t |channels |Number of data channels supplied
446 |8 |uint16_t[12] |companion_data |Up to 12 channels of 16-bit companion data
452 Altus Metrum devices use Texas Instruments sub-GHz digital
453 radio products. Ground stations use parts with HW FEC while
454 some flight computers perform FEC in software. TeleGPS is
457 .Altus Metrum Radio Parts
458 [options="border",cols="1,4,4"]
460 |Part Number |Description |Used in
463 |10mW transceiver with integrated SoC
464 |TeleDongle v0.2, TeleBT v1.0, TeleMetrum v1.x, TeleMini v1
467 |35mW transceiver with SW FEC
468 |TeleMetrum v2, TeleMega v1
471 |35mW transceiver with HW FEC
472 |TeleMetrum v3, TeleMega v2, TeleDongle v3.0, TeleMini v3, TeleBT v3.0, TeleGPS v2
475 |14mW transmitter with SW FEC
480 === Modulation Scheme
482 Texas Instruments provides a tool for computing
483 modulation parameters given a desired modulation
484 format and basic bit rate.
486 While we might like to use something with better
487 low-signal performance like BPSK, the radios we use
488 don't support that, but do support Gaussian frequency
489 shift keying (GFSK). Regular frequency shift keying
490 (FSK) encodes the signal by switching the carrier
491 between two frequencies. The Gaussian version is
492 essentially the same, but the shift between
493 frequencies gently follows a gaussian curve, rather
494 than switching immediately. This tames the bandwidth
495 of the signal without affecting the ability to
498 For AltOS, there are three available bit rates,
499 38.4kBaud, 9.6kBaud and 2.4kBaud resulting in the
500 following signal parmeters:
503 [options="border",cols="1,1,1"]
505 |Rate |Deviation |Receiver Bandwidth
506 |38.4kBaud |20.5kHz |100kHz
507 |9.6kBaud |5.125kHz |25kHz
508 |2.4kBaud |1.5kHz |5kHz
513 The cc1111 and cc1200 provide forward error correction
514 in hardware; on the cc1120 and cc115l that's done in
515 software. AltOS uses this to improve reception of weak
516 signals. As it's a rate 1/2 encoding, each bit of data
517 takes two bits when transmitted, so the effective data
518 rate is half of the raw transmitted bit rate.
521 [options="border",cols="1,1,1"]
523 |Parameter |Value |Description
526 |Convolutional coding
527 |1/2 rate, constraint length m=4
531 |Reduce effect of noise burst
535 |Rotate right with bit 8 = bit 0 xor bit 5, initial value 111111111
539 == TeleDongle serial packet format
541 TeleDongle does not do any interpretation of the packet data,
542 instead it is configured to receive packets of a specified
543 length (32 bytes in this case). For each received packet,
544 TeleDongle produces a single line of text. This line starts with
545 the string "TELEM " and is followed by a list of hexadecimal
549 TELEM 224f01080b05765e00701f1a1bbeb8d7b60b070605140c000600000000000000003fa988
552 The hexadecimal encoded string of bytes contains a length byte,
553 the packet data, two bytes added by the cc1111 radio receiver
554 hardware and finally a checksum so that the host software can
555 validate that the line was transmitted without any errors.
557 .TeleDongle serial Packet Format
559 [options="border",cols="2,1,1,5"]
561 |Offset |Name |Example |Description
566 |Total length of data bytes in the line. Note that
567 this includes the added RSSI and status bytes
572 |Bytes of actual packet data
577 |Received signal strength. dBm = rssi / 2 - 74
582 |Link Quality Indicator and CRC status. Bit 7
583 is set when the CRC is correct
588 |(0x5a + sum(bytes 1 ·· length-1)) % 256
592 == History and Motivation
594 The original AltoOS telemetry mechanism encoded everything
595 available piece of information on the TeleMetrum hardware into a
596 single unified packet. Initially, the packets contained very
597 little data—some raw sensor readings along with the current GPS
598 coordinates when a GPS receiver was connected. Over time, the
599 amount of data grew to include sensor calibration data, GPS
600 satellite information and a host of internal state information
601 designed to help diagnose flight failures in case of a loss of
602 the on-board flight data.
604 Because every packet contained all of the data, packets were
605 huge—95 bytes long. Much of the information was also specific to
606 the TeleMetrum hardware. With the introduction of the TeleMini
607 flight computer, most of the data contained in the telemetry
608 packets was unavailable. Initially, a shorter, but still
609 comprehensive packet was implemented. This required that the
610 ground station be pre-configured as to which kind of packet to
613 The development of several companion boards also made the
614 shortcomings evident—each companion board would want to include
615 telemetry data in the radio link; with the original design, the
616 packet would have to hold the new data as well, requiring
617 additional TeleMetrum and ground station changes.