git.gag.com Git - fw/altos/blob - doc/telemetry.xsl

   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">
   4
   5 <article>
   6   <articleinfo>
   7     <title>AltOS Telemetry</title>
   8     <subtitle>Packet Definitions</subtitle>
   9     <author>
  10       <firstname>Keith</firstname>
  11       <surname>Packard</surname>
  12     </author>
  13     <copyright>
  14       <year>2011</year>
  15       <holder>Keith Packard</holder>
  16     </copyright>
  17     <legalnotice>
  18       <para>
  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
  22         </ulink>
  23         license.
  24       </para>
  25     </legalnotice>
  26     <revhistory>
  27       <revision>
  28         <revnumber>0.1</revnumber>
  29         <date>01 July 2011</date>
  30         <revremark>Initial content</revremark>
  31       </revision>
  32     </revhistory>
  33   </articleinfo>
  34   <section>
  35     <title>Packet Format Design</title>
  36     <para>
  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.
  45     </para>
  46     <para>
  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.
  51     </para>
  52     <para>
  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.
  56     </para>
  57   </section>
  58   <section>
  59     <title>Packet Formats</title>
  60     <para>
  61       This section first defines the packet header common to all packets
  62       and then the per-packet data layout.
  63     </para>
  64     <section>
  65       <title>Packet Header</title>
  66       <table frame='all'>
  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'/>
  73           <thead>
  74             <row>
  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>
  79             </row>
  80           </thead>
  81           <tbody>
  82             <row>
  83               <entry>0</entry>
  84               <entry>uint16_t</entry>
  85               <entry>serial</entry>
  86               <entry>Device serial Number</entry>
  87             </row>
  88             <row>
  89               <entry>2</entry>
  90               <entry>uint16_t</entry>
  91               <entry>tick</entry>
  92               <entry>Device time in 100ths of a second</entry>
  93             </row>
  94             <row>
  95               <entry>4</entry>
  96               <entry>uint8_t</entry>
  97               <entry>type</entry>
  98               <entry>Packet type</entry>
  99             </row>
 100             <row>
 101               <entry>5</entry>
 102             </row>
 103           </tbody>
 104         </tgroup>
 105       </table>
 106       <para>
 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.
 110       </para>
 111     </section>
 112     <section>
 113       <title>TeleMetrum v1.x, TeleMini and TeleNano 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'/>
 118           <thead>
 119             <row>
 120               <entry>Type</entry>
 121               <entry>Description</entry>
 122             </row>
 123           </thead>
 124           <tbody>
 125             <row>
 126               <entry>0x01</entry>
 127               <entry>TeleMetrum v1.x Sensor Data</entry>
 128             </row>
 129             <row>
 130               <entry>0x02</entry>
 131               <entry>TeleMini Sensor Data</entry>
 132             </row>
 133             <row>
 134               <entry>0x03</entry>
 135               <entry>TeleNano Sensor Data</entry>
 136             </row>
 137           </tbody>
 138         </tgroup>
 139       </informaltable>
 140       <para>
 141         TeleMetrum v1.x, 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
 144         are undefined.
 145       </para>
 146       <para>
 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
 150       </para>
 151       <table frame='all'>
 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'/>
 158           <thead>
 159             <row>
 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>
 164             </row>
 165           </thead>
 166           <tbody>
 167             <row>
 168               <entry>5</entry><entry>uint8_t</entry><entry>state</entry><entry>Flight state</entry>
 169             </row>
 170             <row>
 171               <entry>6</entry><entry>int16_t</entry><entry>accel</entry><entry>accelerometer (TM only)</entry>
 172             </row>
 173             <row>
 174               <entry>8</entry><entry>int16_t</entry><entry>pres</entry><entry>pressure sensor</entry>
 175             </row>
 176             <row>
 177               <entry>10</entry><entry>int16_t</entry><entry>temp</entry><entry>temperature sensor</entry>
 178             </row>
 179             <row>
 180               <entry>12</entry><entry>int16_t</entry><entry>v_batt</entry><entry>battery voltage</entry>
 181             </row>
 182             <row>
 183               <entry>14</entry><entry>int16_t</entry><entry>sense_d</entry><entry>drogue continuity sense (TM/Tm)</entry>
 184             </row>
 185             <row>
 186               <entry>16</entry><entry>int16_t</entry><entry>sense_m</entry><entry>main continuity sense (TM/Tm)</entry>
 187             </row>
 188             <row>
 189               <entry>18</entry><entry>int16_t</entry><entry>acceleration</entry><entry>m/s² * 16</entry>
 190             </row>
 191             <row>
 192               <entry>20</entry><entry>int16_t</entry><entry>speed</entry><entry>m/s * 16</entry>
 193             </row>
 194             <row>
 195               <entry>22</entry><entry>int16_t</entry><entry>height</entry><entry>m</entry>
 196             </row>
 197             <row>
 198               <entry>24</entry><entry>int16_t</entry><entry>ground_pres</entry><entry>Average barometer reading on ground</entry>
 199             </row>
 200             <row>
 201               <entry>26</entry><entry>int16_t</entry><entry>ground_accel</entry><entry>TM</entry>
 202             </row>
 203             <row>
 204               <entry>28</entry><entry>int16_t</entry><entry>accel_plus_g</entry><entry>TM</entry>
 205             </row>
 206             <row>
 207               <entry>30</entry><entry>int16_t</entry><entry>accel_minus_g</entry><entry>TM</entry>
 208             </row>
 209             <row>
 210               <entry>32</entry>
 211             </row>
 212           </tbody>
 213         </tgroup>
 214       </table>
 215     </section>
 216     <section>
 217       <title>TeleMega Sensor  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'/>
 222           <thead>
 223             <row>
 224               <entry>Type</entry>
 225               <entry>Description</entry>
 226             </row>
 227           </thead>
 228           <tbody>
 229             <row>
 230               <entry>0x08</entry>
 231               <entry>TeleMega IMU Sensor Data</entry>
 232             </row>
 233             <row>
 234               <entry>0x09</entry>
 235               <entry>TeleMega Kalman and Voltage Data</entry>
 236             </row>
 237           </tbody>
 238         </tgroup>
 239       </informaltable>
 240       <para>
 241         TeleMega has a lot of sensors, and so it splits the sensor
 242         data into two packets. The raw IMU data are sent more often;
 243         the voltage values don't change very fast, and the Kalman
 244         values can be reconstructed from the IMU data.
 245       </para>
 246       <para>
 247         IMU Sensor Data packets are transmitted once per second on the
 248         ground, 10 times per second during ascent and once per second
 249         during descent and landing
 250       </para>
 251       <para>
 252         Kalman and Voltage Data packets are transmitted once per second on the
 253         ground, 5 times per second during ascent and once per second
 254         during descent and landing
 255       </para>
 256       <para>
 257         The high-g accelerometer is reported separately from the data
 258         for the 9-axis IMU (accel/gyro/mag). The 9-axis IMU is mounted
 259         so that the X axis is "across" the board (along the short
 260         axis0, the Y axis is "along" the board (along the long axis,
 261         with the high-g accelerometer) and the Z axis is "through" the
 262         board (perpendicular to the board). Rotation measurements are
 263         around the respective axis, so Y rotation measures the spin
 264         rate of the rocket while X and Z rotation measure the tilt
 265         rate.
 266       </para>
 267       <para>
 268         The overall tilt angle of the rocket is computed by first
 269         measuring the orientation of the rocket on the pad using the 3
 270         axis accelerometer, and then integrating the overall tilt rate
 271         from the 3 axis gyroscope to compute the total orientation
 272         change of the airframe since liftoff.
 273       </para>
 274       <table frame='all'>
 275         <title>TeleMega IMU Sensor Packet Contents</title>
 276         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 277           <colspec align='center' colwidth='*' colname='Offset'/>
 278           <colspec align='center' colwidth='3*' colname='Data Type'/>
 279           <colspec align='left' colwidth='3*' colname='Name'/>
 280           <colspec align='left' colwidth='9*' colname='Description'/>
 281           <thead>
 282             <row>
 283               <entry align='center'>Offset</entry>
 284               <entry align='center'>Data Type</entry>
 285               <entry align='center'>Name</entry>
 286               <entry align='center'>Description</entry>
 287             </row>
 288           </thead>
 289           <tbody>
 290             <row>
 291               <entry>5</entry><entry>uint8_t</entry><entry>orient</entry><entry>Angle from vertical in degrees</entry>
 292             </row>
 293             <row>
 294               <entry>6</entry><entry>int16_t</entry><entry>accel</entry><entry>High G accelerometer</entry>
 295             </row>
 296             <row>
 297               <entry>8</entry><entry>int32_t</entry><entry>pres</entry><entry>pressure (Pa * 10)</entry>
 298             </row>
 299             <row>
 300               <entry>12</entry><entry>int16_t</entry><entry>temp</entry><entry>temperature (°C * 100)</entry>
 301             </row>
 302             <row>
 303               <entry>14</entry><entry>int16_t</entry><entry>accel_x</entry><entry>X axis acceleration (across)</entry>
 304             </row>
 305             <row>
 306               <entry>16</entry><entry>int16_t</entry><entry>accel_y</entry><entry>Y axis acceleration (along)</entry>
 307             </row>
 308             <row>
 309               <entry>18</entry><entry>int16_t</entry><entry>accel_z</entry><entry>Z axis acceleration (through)</entry>
 310             </row>
 311             <row>
 312               <entry>20</entry><entry>int16_t</entry><entry>gyro_x</entry><entry>X axis rotation (across)</entry>
 313             </row>
 314             <row>
 315               <entry>22</entry><entry>int16_t</entry><entry>gyro_y</entry><entry>Y axis rotation (along)</entry>
 316             </row>
 317             <row>
 318               <entry>24</entry><entry>int16_t</entry><entry>gyro_z</entry><entry>Z axis rotation (through)</entry>
 319             </row>
 320             <row>
 321               <entry>26</entry><entry>int16_t</entry><entry>mag_x</entry><entry>X field strength (across)</entry>
 322             </row>
 323             <row>
 324               <entry>28</entry><entry>int16_t</entry><entry>mag_y</entry><entry>Y field strength (along)</entry>
 325             </row>
 326             <row>
 327               <entry>30</entry><entry>int16_t</entry><entry>mag_z</entry><entry>Z field strength (through)</entry>
 328             </row>
 329             <row>
 330               <entry>32</entry>
 331             </row>
 332           </tbody>
 333         </tgroup>
 334       </table>
 335       <table frame='all'>
 336         <title>TeleMega Kalman and Voltage Data Packet Contents</title>
 337         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 338           <colspec align='center' colwidth='*' colname='Offset'/>
 339           <colspec align='center' colwidth='3*' colname='Data Type'/>
 340           <colspec align='left' colwidth='3*' colname='Name'/>
 341           <colspec align='left' colwidth='9*' colname='Description'/>
 342           <thead>
 343             <row>
 344               <entry align='center'>Offset</entry>
 345               <entry align='center'>Data Type</entry>
 346               <entry align='center'>Name</entry>
 347               <entry align='center'>Description</entry>
 348             </row>
 349           </thead>
 350           <tbody>
 351             <row>
 352               <entry>5</entry><entry>uint8_t</entry><entry>state</entry><entry>Flight state</entry>
 353             </row>
 354             <row>
 355               <entry>6</entry><entry>int16_t</entry><entry>v_batt</entry><entry>battery voltage</entry>
 356             </row>
 357             <row>
 358               <entry>8</entry><entry>int16_t</entry><entry>v_pyro</entry><entry>pyro battery voltage</entry>
 359             </row>
 360             <row>
 361               <entry>10</entry><entry>int8_t[6]</entry><entry>sense</entry><entry>pyro continuity sense</entry>
 362             </row>
 363             <row>
 364               <entry>16</entry><entry>int32_t</entry><entry>ground_pres</entry><entry>Average barometer reading on ground</entry>
 365             </row>
 366             <row>
 367               <entry>20</entry><entry>int16_t</entry><entry>ground_accel</entry><entry>Average accelerometer reading on ground</entry>
 368             </row>
 369             <row>
 370               <entry>22</entry><entry>int16_t</entry><entry>accel_plus_g</entry><entry>Accel calibration at +1g</entry>
 371             </row>
 372             <row>
 373               <entry>24</entry><entry>int16_t</entry><entry>accel_minus_g</entry><entry>Accel calibration at -1g</entry>
 374             </row>
 375             <row>
 376               <entry>26</entry><entry>int16_t</entry><entry>acceleration</entry><entry>m/s² * 16</entry>
 377             </row>
 378             <row>
 379               <entry>28</entry><entry>int16_t</entry><entry>speed</entry><entry>m/s * 16</entry>
 380             </row>
 381             <row>
 382               <entry>30</entry><entry>int16_t</entry><entry>height</entry><entry>m</entry>
 383             </row>
 384             <row>
 385               <entry>32</entry>
 386             </row>
 387           </tbody>
 388         </tgroup>
 389       </table>
 390     </section>
 391     <section>
 392       <title>TeleMetrum v2 Sensor  Data</title>
 393       <informaltable frame='none' label='' tocentry='0'>
 394         <tgroup cols='2' align='center' colsep='1' rowsep='1'>
 395           <colspec align='center' colwidth='*' colname='Offset'/>
 396           <colspec align='left' colwidth='3*' colname='Description'/>
 397           <thead>
 398             <row>
 399               <entry>Type</entry>
 400               <entry>Description</entry>
 401             </row>
 402           </thead>
 403           <tbody>
 404             <row>
 405               <entry>0x0A</entry>
 406               <entry>TeleMetrum v2 Sensor Data</entry>
 407             </row>
 408             <row>
 409               <entry>0x0B</entry>
 410               <entry>TeleMetrum v2 Calibration Data</entry>
 411             </row>
 412           </tbody>
 413         </tgroup>
 414       </informaltable>
 415       <para>
 416         TeleMetrum v2 has higher resolution barometric data than
 417         TeleMetrum v1, and so the constant calibration data is
 418         split out into a separate packet.
 419       </para>
 420       <para>
 421         TeleMetrum v2 Sensor Data packets are transmitted once per second on the
 422         ground, 10 times per second during ascent and once per second
 423         during descent and landing
 424       </para>
 425       <para>
 426         TeleMetrum v2 Calibration Data packets are always transmitted once per second.
 427       </para>
 428       <table frame='all'>
 429         <title>TeleMetrum v2 Sensor Packet Contents</title>
 430         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 431           <colspec align='center' colwidth='*' colname='Offset'/>
 432           <colspec align='center' colwidth='3*' colname='Data Type'/>
 433           <colspec align='left' colwidth='3*' colname='Name'/>
 434           <colspec align='left' colwidth='9*' colname='Description'/>
 435           <thead>
 436             <row>
 437               <entry align='center'>Offset</entry>
 438               <entry align='center'>Data Type</entry>
 439               <entry align='center'>Name</entry>
 440               <entry align='center'>Description</entry>
 441             </row>
 442           </thead>
 443           <tbody>
 444             <row>
 445               <entry>5</entry><entry>uint8_t</entry><entry>state</entry><entry>Flight state</entry>
 446             </row>
 447             <row>
 448               <entry>6</entry><entry>int16_t</entry><entry>accel</entry><entry>accelerometer</entry>
 449             </row>
 450             <row>
 451               <entry>8</entry><entry>int32_t</entry><entry>pres</entry><entry>pressure sensor (Pa * 10)</entry>
 452             </row>
 453             <row>
 454               <entry>12</entry><entry>int16_t</entry><entry>temp</entry><entry>temperature sensor (°C * 100)</entry>
 455             </row>
 456
 457             <row>
 458               <entry>14</entry><entry>int16_t</entry><entry>acceleration</entry><entry>m/s² * 16</entry>
 459             </row>
 460             <row>
 461               <entry>16</entry><entry>int16_t</entry><entry>speed</entry><entry>m/s * 16</entry>
 462             </row>
 463             <row>
 464               <entry>18</entry><entry>int16_t</entry><entry>height</entry><entry>m</entry>
 465             </row>
 466
 467             <row>
 468               <entry>20</entry><entry>int16_t</entry><entry>v_batt</entry><entry>battery voltage</entry>
 469             </row>
 470             <row>
 471               <entry>22</entry><entry>int16_t</entry><entry>sense_d</entry><entry>drogue continuity sense</entry>
 472             </row>
 473             <row>
 474               <entry>24</entry><entry>int16_t</entry><entry>sense_m</entry><entry>main continuity sense</entry>
 475             </row>
 476             <row>
 477               <entry>26</entry><entry>pad[6]</entry><entry>pad bytes</entry><entry></entry>
 478             </row>
 479             <row>
 480               <entry>32</entry>
 481             </row>
 482           </tbody>
 483         </tgroup>
 484       </table>
 485       <table frame='all'>
 486         <title>TeleMetrum v2 Calibration Data Packet Contents</title>
 487         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 488           <colspec align='center' colwidth='*' colname='Offset'/>
 489           <colspec align='center' colwidth='3*' colname='Data Type'/>
 490           <colspec align='left' colwidth='3*' colname='Name'/>
 491           <colspec align='left' colwidth='9*' colname='Description'/>
 492           <thead>
 493             <row>
 494               <entry align='center'>Offset</entry>
 495               <entry align='center'>Data Type</entry>
 496               <entry align='center'>Name</entry>
 497               <entry align='center'>Description</entry>
 498             </row>
 499           </thead>
 500           <tbody>
 501             <row>
 502               <entry>5</entry><entry>pad[3]</entry><entry>pad bytes</entry><entry></entry>
 503             </row>
 504             <row>
 505               <entry>8</entry><entry>int32_t</entry><entry>ground_pres</entry><entry>Average barometer reading on ground</entry>
 506             </row>
 507             <row>
 508               <entry>12</entry><entry>int16_t</entry><entry>ground_accel</entry><entry>Average accelerometer reading on ground</entry>
 509             </row>
 510             <row>
 511               <entry>14</entry><entry>int16_t</entry><entry>accel_plus_g</entry><entry>Accel calibration at +1g</entry>
 512             </row>
 513             <row>
 514               <entry>16</entry><entry>int16_t</entry><entry>accel_minus_g</entry><entry>Accel calibration at -1g</entry>
 515             </row>
 516             <row>
 517               <entry>18</entry><entry>pad[14]</entry><entry>pad bytes</entry><entry></entry>
 518             </row>
 519             <row>
 520               <entry>32</entry>
 521             </row>
 522           </tbody>
 523         </tgroup>
 524       </table>
 525     </section>
 526     <section>
 527       <title>Configuration Data</title>
 528       <informaltable frame='none' label='' tocentry='0'>
 529         <tgroup cols='2' align='center' colsep='1' rowsep='1'>
 530           <colspec align='center' colwidth='*' colname='Offset'/>
 531           <colspec align='left' colwidth='3*' colname='Description'/>
 532           <thead>
 533             <row>
 534               <entry>Type</entry>
 535               <entry>Description</entry>
 536             </row>
 537           </thead>
 538           <tbody>
 539             <row>
 540               <entry>0x04</entry>
 541               <entry>Configuration Data</entry>
 542             </row>
 543           </tbody>
 544         </tgroup>
 545       </informaltable>
 546       <para>
 547         This provides a description of the software installed on the
 548         flight computer as well as any user-specified configuration data.
 549       </para>
 550       <para>
 551         Configuration data packets are transmitted once per second
 552         during all phases of the flight
 553       </para>
 554       <table frame='all'>
 555         <title>Sensor Packet Contents</title>
 556         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 557           <colspec align='center' colwidth='*' colname='Offset'/>
 558           <colspec align='center' colwidth='3*' colname='Data Type'/>
 559           <colspec align='left' colwidth='3*' colname='Name'/>
 560           <colspec align='left' colwidth='9*' colname='Description'/>
 561           <thead>
 562             <row>
 563               <entry align='center'>Offset</entry>
 564               <entry align='center'>Data Type</entry>
 565               <entry align='center'>Name</entry>
 566               <entry align='center'>Description</entry>
 567             </row>
 568           </thead>
 569           <tbody>
 570             <row>
 571               <entry>5</entry><entry>uint8_t</entry><entry>type</entry><entry>Device type</entry>
 572             </row>
 573             <row>
 574               <entry>6</entry><entry>uint16_t</entry><entry>flight</entry><entry>Flight number</entry>
 575             </row>
 576             <row>
 577               <entry>8</entry><entry>uint8_t</entry><entry>config_major</entry><entry>Config major version</entry>
 578             </row>
 579             <row>
 580               <entry>9</entry><entry>uint8_t</entry><entry>config_minor</entry><entry>Config minor version</entry>
 581             </row>
 582             <row>
 583               <entry>10</entry><entry>uint16_t</entry><entry>apogee_delay</entry>
 584               <entry>Apogee deploy delay in seconds</entry>
 585             </row>
 586             <row>
 587               <entry>12</entry><entry>uint16_t</entry><entry>main_deploy</entry><entry>Main deploy alt in meters</entry>
 588             </row>
 589             <row>
 590               <entry>14</entry><entry>uint16_t</entry><entry>flight_log_max</entry>
 591               <entry>Maximum flight log size (kB)</entry>
 592             </row>
 593             <row>
 594               <entry>16</entry><entry>char</entry><entry>callsign[8]</entry><entry>Radio operator identifier</entry>
 595             </row>
 596             <row>
 597               <entry>24</entry><entry>char</entry><entry>version[8]</entry><entry>Software version identifier</entry>
 598             </row>
 599             <row>
 600               <entry>32</entry>
 601             </row>
 602           </tbody>
 603         </tgroup>
 604       </table>
 605     </section>
 606     <section>
 607       <title>GPS Location</title>
 608       <informaltable frame='none' label='' tocentry='0'>
 609         <tgroup cols='2' align='center' colsep='1' rowsep='1'>
 610           <colspec align='center' colwidth='*' colname='Offset'/>
 611           <colspec align='left' colwidth='3*' colname='Description'/>
 612           <thead>
 613             <row>
 614               <entry>Type</entry>
 615               <entry>Description</entry>
 616             </row>
 617           </thead>
 618           <tbody>
 619             <row>
 620               <entry>0x05</entry>
 621               <entry>GPS Location</entry>
 622             </row>
 623           </tbody>
 624         </tgroup>
 625       </informaltable>
 626       <para>
 627         This packet provides all of the information available from the
 628         GPS receiver—position, time, speed and precision
 629         estimates.
 630       </para>
 631       <para>
 632         GPS Location packets are transmitted once per second during
 633         all phases of the flight
 634       </para>
 635       <table frame='all'>
 636         <title>GPS Location Packet Contents</title>
 637         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 638           <colspec align='center' colwidth='*' colname='Offset'/>
 639           <colspec align='center' colwidth='3*' colname='Data Type'/>
 640           <colspec align='left' colwidth='3*' colname='Name'/>
 641           <colspec align='left' colwidth='9*' colname='Description'/>
 642           <thead>
 643             <row>
 644               <entry align='center'>Offset</entry>
 645               <entry align='center'>Data Type</entry>
 646               <entry align='center'>Name</entry>
 647               <entry align='center'>Description</entry>
 648             </row>
 649           </thead>
 650           <tbody>
 651             <row>
 652               <entry>5</entry><entry>uint8_t</entry><entry>flags</entry>
 653               <entry>See GPS Flags table below</entry>
 654             </row>
 655             <row>
 656               <entry>6</entry><entry>int16_t</entry><entry>altitude</entry><entry>m</entry>
 657             </row>
 658             <row>
 659               <entry>8</entry><entry>int32_t</entry><entry>latitude</entry><entry>degrees * 10<superscript>7</superscript></entry>
 660             </row>
 661             <row>
 662               <entry>12</entry><entry>int32_t</entry><entry>longitude</entry><entry>degrees * 10<superscript>7</superscript></entry>
 663             </row>
 664             <row>
 665               <entry>16</entry><entry>uint8_t</entry><entry>year</entry>
 666             </row>
 667             <row>
 668               <entry>17</entry><entry>uint8_t</entry><entry>month</entry>
 669             </row>
 670             <row>
 671               <entry>18</entry><entry>uint8_t</entry><entry>day</entry>
 672             </row>
 673             <row>
 674               <entry>19</entry><entry>uint8_t</entry><entry>hour</entry>
 675             </row>
 676             <row>
 677               <entry>20</entry><entry>uint8_t</entry><entry>minute</entry>
 678             </row>
 679             <row>
 680               <entry>21</entry><entry>uint8_t</entry><entry>second</entry>
 681             </row>
 682             <row>
 683               <entry>22</entry><entry>uint8_t</entry><entry>pdop</entry><entry>* 5</entry>
 684             </row>
 685             <row>
 686               <entry>23</entry><entry>uint8_t</entry><entry>hdop</entry><entry>* 5</entry>
 687             </row>
 688             <row>
 689               <entry>24</entry><entry>uint8_t</entry><entry>vdop</entry><entry>* 5</entry>
 690             </row>
 691             <row>
 692               <entry>25</entry><entry>uint8_t</entry><entry>mode</entry>
 693               <entry>See GPS Mode table below</entry>
 694             </row>
 695             <row>
 696               <entry>26</entry><entry>uint16_t</entry><entry>ground_speed</entry><entry>cm/s</entry>
 697             </row>
 698             <row>
 699               <entry>28</entry><entry>int16_t</entry><entry>climb_rate</entry><entry>cm/s</entry>
 700             </row>
 701             <row>
 702               <entry>30</entry><entry>uint8_t</entry><entry>course</entry><entry>/ 2</entry>
 703             </row>
 704             <row>
 705               <entry>31</entry><entry>uint8_t</entry><entry>unused[1]</entry>
 706             </row>
 707             <row>
 708               <entry>32</entry>
 709             </row>
 710           </tbody>
 711         </tgroup>
 712       </table>
 713       <para>
 714         Packed into a one byte field are status flags and the count of
 715         satellites used to compute the position fix. Note that this
 716         number may be lower than the number of satellites being
 717         tracked; the receiver will not use information from satellites
 718         with weak signals or which are close enough to the horizon to
 719         have significantly degraded position accuracy.
 720       </para>
 721       <table frame='all'>
 722         <title>GPS Flags</title>
 723         <tgroup cols='3' colsep='1' rowsep='1'>
 724           <colspec align='center' colwidth='*' colname='bits'/>
 725           <colspec align='left' colwidth='2*' colname='name'/>
 726           <colspec align='left' colwidth='7*' colname='description'/>
 727           <thead>
 728             <row>
 729               <entry align='center'>Bits</entry>
 730               <entry align='center'>Name</entry>
 731               <entry align='center'>Description</entry>
 732             </row>
 733           </thead>
 734           <tbody>
 735             <row>
 736               <entry>0-3</entry>
 737               <entry>nsats</entry>
 738               <entry>Number of satellites in solution</entry>
 739             </row>
 740             <row>
 741               <entry>4</entry>
 742               <entry>valid</entry>
 743               <entry>GPS solution is valid</entry>
 744             </row>
 745             <row>
 746               <entry>5</entry>
 747               <entry>running</entry>
 748               <entry>GPS receiver is operational</entry>
 749             </row>
 750             <row>
 751               <entry>6</entry>
 752               <entry>date_valid</entry>
 753               <entry>Reported date is valid</entry>
 754             </row>
 755             <row>
 756               <entry>7</entry>
 757               <entry>course_valid</entry>
 758               <entry>ground speed, course and climb rates are valid</entry>
 759             </row>
 760           </tbody>
 761         </tgroup>
 762       </table>
 763       <para>
 764         Here are all of the valid GPS operational modes. Altus Metrum
 765         products will only ever report 'N' (not valid), 'A'
 766         (Autonomous) modes or 'E' (Estimated). The remaining modes
 767         are either testing modes or require additional data.
 768       </para>
 769       <table frame='all'>
 770         <title>GPS Mode</title>
 771         <tgroup cols='3' colsep='1' rowsep='1'>
 772           <colspec align='center' colwidth='*' colname='value'/>
 773           <colspec align='center' colwidth='3*' colname='name'/>
 774           <colspec align='left' colwidth='7*' colname='description'/>
 775           <thead>
 776             <row>
 777               <entry align='center'>Mode</entry>
 778               <entry align='center'>Name</entry>
 779               <entry align='center'>Decsription</entry>
 780             </row>
 781           </thead>
 782           <tbody>
 783             <row>
 784               <entry>N</entry>
 785               <entry>Not Valid</entry>
 786               <entry>All data are invalid</entry>
 787             </row>
 788             <row>
 789               <entry>A</entry>
 790               <entry>Autonomous mode</entry>
 791               <entry>Data are derived from satellite data</entry>
 792             </row>
 793             <row>
 794               <entry>D</entry>
 795               <entry>Differential Mode</entry>
 796               <entry>
 797                   Data are augmented with differential data from a
 798                   known ground station. The SkyTraq unit in TeleMetrum
 799                   does not support this mode
 800                 </entry>
 801             </row>
 802             <row>
 803               <entry>E</entry>
 804               <entry>Estimated</entry>
 805               <entry>
 806                   Data are estimated using dead reckoning from the
 807                   last known data
 808                 </entry>
 809             </row>
 810             <row>
 811               <entry>M</entry>
 812               <entry>Manual</entry>
 813               <entry>Data were entered manually</entry>
 814             </row>
 815             <row>
 816               <entry>S</entry>
 817               <entry>Simulated</entry>
 818               <entry>GPS receiver testing mode</entry>
 819             </row>
 820           </tbody>
 821         </tgroup>
 822       </table>
 823     </section>
 824     <section>
 825       <title>GPS Satellite Data</title>
 826       <informaltable frame='none' label='' tocentry='0'>
 827         <tgroup cols='2' align='center' colsep='1' rowsep='1'>
 828           <colspec align='center' colwidth='*' colname='Offset'/>
 829           <colspec align='left' colwidth='3*' colname='Description'/>
 830           <thead>
 831             <row>
 832               <entry>Type</entry>
 833               <entry>Description</entry>
 834             </row>
 835           </thead>
 836           <tbody>
 837             <row>
 838               <entry>0x06</entry>
 839               <entry>GPS Satellite Data</entry>
 840             </row>
 841           </tbody>
 842         </tgroup>
 843       </informaltable>
 844       <para>
 845         This packet provides space vehicle identifiers and signal
 846         quality information in the form of a C/N1 number for up to 12
 847         satellites. The order of the svids is not specified.
 848       </para>
 849       <para>
 850         GPS Satellite data are transmitted once per second during all
 851         phases of the flight.
 852       </para>
 853       <table frame='all'>
 854         <title>GPS Satellite Data Contents</title>
 855         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 856           <colspec align='right' colwidth='*' colname='Offset'/>
 857           <colspec align='center' colwidth='3*' colname='Data Type'/>
 858           <colspec align='left' colwidth='3*' colname='Name'/>
 859           <colspec align='left' colwidth='9*' colname='Description'/>
 860           <thead>
 861             <row>
 862               <entry align='center'>Offset</entry>
 863               <entry align='center'>Data Type</entry>
 864               <entry align='center'>Name</entry>
 865               <entry align='center'>Description</entry>
 866             </row>
 867           </thead>
 868           <tbody>
 869             <row>
 870               <entry>5</entry><entry>uint8_t</entry><entry>channels</entry>
 871               <entry>Number of reported satellite information</entry>
 872             </row>
 873             <row>
 874               <entry>6</entry><entry>sat_info_t</entry><entry>sats[12]</entry>
 875               <entry>See Per-Satellite data table below</entry>
 876             </row>
 877             <row>
 878               <entry>30</entry><entry>uint8_t</entry><entry>unused[2]</entry>
 879             </row>
 880             <row>
 881               <entry>32</entry>
 882             </row>
 883           </tbody>
 884         </tgroup>
 885       </table>
 886       <table frame='all'>
 887         <title>GPS Per-Satellite data (sat_info_t)</title>
 888         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 889           <colspec align='right' colwidth='*' colname='Offset'/>
 890           <colspec align='center' colwidth='3*' colname='Data Type'/>
 891           <colspec align='left' colwidth='3*' colname='Name'/>
 892           <colspec align='left' colwidth='9*' colname='Description'/>
 893           <thead>
 894             <row>
 895               <entry align='center'>Offset</entry>
 896               <entry align='center'>Data Type</entry>
 897               <entry align='center'>Name</entry>
 898               <entry align='center'>Description</entry>
 899             </row>
 900           </thead>
 901           <tbody>
 902             <row>
 903               <entry>0</entry><entry>uint8_t</entry><entry>svid</entry>
 904               <entry>Space Vehicle Identifier</entry>
 905             </row>
 906             <row>
 907               <entry>1</entry><entry>uint8_t</entry><entry>c_n_1</entry>
 908               <entry>C/N1 signal quality indicator</entry>
 909             </row>
 910             <row>
 911               <entry>2</entry>
 912             </row>
 913           </tbody>
 914         </tgroup>
 915       </table>
 916     </section>
 917     <section>
 918       <title>Companion Data Data</title>
 919       <informaltable frame='none' label='' tocentry='0'>
 920         <tgroup cols='2' align='center' colsep='1' rowsep='1'>
 921           <colspec align='center' colwidth='*' colname='Offset'/>
 922           <colspec align='left' colwidth='3*' colname='Description'/>
 923           <thead>
 924             <row>
 925               <entry>Type</entry>
 926               <entry>Description</entry>
 927             </row>
 928           </thead>
 929           <tbody>
 930             <row>
 931               <entry>0x07</entry>
 932               <entry>Companion Data Data</entry>
 933             </row>
 934           </tbody>
 935         </tgroup>
 936       </informaltable>
 937       <para>
 938         When a companion board is attached to TeleMega or TeleMetrum,
 939         it can provide telemetry data to be included in the
 940         downlink. The companion board can provide up to 12 16-bit data
 941         values.
 942       </para>
 943       <para>
 944         The companion board itself specifies the transmission rate. On
 945         the ground and during descent, that rate is limited to one
 946         packet per second. During ascent, that rate is limited to 10
 947         packets per second.
 948       </para>
 949       <table frame='all'>
 950         <title>Companion Data Contents</title>
 951         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 952           <colspec align='right' colwidth='*' colname='Offset'/>
 953           <colspec align='center' colwidth='3*' colname='Data Type'/>
 954           <colspec align='left' colwidth='3*' colname='Name'/>
 955           <colspec align='left' colwidth='9*' colname='Description'/>
 956           <thead>
 957             <row>
 958               <entry align='center'>Offset</entry>
 959               <entry align='center'>Data Type</entry>
 960               <entry align='center'>Name</entry>
 961               <entry align='center'>Description</entry>
 962             </row>
 963           </thead>
 964           <tbody>
 965             <row>
 966               <entry>5</entry><entry>uint8_t</entry><entry>board_id</entry>
 967               <entry>Type of companion board attached</entry>
 968             </row>
 969             <row>
 970               <entry>6</entry><entry>uint8_t</entry><entry>update_period</entry>
 971               <entry>How often telemetry is sent, in 1/100ths of a second</entry>
 972             </row>
 973             <row>
 974               <entry>7</entry><entry>uint8_t</entry><entry>channels</entry>
 975               <entry>Number of data channels supplied</entry>
 976             </row>
 977             <row>
 978               <entry>8</entry><entry>uint16_t[12]</entry><entry>companion_data</entry>
 979               <entry>Up to 12 channels of 16-bit companion data</entry>
 980             </row>
 981             <row>
 982               <entry>32</entry>
 983             </row>
 984           </tbody>
 985         </tgroup>
 986       </table>
 987     </section>
 988   </section>
 989   <section>
 990     <title>Data Transmission</title>
 991     <para>
 992       Altus Metrum devices use Texas Instruments sub-GHz digital radio
 993       products. Ground stations use parts with HW FEC while some
 994       flight computers perform FEC in software. TeleGPS is
 995       transmit-only.
 996     </para>
 997     <table>
 998       <title>Altus Metrum Radio Parts</title>
 999       <tgroup cols='3'>
1000         <colspec align="center" colwidth="*" colname="Part Number"/>
1001         <colspec align="center" colwidth="*" colname="Description"/>
1002         <colspec align="left" colwidth="*" colname="Used in"/>
1003         <thead>
1004           <row>
1005             <entry align="center">Part Number</entry>
1006             <entry align="center">Description</entry>
1007             <entry align="center">Used in</entry>
1008           </row>
1009         </thead>
1010         <tbody>
1011           <row>
1012             <entry>CC1111</entry><entry>10mW transceiver with integrated SoC</entry>
1013             <entry>TeleDongle v0.2, TeleBT v1.0, TeleMetrum v1.x, TeleMini</entry>
1014           </row>
1015           <row>
1016             <entry>CC1120</entry><entry>35mW transceiver with SW FEC</entry>
1017             <entry>TeleMetrum v2, TeleMega</entry>
1018           </row>
1019           <row>
1020             <entry>CC1200</entry><entry>35mW transceiver with HW FEC</entry>
1021             <entry>TeleDongle v3.0, TeleBT v3.0</entry>
1022           </row>
1023           <row>
1024             <entry>CC115L</entry><entry>14mW transmitter with SW FEC</entry>
1025             <entry>TeleGPS</entry>
1026           </row>
1027         </tbody>
1028       </tgroup>
1029     </table>
1030     <section>
1031       <title>Modulation Scheme</title>
1032       <para>
1033         Texas Instruments provides a tool for computing modulation
1034         parameters given a desired modulation format and basic bit
1035         rate.
1036
1037         While we might like to use something with better low-signal
1038         performance like BPSK, the radios we use don't support that,
1039         but do support Gaussian frequency shift keying (GFSK). Regular
1040         frequency shift keying (FSK) encodes the signal by switching
1041         the carrier between two frequencies. The Gaussian version is
1042         essentially the same, but the shift between frequencies gently
1043         follows a gaussian curve, rather than switching
1044         immediately. This tames the bandwidth of the signal without
1045         affecting the ability to transmit data.
1046
1047         For AltOS, there are three available bit rates, 38.4kBaud,
1048         9.6kBaud and 2.4kBaud resulting in the following signal
1049         parmeters:
1050
1051       </para>
1052       <table>
1053         <title>Modulation Scheme</title>
1054         <tgroup cols='3'>
1055           <colspec align="center" colwidth="*" colname="rate"/>
1056           <colspec align="center" colwidth="*" colname="deviation"/>
1057           <colspec align="center" colwidth="*" colname="bandwidth"/>
1058           <thead>
1059             <row>
1060               <entry align='center'>Rate</entry>
1061               <entry align='center'>Deviation</entry>
1062               <entry align='center'>Receiver Bandwidth</entry>
1063             </row>
1064           </thead>
1065           <tbody>
1066             <row>
1067               <entry>38.4kBaud</entry>
1068               <entry>20.5kHz</entry>
1069               <entry>100kHz</entry>
1070             </row>
1071             <row>
1072               <entry>9.6kBaud</entry>
1073               <entry>5.125kHz</entry>
1074               <entry>25kHz</entry>
1075             </row>
1076             <row>
1077               <entry>2.4kBaud</entry>
1078               <entry>1.5kHz</entry>
1079               <entry>5kHz</entry>
1080             </row>
1081           </tbody>
1082         </tgroup>
1083       </table>
1084     </section>
1085     <section>
1086       <title>Error Correction</title>
1087       <para>
1088         The cc1111 and cc1200 provide forward error correction in
1089         hardware; on the cc1120 and cc115l that's done in
1090         software. AltOS uses this to improve reception of weak
1091         signals. As it's a rate 1/2 encoding, each bit of data takes
1092         two bits when transmitted, so the effective data rate is half
1093         of the raw transmitted bit rate.
1094       </para>
1095       <table>
1096         <title>Error Correction</title>
1097         <tgroup cols='3'>
1098           <colspec align="center" colwidth="*" colname="parameter"/>
1099           <colspec align="center" colwidth="*" colname="value"/>
1100           <colspec align="center" colwidth="*" colname="description"/>
1101           <thead>
1102             <row>
1103               <entry align='center'>Parameter</entry>
1104               <entry align='center'>Value</entry>
1105               <entry align='center'>Description</entry>
1106             </row>
1107           </thead>
1108           <tbody>
1109             <row>
1110               <entry>Error Correction</entry>
1111               <entry>Convolutional coding</entry>
1112               <entry>1/2 rate, constraint length m=4</entry>
1113             </row>
1114             <row>
1115               <entry>Interleaving</entry>
1116               <entry>4 x 4</entry>
1117               <entry>Reduce effect of noise burst</entry>
1118             </row>
1119             <row>
1120               <entry>Data Whitening</entry>
1121               <entry>XOR with 9-bit PNR</entry>
1122               <entry>Rotate right with bit 8 = bit 0 xor bit 5, initial
1123               value 111111111</entry>
1124             </row>
1125           </tbody>
1126         </tgroup>
1127       </table>
1128     </section>
1129   </section>
1130   <section>
1131     <title>TeleDongle packet format</title>
1132     <para>
1133       TeleDongle does not do any interpretation of the packet data,
1134       instead it is configured to receive packets of a specified
1135       length (32 bytes in this case). For each received packet,
1136       TeleDongle produces a single line of text. This line starts with
1137       the string "TELEM " and is followed by a list of hexadecimal
1138       encoded bytes.
1139     </para>
1140     <programlisting>TELEM 224f01080b05765e00701f1a1bbeb8d7b60b070605140c000600000000000000003fa988</programlisting>
1141     <para>
1142       The hexadecimal encoded string of bytes contains a length byte,
1143       the packet data, two bytes added by the cc1111 radio receiver
1144       hardware and finally a checksum so that the host software can
1145       validate that the line was transmitted without any errors.
1146     </para>
1147     <table>
1148       <title>Packet Format</title>
1149       <tgroup cols='4'>
1150         <colspec align="center" colwidth="2*" colname="offset"/>
1151         <colspec align="center" colwidth="*" colname="name"/>
1152         <colspec align="center" colwidth="*" colname="value"/>
1153         <colspec align="center" colwidth="5*" colname="description"/>
1154         <thead>
1155           <row>
1156             <entry align='center'>Offset</entry>
1157             <entry align='center'>Name</entry>
1158             <entry align='center'>Example</entry>
1159             <entry align='center'>Description</entry>
1160           </row>
1161         </thead>
1162         <tbody>
1163           <row>
1164             <entry>0</entry>
1165             <entry>length</entry>
1166             <entry>22</entry>
1167             <entry>Total length of data bytes in the line. Note that
1168             this includes the added RSSI and status bytes</entry>
1169           </row>
1170           <row>
1171             <entry>1 ·· length-3</entry>
1172             <entry>packet</entry>
1173             <entry>4f ·· 00</entry>
1174             <entry>Bytes of actual packet data</entry>
1175           </row>
1176           <row>
1177             <entry>length-2</entry>
1178             <entry>rssi</entry>
1179             <entry>3f</entry>
1180             <entry>Received signal strength. dBm = rssi / 2 - 74</entry>
1181           </row>
1182           <row>
1183             <entry>length-1</entry>
1184             <entry>lqi</entry>
1185             <entry>a9</entry>
1186             <entry>Link Quality Indicator and CRC status. Bit 7
1187             is set when the CRC is correct</entry>
1188           </row>
1189           <row>
1190             <entry>length</entry>
1191             <entry>checksum</entry>
1192             <entry>88</entry>
1193             <entry>(0x5a + sum(bytes 1 ·· length-1)) % 256</entry>
1194           </row>
1195         </tbody>
1196       </tgroup>
1197     </table>
1198   </section>
1199   <section>
1200     <title>History and Motivation</title>
1201     <para>
1202       The original AltoOS telemetry mechanism encoded everything
1203       available piece of information on the TeleMetrum hardware into a
1204       single unified packet. Initially, the packets contained very
1205       little data—some raw sensor readings along with the current GPS
1206       coordinates when a GPS receiver was connected. Over time, the
1207       amount of data grew to include sensor calibration data, GPS
1208       satellite information and a host of internal state information
1209       designed to help diagnose flight failures in case of a loss of
1210       the on-board flight data.
1211     </para>
1212     <para>
1213       Because every packet contained all of the data, packets were
1214       huge—95 bytes long. Much of the information was also specific to
1215       the TeleMetrum hardware. With the introduction of the TeleMini
1216       flight computer, most of the data contained in the telemetry
1217       packets was unavailable. Initially, a shorter, but still
1218       comprehensive packet was implemented. This required that the
1219       ground station be pre-configured as to which kind of packet to
1220       expect.
1221     </para>
1222     <para>
1223       The development of several companion boards also made the
1224       shortcomings evident—each companion board would want to include
1225       telemetry data in the radio link; with the original design, the
1226       packet would have to hold the new data as well, requiring
1227       additional TeleMetrum and ground station changes.
1228     </para>
1229   </section>
1230 </article>