1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
7 <title>AltOS Telemetry</title>
8 <subtitle>Packet Definitions</subtitle>
10 <firstname>Keith</firstname>
11 <surname>Packard</surname>
15 <holder>Keith Packard</holder>
19 This document is released under the terms of the
20 <ulink url="http://creativecommons.org/licenses/by-sa/3.0/">
21 Creative Commons ShareAlike 3.0
28 <revnumber>0.1</revnumber>
29 <date>01 July 2011</date>
30 <revremark>Initial content</revremark>
35 <title>Packet Format Design</title>
37 AltOS telemetry data is split into multiple different packets,
38 all the same size, but each includs an identifier so that the
39 ground station can distinguish among different types. A single
40 flight board will transmit multiple packet types, each type on a
41 different schedule. The ground software need look for only a
42 single packet size, and then decode the information within the
43 packet and merge data from multiple packets to construct the
44 full flight computer state.
47 Each AltOS packet is 32 bytes long. This size was chosen based
48 on the known telemetry data requirements. The power of two size
49 allows them to be stored easily in flash memory without having
50 them split across blocks or leaving gaps at the end.
53 All packet types start with a five byte header which encodes the
54 device serial number, device clock value and the packet
55 type. The remaining 27 bytes encode type-specific data.
59 <title>Packet Formats</title>
61 This section first defines the packet header common to all packets
62 and then the per-packet data layout.
65 <title>Packet Header</title>
67 <title>Telemetry Packet Header</title>
68 <tgroup cols='4' align='center' colsep='1' rowsep='1'>
69 <colspec align='center' colwidth='*' colname='Offset'/>
70 <colspec align='center' colwidth='3*' colname='Data Type'/>
71 <colspec align='left' colwidth='3*' colname='Name'/>
72 <colspec align='left' colwidth='9*' colname='Description'/>
75 <entry align='center'>Offset</entry>
76 <entry align='center'>Data Type</entry>
77 <entry align='center'>Name</entry>
78 <entry align='center'>Description</entry>
84 <entry>uint16_t</entry>
86 <entry>Device serial Number</entry>
90 <entry>uint16_t</entry>
92 <entry>Device time in 100ths of a second</entry>
96 <entry>uint8_t</entry>
98 <entry>Packet type</entry>
107 Each packet starts with these five bytes which serve to identify
108 which device has transmitted the packet, when it was transmitted
109 and what the rest of the packet contains.
113 <title>Sensor Data</title>
114 <informaltable frame='none' label='' tocentry='0'>
115 <tgroup cols='2' align='center' colsep='1' rowsep='1'>
116 <colspec align='center' colwidth='*' colname='Offset'/>
117 <colspec align='left' colwidth='3*' colname='Description'/>
121 <entry>Description</entry>
127 <entry>TeleMetrum Sensor Data</entry>
131 <entry>TeleMini Sensor Data</entry>
135 <entry>TeleNano Sensor Data</entry>
141 TeleMetrum, TeleMini and TeleNano share this same packet
142 format for sensor data. Each uses a distinct packet type so
143 that the receiver knows which data values are valid and which
147 Sensor Data packets are transmitted once per second on the
148 ground, 10 times per second during ascent and once per second
149 during descent and landing
152 <title>Sensor Packet Contents</title>
153 <tgroup cols='4' align='center' colsep='1' rowsep='1'>
154 <colspec align='center' colwidth='*' colname='Offset'/>
155 <colspec align='center' colwidth='3*' colname='Data Type'/>
156 <colspec align='left' colwidth='3*' colname='Name'/>
157 <colspec align='left' colwidth='9*' colname='Description'/>
160 <entry align='center'>Offset</entry>
161 <entry align='center'>Data Type</entry>
162 <entry align='center'>Name</entry>
163 <entry align='center'>Description</entry>
168 <entry>5</entry><entry>uint8_t</entry><entry>state</entry><entry>Flight state</entry>
171 <entry>6</entry><entry>int16_t</entry><entry>accel</entry><entry>accelerometer (TM only)</entry>
174 <entry>8</entry><entry>int16_t</entry><entry>pres</entry><entry>pressure sensor</entry>
177 <entry>10</entry><entry>int16_t</entry><entry>temp</entry><entry>temperature sensor</entry>
180 <entry>12</entry><entry>int16_t</entry><entry>v_batt</entry><entry>battery voltage</entry>
183 <entry>14</entry><entry>int16_t</entry><entry>sense_d</entry><entry>drogue continuity sense (TM/Tm)</entry>
186 <entry>16</entry><entry>int16_t</entry><entry>sense_m</entry><entry>main continuity sense (TM/Tm)</entry>
189 <entry>18</entry><entry>int16_t</entry><entry>acceleration</entry><entry>m/s² * 16</entry>
192 <entry>20</entry><entry>int16_t</entry><entry>speed</entry><entry>m/s * 16</entry>
195 <entry>22</entry><entry>int16_t</entry><entry>height</entry><entry>m</entry>
198 <entry>24</entry><entry>int16_t</entry><entry>ground_pres</entry><entry>Average barometer reading on ground</entry>
201 <entry>26</entry><entry>int16_t</entry><entry>ground_accel</entry><entry>TM</entry>
204 <entry>28</entry><entry>int16_t</entry><entry>accel_plus_g</entry><entry>TM</entry>
207 <entry>30</entry><entry>int16_t</entry><entry>accel_minus_g</entry><entry>TM</entry>
217 <title>Configuration Data</title>
218 <informaltable frame='none' label='' tocentry='0'>
219 <tgroup cols='2' align='center' colsep='1' rowsep='1'>
220 <colspec align='center' colwidth='*' colname='Offset'/>
221 <colspec align='left' colwidth='3*' colname='Description'/>
225 <entry>Description</entry>
231 <entry>Configuration Data</entry>
237 This provides a description of the software installed on the
238 flight computer as well as any user-specified configuration data.
241 Configuration data packets are transmitted once per second
242 during all phases of the flight
245 <title>Sensor Packet Contents</title>
246 <tgroup cols='4' align='center' colsep='1' rowsep='1'>
247 <colspec align='center' colwidth='*' colname='Offset'/>
248 <colspec align='center' colwidth='3*' colname='Data Type'/>
249 <colspec align='left' colwidth='3*' colname='Name'/>
250 <colspec align='left' colwidth='9*' colname='Description'/>
253 <entry align='center'>Offset</entry>
254 <entry align='center'>Data Type</entry>
255 <entry align='center'>Name</entry>
256 <entry align='center'>Description</entry>
261 <entry>5</entry><entry>uint8_t</entry><entry>type</entry><entry>Device type</entry>
264 <entry>6</entry><entry>uint16_t</entry><entry>flight</entry><entry>Flight number</entry>
267 <entry>8</entry><entry>uint8_t</entry><entry>config_major</entry><entry>Config major version</entry>
270 <entry>9</entry><entry>uint8_t</entry><entry>config_minor</entry><entry>Config minor version</entry>
273 <entry>10</entry><entry>uint16_t</entry><entry>apogee_delay</entry>
274 <entry>Apogee deploy delay in seconds</entry>
277 <entry>12</entry><entry>uint16_t</entry><entry>main_deploy</entry><entry>Main deploy alt in meters</entry>
280 <entry>14</entry><entry>uint16_t</entry><entry>flight_log_max</entry>
281 <entry>Maximum flight log size (kB)</entry>
284 <entry>16</entry><entry>char</entry><entry>callsign[8]</entry><entry>Radio operator identifier</entry>
287 <entry>24</entry><entry>char</entry><entry>version[8]</entry><entry>Software version identifier</entry>
297 <title>GPS Location</title>
298 <informaltable frame='none' label='' tocentry='0'>
299 <tgroup cols='2' align='center' colsep='1' rowsep='1'>
300 <colspec align='center' colwidth='*' colname='Offset'/>
301 <colspec align='left' colwidth='3*' colname='Description'/>
305 <entry>Description</entry>
311 <entry>GPS Location</entry>
317 This packet provides all of the information available from the
318 Venus SkyTraq GPS receiver—position, time, speed and precision
322 GPS Location packets are transmitted once per second during
323 all phases of the flight
326 <title>GPS Location Packet Contents</title>
327 <tgroup cols='4' align='center' colsep='1' rowsep='1'>
328 <colspec align='center' colwidth='*' colname='Offset'/>
329 <colspec align='center' colwidth='3*' colname='Data Type'/>
330 <colspec align='left' colwidth='3*' colname='Name'/>
331 <colspec align='left' colwidth='9*' colname='Description'/>
334 <entry align='center'>Offset</entry>
335 <entry align='center'>Data Type</entry>
336 <entry align='center'>Name</entry>
337 <entry align='center'>Description</entry>
342 <entry>5</entry><entry>uint8_t</entry><entry>flags</entry>
343 <entry>See GPS Flags table below</entry>
346 <entry>6</entry><entry>int16_t</entry><entry>altitude</entry><entry>m</entry>
349 <entry>8</entry><entry>int32_t</entry><entry>latitude</entry><entry>degrees * 10<superscript>7</superscript></entry>
352 <entry>12</entry><entry>int32_t</entry><entry>longitude</entry><entry>degrees * 10<superscript>7</superscript></entry>
355 <entry>16</entry><entry>uint8_t</entry><entry>year</entry>
358 <entry>17</entry><entry>uint8_t</entry><entry>month</entry>
361 <entry>18</entry><entry>uint8_t</entry><entry>day</entry>
364 <entry>19</entry><entry>uint8_t</entry><entry>hour</entry>
367 <entry>20</entry><entry>uint8_t</entry><entry>minute</entry>
370 <entry>21</entry><entry>uint8_t</entry><entry>second</entry>
373 <entry>22</entry><entry>uint8_t</entry><entry>pdop</entry><entry>* 5</entry>
376 <entry>23</entry><entry>uint8_t</entry><entry>hdop</entry><entry>* 5</entry>
379 <entry>24</entry><entry>uint8_t</entry><entry>vdop</entry><entry>* 5</entry>
382 <entry>25</entry><entry>uint8_t</entry><entry>mode</entry>
383 <entry>See GPS Mode table below</entry>
386 <entry>26</entry><entry>uint16_t</entry><entry>ground_speed</entry><entry>cm/s</entry>
389 <entry>28</entry><entry>int16_t</entry><entry>climb_rate</entry><entry>cm/s</entry>
392 <entry>30</entry><entry>uint8_t</entry><entry>course</entry><entry>/ 2</entry>
395 <entry>31</entry><entry>uint8_t</entry><entry>unused[1]</entry>
404 Packed into a one byte field are status flags and the count of
405 satellites used to compute the position fix. Note that this
406 number may be lower than the number of satellites being
407 tracked; the receiver will not use information from satellites
408 with weak signals or which are close enough to the horizon to
409 have significantly degraded position accuracy.
412 <title>GPS Flags</title>
413 <tgroup cols='3' colsep='1' rowsep='1'>
414 <colspec align='center' colwidth='*' colname='bits'/>
415 <colspec align='left' colwidth='2*' colname='name'/>
416 <colspec align='left' colwidth='7*' colname='description'/>
419 <entry align='center'>Bits</entry>
420 <entry align='center'>Name</entry>
421 <entry align='center'>Description</entry>
428 <entry>Number of satellites in solution</entry>
433 <entry>GPS solution is valid</entry>
437 <entry>running</entry>
438 <entry>GPS receiver is operational</entry>
442 <entry>date_valid</entry>
443 <entry>Reported date is valid</entry>
447 <entry>course_valid</entry>
448 <entry>ground speed, course and climb rates are valid</entry>
454 Here are all of the valid GPS operational modes. Altus Metrum
455 products will only ever report 'N' (not valid), 'A'
456 (Autonomous) modes or 'E' (Estimated). The remaining modes
457 are either testing modes or require additional data.
460 <title>GPS Mode</title>
461 <tgroup cols='3' colsep='1' rowsep='1'>
462 <colspec align='center' colwidth='*' colname='value'/>
463 <colspec align='center' colwidth='3*' colname='name'/>
464 <colspec align='left' colwidth='7*' colname='description'/>
467 <entry align='center'>Mode</entry>
468 <entry align='center'>Name</entry>
469 <entry align='center'>Decsription</entry>
475 <entry>Not Valid</entry>
476 <entry>All data are invalid</entry>
480 <entry>Autonomous mode</entry>
481 <entry>Data are derived from satellite data</entry>
485 <entry>Differential Mode</entry>
487 Data are augmented with differential data from a
488 known ground station. The SkyTraq unit in TeleMetrum
489 does not support this mode
494 <entry>Estimated</entry>
496 Data are estimated using dead reckoning from the
502 <entry>Manual</entry>
503 <entry>Data were entered manually</entry>
507 <entry>Simulated</entry>
508 <entry>GPS receiver testing mode</entry>
515 <title>GPS Satellite Data</title>
516 <informaltable frame='none' label='' tocentry='0'>
517 <tgroup cols='2' align='center' colsep='1' rowsep='1'>
518 <colspec align='center' colwidth='*' colname='Offset'/>
519 <colspec align='left' colwidth='3*' colname='Description'/>
523 <entry>Description</entry>
529 <entry>GPS Satellite Data</entry>
535 This packet provides space vehicle identifiers and signal
536 quality information in the form of a C/N1 number for up to 12
537 satellites. The order of the svids is not specified.
540 GPS Satellite data are transmitted once per second during all
541 phases of the flight.
544 <title>GPS Satellite Data Contents</title>
545 <tgroup cols='4' align='center' colsep='1' rowsep='1'>
546 <colspec align='right' colwidth='*' colname='Offset'/>
547 <colspec align='center' colwidth='3*' colname='Data Type'/>
548 <colspec align='left' colwidth='3*' colname='Name'/>
549 <colspec align='left' colwidth='9*' colname='Description'/>
552 <entry align='center'>Offset</entry>
553 <entry align='center'>Data Type</entry>
554 <entry align='center'>Name</entry>
555 <entry align='center'>Description</entry>
560 <entry>5</entry><entry>uint8_t</entry><entry>channels</entry>
561 <entry>Number of reported satellite information</entry>
564 <entry>6</entry><entry>sat_info_t</entry><entry>sats[12]</entry>
565 <entry>See Per-Satellite data table below</entry>
568 <entry>30</entry><entry>uint8_t</entry><entry>unused[2]</entry>
577 <title>GPS Per-Satellite data (sat_info_t)</title>
578 <tgroup cols='4' align='center' colsep='1' rowsep='1'>
579 <colspec align='right' colwidth='*' colname='Offset'/>
580 <colspec align='center' colwidth='3*' colname='Data Type'/>
581 <colspec align='left' colwidth='3*' colname='Name'/>
582 <colspec align='left' colwidth='9*' colname='Description'/>
585 <entry align='center'>Offset</entry>
586 <entry align='center'>Data Type</entry>
587 <entry align='center'>Name</entry>
588 <entry align='center'>Description</entry>
593 <entry>0</entry><entry>uint8_t</entry><entry>svid</entry>
594 <entry>Space Vehicle Identifier</entry>
597 <entry>1</entry><entry>uint8_t</entry><entry>c_n_1</entry>
598 <entry>C/N1 signal quality indicator</entry>
609 <title>Data Transmission</title>
611 Altus Metrum devices use the Texas Instruments CC1111
612 microcontroller which includes an integrated sub-GHz digital
613 transceiver. This transceiver is used to both transmit and
614 receive the telemetry packets. This section discusses what
615 modulation scheme is used and how this device is configured.
618 <title>Modulation Scheme</title>
620 Texas Instruments provides a tool for computing modulation
621 parameters given a desired modulation format and basic bit
622 rate. For AltOS, the basic bit rate was specified as 38 kBaud,
623 resulting in the following signal parmeters:
626 <title>Modulation Scheme</title>
628 <colspec align="center" colwidth="*" colname="parameter"/>
629 <colspec align="center" colwidth="*" colname="value"/>
630 <colspec align="center" colwidth="*" colname="description"/>
633 <entry align='center'>Parameter</entry>
634 <entry align='center'>Value</entry>
635 <entry align='center'>Description</entry>
640 <entry>Modulation</entry>
642 <entry>Gaussian Frequency Shift Keying</entry>
645 <entry>Deviation</entry>
646 <entry>20.507812 kHz</entry>
647 <entry>Frequency modulation</entry>
650 <entry>Data rate</entry>
651 <entry>38.360596 kBaud</entry>
652 <entry>Raw bit rate</entry>
655 <entry>RX Filter Bandwidth</entry>
656 <entry>93.75 kHz</entry>
657 <entry>Receiver Band pass filter bandwidth</entry>
660 <entry>IF Frequency</entry>
661 <entry>140.62 kHz</entry>
662 <entry>Receiver intermediate frequency</entry>
669 <title>Error Correction</title>
671 The cc1111 provides forward error correction in hardware,
672 which AltOS uses to improve reception of weak signals. The
673 overall effect of this is to halve the available bandwidth for
674 data from 38 kBaud to 19 kBaud.
677 <title>Error Correction</title>
679 <colspec align="center" colwidth="*" colname="parameter"/>
680 <colspec align="center" colwidth="*" colname="value"/>
681 <colspec align="center" colwidth="*" colname="description"/>
684 <entry align='center'>Parameter</entry>
685 <entry align='center'>Value</entry>
686 <entry align='center'>Description</entry>
691 <entry>Error Correction</entry>
692 <entry>Convolutional coding</entry>
693 <entry>1/2 rate, constraint length m=4</entry>
696 <entry>Interleaving</entry>
698 <entry>Reduce effect of noise burst</entry>
701 <entry>Data Whitening</entry>
702 <entry>XOR with 9-bit PNR</entry>
703 <entry>Rotate right with bit 8 = bit 0 xor bit 5, initial
704 value 111111111</entry>
712 <title>TeleDongle packet format</title>
714 TeleDongle does not do any interpretation of the packet data,
715 instead it is configured to receive packets of a specified
716 length (32 bytes in this case). For each received packet,
717 TeleDongle produces a single line of text. This line starts with
718 the string "TELEM " and is followed by a list of hexadecimal
721 <programlisting>TELEM 224f01080b05765e00701f1a1bbeb8d7b60b070605140c000600000000000000003fa988</programlisting>
723 The hexadecimal encoded string of bytes contains a length byte,
724 the packet data, two bytes added by the cc1111 radio receiver
725 hardware and finally a checksum so that the host software can
726 validate that the line was transmitted without any errors.
729 <title>Packet Format</title>
731 <colspec align="center" colwidth="2*" colname="offset"/>
732 <colspec align="center" colwidth="*" colname="name"/>
733 <colspec align="center" colwidth="*" colname="value"/>
734 <colspec align="center" colwidth="5*" colname="description"/>
737 <entry align='center'>Offset</entry>
738 <entry align='center'>Name</entry>
739 <entry align='center'>Example</entry>
740 <entry align='center'>Description</entry>
746 <entry>length</entry>
748 <entry>Total length of data bytes in the line. Note that
749 this includes the added RSSI and status bytes</entry>
752 <entry>1 ·· length-3</entry>
753 <entry>packet</entry>
754 <entry>4f ·· 00</entry>
755 <entry>Bytes of actual packet data</entry>
758 <entry>length-2</entry>
761 <entry>Received signal strength. dBm = rssi / 2 - 74</entry>
764 <entry>length-1</entry>
767 <entry>Link Quality Indicator and CRC status. Bit 7
768 is set when the CRC is correct</entry>
771 <entry>length</entry>
772 <entry>checksum</entry>
774 <entry>(0x5a + sum(bytes 1 ·· length-1)) % 256</entry>
781 <title>History and Motivation</title>
783 The original AltoOS telemetry mechanism encoded everything
784 available piece of information on the TeleMetrum hardware into a
785 single unified packet. Initially, the packets contained very
786 little data—some raw sensor readings along with the current GPS
787 coordinates when a GPS receiver was connected. Over time, the
788 amount of data grew to include sensor calibration data, GPS
789 satellite information and a host of internal state information
790 designed to help diagnose flight failures in case of a loss of
791 the on-board flight data.
794 Because every packet contained all of the data, packets were
795 huge—95 bytes long. Much of the information was also specific to
796 the TeleMetrum hardware. With the introduction of the TeleMini
797 flight computer, most of the data contained in the telemetry
798 packets was unavailable. Initially, a shorter, but still
799 comprehensive packet was implemented. This required that the
800 ground station be pre-configured as to which kind of packet to
804 The development of several companion boards also made the
805 shortcomings evident—each companion board would want to include
806 telemetry data in the radio link; with the original design, the
807 packet would have to hold the new data as well, requiring
808 additional TeleMetrum and ground station changes.