6 == Packet Format Design
8 AltOS telemetry data is split into multiple different packets,
9 all the same size, but each includs an identifier so that the
10 ground station can distinguish among different types. A single
11 flight board will transmit multiple packet types, each type on
12 a different schedule. The ground software need look for only a
13 single packet size, and then decode the information within the
14 packet and merge data from multiple packets to construct the
15 full flight computer state.
17 Each AltOS packet is 32 bytes long. This size was chosen based
18 on the known telemetry data requirements. The power of two
19 size allows them to be stored easily in flash memory without
20 having them split across blocks or leaving gaps at the end.
22 All packet types start with a five byte header which encodes
23 the device serial number, device clock value and the packet
24 type. The remaining 27 bytes encode type-specific data.
28 This section first defines the packet header common to all packets
29 and then the per-packet data layout.
33 .Telemetry Packet Header
34 [options="border",cols="2,3,3,9"]
36 |Offset |Data Type |Name |Description
37 |0 |uint16_t |serial |Device serial Number
38 |2 |uint16_t |tick |Device time in 100ths of a second
39 |4 |uint8_t |type |Packet type
43 Each packet starts with these five bytes which serve to identify
44 which device has transmitted the packet, when it was transmitted
45 and what the rest of the packet contains.
47 === TeleMetrum v1.x, TeleMini and TeleNano Sensor Data
50 [options="border",cols="1,3"]
53 |0x01 |TeleMetrum v1.x Sensor Data
54 |0x02 |TeleMini Sensor Data
55 |0x03 |TeleNano Sensor Data
58 TeleMetrum v1.x, TeleMini and TeleNano share this same
59 packet format for sensor data. Each uses a distinct
60 packet type so that the receiver knows which data
61 values are valid and which are undefined.
63 Sensor Data packets are transmitted once per second on
64 the ground, 10 times per second during ascent and once
65 per second during descent and landing
67 .Sensor Packet Contents
68 [options="border",cols="2,3,3,9"]
70 |Offset |Data Type |Name |Description
71 |5 |uint8_t |state |Flight state
72 |6 |int16_t |accel |accelerometer (TM only)
73 |8 |int16_t |pres |pressure sensor
74 |10 |int16_t |temp |temperature sensor
75 |12 |int16_t |v_batt |battery voltage
76 |14 |int16_t |sense_d |drogue continuity sense (TM/Tm)
77 |16 |int16_t |sense_m |main continuity sense (TM/Tm)
78 |18 |int16_t |acceleration |m/s² * 16
79 |20 |int16_t |speed |m/s * 16
80 |22 |int16_t |height |m
81 |24 |int16_t |ground_pres |Average barometer reading on ground
82 |26 |int16_t |ground_accel |TM
83 |28 |int16_t |accel_plus_g |TM
84 |30 |int16_t |accel_minus_g |TM
88 === TeleMega Sensor Data
91 [options="border",cols="1,3"]
94 |0x08 |TeleMega IMU Sensor Data
95 |0x09 |TeleMega Kalman and Voltage Data
98 TeleMega has a lot of sensors, and so it splits the sensor
99 data into two packets. The raw IMU data are sent more often;
100 the voltage values don't change very fast, and the Kalman
101 values can be reconstructed from the IMU data.
103 IMU Sensor Data packets are transmitted once per second on the
104 ground, 10 times per second during ascent and once per second
105 during descent and landing
107 Kalman and Voltage Data packets are transmitted once per second on the
108 ground, 5 times per second during ascent and once per second
109 during descent and landing
111 The high-g accelerometer is reported separately from the data
112 for the 9-axis IMU (accel/gyro/mag). The 9-axis IMU is mounted
113 so that the X axis is "across" the board (along the short
114 axis0, the Y axis is "along" the board (along the long axis,
115 with the high-g accelerometer) and the Z axis is "through" the
116 board (perpendicular to the board). Rotation measurements are
117 around the respective axis, so Y rotation measures the spin
118 rate of the rocket while X and Z rotation measure the tilt
121 The overall tilt angle of the rocket is computed by first
122 measuring the orientation of the rocket on the pad using the 3
123 axis accelerometer, and then integrating the overall tilt rate
124 from the 3 axis gyroscope to compute the total orientation
125 change of the airframe since liftoff.
127 .TeleMega IMU Sensor Packet Contents
128 [options="border",cols="2,3,3,9"]
130 |Offset |Data Type |Name |Description
131 |5 |uint8_t |orient |Angle from vertical in degrees
132 |6 |int16_t |accel |High G accelerometer
133 |8 |int32_t |pres |pressure (Pa * 10)
134 |12 |int16_t |temp |temperature (°C * 100)
135 |14 |int16_t |accel_x |X axis acceleration (across)
136 |16 |int16_t |accel_y |Y axis acceleration (along)
137 |18 |int16_t |accel_z |Z axis acceleration (through)
138 |20 |int16_t |gyro_x |X axis rotation (across)
139 |22 |int16_t |gyro_y |Y axis rotation (along)
140 |24 |int16_t |gyro_z |Z axis rotation (through)
141 |26 |int16_t |mag_x |X field strength (across)
142 |28 |int16_t |mag_y |Y field strength (along)
143 |30 |int16_t |mag_z |Z field strength (through)
147 .TeleMega Kalman and Voltage Data Packet Contents
148 [options="border",cols="2,3,3,9"]
150 |Offset |Data Type |Name |Description
151 |5 |uint8_t |state |Flight state
152 |6 |int16_t |v_batt |battery voltage
153 |8 |int16_t |v_pyro |pyro battery voltage
154 |10 |int8_t[6] |sense |pyro continuity sense
155 |16 |int32_t |ground_pres |Average barometer reading on ground
156 |20 |int16_t |ground_accel |Average accelerometer reading on ground
157 |22 |int16_t |accel_plus_g |Accel calibration at +1g
158 |24 |int16_t |accel_minus_g |Accel calibration at -1g
159 |26 |int16_t |acceleration |m/s² * 16
160 |28 |int16_t |speed |m/s * 16
161 |30 |int16_t |height |m
165 === TeleMetrum v2 Sensor Data
167 .TeleMetrum v2 Packet Type
168 [options="border",cols="1,3"]
171 |0x0A |TeleMetrum v2 Sensor Data
172 |0x0B |TeleMetrum v2 Calibration Data
175 TeleMetrum v2 has higher resolution barometric data than
176 TeleMetrum v1, and so the constant calibration data is
177 split out into a separate packet.
179 TeleMetrum v2 Sensor Data packets are transmitted once per second on the
180 ground, 10 times per second during ascent and once per second
181 during descent and landing
183 TeleMetrum v2 Calibration Data packets are always transmitted once per second.
185 .TeleMetrum v2 Sensor Packet Contents
186 [options="border",cols="2,3,3,9"]
188 |Offset |Data Type |Name |Description
189 |5 |uint8_t |state |Flight state
190 |6 |int16_t |accel |accelerometer
191 |8 |int32_t |pres |pressure sensor (Pa * 10)
192 |12 |int16_t |temp |temperature sensor (°C * 100)
193 |14 |int16_t |acceleration |m/s² * 16
194 |16 |int16_t |speed |m/s * 16
195 |18 |int16_t |height |m
196 |20 |int16_t |v_batt |battery voltage
197 |22 |int16_t |sense_d |drogue continuity sense
198 |24 |int16_t |sense_m |main continuity sense
199 |26 |pad[6] |pad bytes |
203 .TeleMetrum v2 Calibration Data Packet Contents
204 [options="border",cols="2,3,3,9"]
206 |Offset |Data Type |Name |Description
207 |5 |pad[3] |pad bytes |
208 |8 |int32_t |ground_pres |Average barometer reading on ground
209 |12 |int16_t |ground_accel |Average accelerometer reading on ground
210 |14 |int16_t |accel_plus_g |Accel calibration at +1g
211 |16 |int16_t |accel_minus_g |Accel calibration at -1g
212 |18 |pad[14] |pad bytes |
216 === Configuration Data
218 .Configuration Packet Type
219 [options="border",cols="1,3"]
222 |0x04 |Configuration Data
225 This provides a description of the software installed on the
226 flight computer as well as any user-specified configuration data.
228 Configuration data packets are transmitted once per second
229 during all phases of the flight
231 .Configuration Packet Contents
232 [options="border",cols="2,3,3,9"]
234 |Offset |Data Type |Name |Description
235 |5 |uint8_t |type |Device type
236 |6 |uint16_t |flight |Flight number
237 |8 |uint8_t |config_major |Config major version
238 |9 |uint8_t |config_minor |Config minor version
239 |10 |uint16_t |apogee_delay |Apogee deploy delay in seconds
240 |12 |uint16_t |main_deploy |Main deploy alt in meters
241 |14 |uint16_t |flight_log_max |Maximum flight log size (kB)
242 |16 |char |callsign[8] |Radio operator identifier
243 |24 |char |version[8] |Software version identifier
250 [options="border",cols="1,3"]
256 This packet provides all of the information available from the
257 GPS receiver—position, time, speed and precision
260 GPS Location packets are transmitted once per second during
261 all phases of the flight
263 .GPS Location Packet Contents
264 [options="border",cols="2,3,3,9"]
266 |Offset |Data Type |Name |Description
267 |5 |uint8_t |flags |See GPS Flags table below
268 |6 |int16_t |altitude |m
269 |8 |int32_t |latitude |degrees * 107
270 |12 |int32_t |longitude |degrees * 107
272 |17 |uint8_t |month |
275 |20 |uint8_t |minute |
276 |21 |uint8_t |second |
277 |22 |uint8_t |pdop |* 5
278 |23 |uint8_t |hdop |* 5
279 |24 |uint8_t |vdop |* 5
280 |25 |uint8_t |mode |See GPS Mode table below
281 |26 |uint16_t |ground_speed |cm/s
282 |28 |int16_t |climb_rate |cm/s
283 |30 |uint8_t |course |/ 2
284 |31 |uint8_t |unused[1] |
288 Packed into a one byte field are status flags and the
289 count of satellites used to compute the position
290 fix. Note that this number may be lower than the
291 number of satellites being tracked; the receiver will
292 not use information from satellites with weak signals
293 or which are close enough to the horizon to have
294 significantly degraded position accuracy.
297 [options="border",cols="1,2,7"]
299 |Bits |Name |Description
300 |0-3 |nsats |Number of satellites in solution
301 |4 |valid |GPS solution is valid
302 |5 |running |GPS receiver is operational
303 |6 |date_valid |Reported date is valid
304 |7 |course_valid |ground speed, course and climb rates are valid
307 Here are all of the valid GPS operational modes. Altus
308 Metrum products will only ever report 'N' (not valid),
309 'A' (Autonomous) modes or 'E' (Estimated). The
310 remaining modes are either testing modes or require
314 [options="border",cols="1,3,7"]
316 |Mode |Name |Description
317 |N |Not Valid |All data are invalid
318 |A |Autonomous mode |
319 Data are derived from satellite data
321 |D |Differential Mode |
322 Data are augmented with differential data from a
323 known ground station. The SkyTraq unit in TeleMetrum
324 does not support this mode
327 Data are estimated using dead reckoning from the
331 Data were entered manually
334 GPS receiver testing mode
338 === GPS Satellite Data
340 .GPS Satellite Data Packet Type
341 [options="border",cols="1,3"]
344 |0x06 |GPS Satellite Data
347 This packet provides space vehicle identifiers and
348 signal quality information in the form of a C/N1
349 number for up to 12 satellites. The order of the svids
352 GPS Satellite data are transmitted once per second
353 during all phases of the flight.
355 .GPS Satellite Data Contents
356 [options="border",cols="2,3,3,9"]
358 |Offset |Data Type |Name |Description
359 |5 |uint8_t |channels |Number of reported satellite information
360 |6 |sat_info_t |sats[12] |See Per-Satellite data table below
361 |30 |uint8_t |unused[2] |
365 .GPS Per-Satellite data (sat_info_t)
366 [options="border",cols="2,3,3,9"]
368 |Offset |Data Type |Name |Description
369 |0 |uint8_t |svid |Space Vehicle Identifier
370 |1 |uint8_t |c_n_1 |C/N1 signal quality indicator
376 .Companion Data Packet Type
377 [options="border",cols="1,3"]
380 |0x07 |Companion Data
383 When a companion board is attached to TeleMega or
384 TeleMetrum, it can provide telemetry data to be
385 included in the downlink. The companion board can
386 provide up to 12 16-bit data values.
388 The companion board itself specifies the transmission
389 rate. On the ground and during descent, that rate is
390 limited to one packet per second. During ascent, that
391 rate is limited to 10 packets per second.
393 .Companion Data Contents
394 [options="border",cols="2,3,3,9"]
396 |Offset |Data Type |Name |Description
397 |5 |uint8_t |board_id |Type of companion board attached
398 |6 |uint8_t |update_period |How often telemetry is sent, in 1/100ths of a second
399 |7 |uint8_t |channels |Number of data channels supplied
400 |8 |uint16_t[12] |companion_data |Up to 12 channels of 16-bit companion data
406 Altus Metrum devices use Texas Instruments sub-GHz digital
407 radio products. Ground stations use parts with HW FEC while
408 some flight computers perform FEC in software. TeleGPS is
411 .Altus Metrum Radio Parts
412 [options="border",cols="1,4,4"]
414 |Part Number |Description |Used in
417 |10mW transceiver with integrated SoC
418 |TeleDongle v0.2, TeleBT v1.0, TeleMetrum v1.x, TeleMini
421 |35mW transceiver with SW FEC
422 |TeleMetrum v2, TeleMega
425 |35mW transceiver with HW FEC
426 |TeleDongle v3.0, TeleBT v3.0
429 |14mW transmitter with SW FEC
434 === Modulation Scheme
436 Texas Instruments provides a tool for computing
437 modulation parameters given a desired modulation
438 format and basic bit rate.
440 While we might like to use something with better
441 low-signal performance like BPSK, the radios we use
442 don't support that, but do support Gaussian frequency
443 shift keying (GFSK). Regular frequency shift keying
444 (FSK) encodes the signal by switching the carrier
445 between two frequencies. The Gaussian version is
446 essentially the same, but the shift between
447 frequencies gently follows a gaussian curve, rather
448 than switching immediately. This tames the bandwidth
449 of the signal without affecting the ability to
452 For AltOS, there are three available bit rates,
453 38.4kBaud, 9.6kBaud and 2.4kBaud resulting in the
454 following signal parmeters:
457 [options="border",cols="1,1,1"]
459 |Rate |Deviation |Receiver Bandwidth
460 |38.4kBaud |20.5kHz |100kHz
461 |9.6kBaud |5.125kHz |25kHz
462 |2.4kBaud |1.5kHz |5kHz
467 The cc1111 and cc1200 provide forward error correction
468 in hardware; on the cc1120 and cc115l that's done in
469 software. AltOS uses this to improve reception of weak
470 signals. As it's a rate 1/2 encoding, each bit of data
471 takes two bits when transmitted, so the effective data
472 rate is half of the raw transmitted bit rate.
475 [options="border",cols="1,1,1"]
477 |Parameter |Value |Description
480 |Convolutional coding
481 |1/2 rate, constraint length m=4
485 |Reduce effect of noise burst
489 |Rotate right with bit 8 = bit 0 xor bit 5, initial value 111111111
493 == TeleDongle serial packet format
495 TeleDongle does not do any interpretation of the packet data,
496 instead it is configured to receive packets of a specified
497 length (32 bytes in this case). For each received packet,
498 TeleDongle produces a single line of text. This line starts with
499 the string "TELEM " and is followed by a list of hexadecimal
503 TELEM 224f01080b05765e00701f1a1bbeb8d7b60b070605140c000600000000000000003fa988
506 The hexadecimal encoded string of bytes contains a length byte,
507 the packet data, two bytes added by the cc1111 radio receiver
508 hardware and finally a checksum so that the host software can
509 validate that the line was transmitted without any errors.
511 .TeleDongle serial Packet Format
513 [options="border",cols="2,1,1,5"]
515 |Offset |Name |Example |Description
520 |Total length of data bytes in the line. Note that
521 this includes the added RSSI and status bytes
526 |Bytes of actual packet data
531 |Received signal strength. dBm = rssi / 2 - 74
536 |Link Quality Indicator and CRC status. Bit 7
537 is set when the CRC is correct
542 |(0x5a + sum(bytes 1 ·· length-1)) % 256
546 == History and Motivation
548 The original AltoOS telemetry mechanism encoded everything
549 available piece of information on the TeleMetrum hardware into a
550 single unified packet. Initially, the packets contained very
551 little data—some raw sensor readings along with the current GPS
552 coordinates when a GPS receiver was connected. Over time, the
553 amount of data grew to include sensor calibration data, GPS
554 satellite information and a host of internal state information
555 designed to help diagnose flight failures in case of a loss of
556 the on-board flight data.
558 Because every packet contained all of the data, packets were
559 huge—95 bytes long. Much of the information was also specific to
560 the TeleMetrum hardware. With the introduction of the TeleMini
561 flight computer, most of the data contained in the telemetry
562 packets was unavailable. Initially, a shorter, but still
563 comprehensive packet was implemented. This required that the
564 ground station be pre-configured as to which kind of packet to
567 The development of several companion boards also made the
568 shortcomings evident—each companion board would want to include
569 telemetry data in the radio link; with the original design, the
570 packet would have to hold the new data as well, requiring
571 additional TeleMetrum and ground station changes.