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

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE book 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>History and Motivation</title>
  36     <para>
  37       The original AltoOS telemetry mechanism encoded everything
  38       available piece of information on the TeleMetrum hardware into a
  39       single unified packet. Initially, the packets contained very
  40       little data—some raw sensor readings along with the current GPS
  41       coordinates when a GPS receiver was connected. Over time, the
  42       amount of data grew to include sensor calibration data, GPS
  43       satellite information and a host of internal state information
  44       designed to help diagnose flight failures in case of a loss of
  45       the on-board flight data.
  46     </para>
  47     <para>
  48       Because every packet contained all of the data, packets were
  49       huge—95 bytes long. Much of the information was also specific to
  50       the TeleMetrum hardware. With the introduction of the TeleMini
  51       flight computer, most of the data contained in the telemetry
  52       packets was unavailable. Initially, a shorter, but still
  53       comprehensive packet was implemented. This required that the
  54       ground station be pre-configured as to which kind of packet to
  55       expect.
  56     </para>
  57     <para>
  58       The development of several companion boards also made the
  59       shortcomings evident—each companion board would want to include
  60       telemetry data in the radio link; with the original design, the
  61       packet would have to hold the new data as well, requiring
  62       additional TeleMetrum and ground station changes.
  63     </para>
  64   </section>
  65   <section>
  66     <title>Packet Format Design</title>
  67     <para>
  68       AltOS telemetry data is split into multiple different packets,
  69       all the same size, but each includs an identifier so that the
  70       ground station can distinguish among different types. A single
  71       flight board will transmit multiple packet types, each type on a
  72       different schedule. The ground software need look for only a
  73       single packet size, and then decode the information within the
  74       packet and merge data from multiple packets to construct the
  75       full flight computer state.
  76     </para>
  77     <para>
  78       Each AltOS packet is 32 bytes long. This size was chosen based
  79       on the known telemetry data requirements. The power of two size
  80       allows them to be stored easily in flash memory without having
  81       them split across blocks or leaving gaps at the end.
  82     </para>
  83     <para>
  84       All packet types start with a five byte header which encodes the
  85       device serial number, device clock value and the packet
  86       type. The remaining 27 bytes encode type-specific data.
  87     </para>
  88   </section>
  89   <section>
  90     <title>Packet Formats</title>
  91     This section first defines the packet header common to all packets
  92     and then the per-packet data layout.
  93     <section>
  94       <title>Packet Header</title>
  95       <table frame='all'>
  96         <title>Telemetry Packet Header</title>
  97         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
  98           <colspec align='right' colwidth='*' colname='Offset'/>
  99           <colspec align='center' colwidth='3*' colname='Data Type'/>
 100           <colspec align='left' colwidth='3*' colname='Name'/>
 101           <colspec align='left' colwidth='9*' colname='Description'/>
 102           <thead>
 103             <row>
 104               <entry align='center'>Offset</entry>
 105               <entry align='center'>Data Type</entry>
 106               <entry align='center'>Name</entry>
 107               <entry align='center'>Description</entry>
 108             </row>
 109           </thead>
 110           <tbody>
 111             <row>
 112               <entry>0</entry>
 113               <entry>uint16_t</entry>
 114               <entry>serial</entry>
 115               <entry>Device serial Number</entry>
 116             </row>
 117             <row>
 118               <entry>2</entry>
 119               <entry>uint16_t</entry>
 120               <entry>tick</entry>
 121               <entry>Device time in 100ths of a second</entry>
 122             </row>
 123             <row>
 124               <entry>4</entry>
 125               <entry>uint8_t</entry>
 126               <entry>type</entry>
 127               <entry>Packet type</entry>
 128             </row>
 129             <row>
 130               <entry>5</entry>
 131             </row>
 132           </tbody>
 133         </tgroup>
 134       </table>
 135       <para>
 136       Each packet starts with these five bytes which serve to identify
 137       which device has transmitted the packet, when it was transmitted
 138       and what the rest of the packet contains.
 139       </para>
 140     </section>
 141     <section>
 142       <title>Sensor Data</title>
 143       <informaltable frame='none' label='' tocentry='0'>
 144         <tgroup cols='2' align='center' colsep='1' rowsep='1'>
 145           <colspec align='center' colwidth='*' colname='Offset'/>
 146           <colspec align='left' colwidth='3*' colname='Description'/>
 147           <thead>
 148             <row>
 149               <entry>Type</entry>
 150               <entry>Description</entry>
 151             </row>
 152           </thead>
 153           <tbody>
 154             <row>
 155               <entry>0x01</entry>
 156               <entry>TeleMetrum Sensor Data</entry>
 157             </row>
 158             <row>
 159               <entry>0x02</entry>
 160               <entry>TeleMini Sensor Data</entry>
 161             </row>
 162             <row>
 163               <entry>0x03</entry>
 164               <entry>TeleNano Sensor Data</entry>
 165             </row>
 166           </tbody>
 167         </tgroup>
 168       </informaltable>
 169       <para>
 170         TeleMetrum, TeleMini and TeleNano share this same packet
 171         format for sensor data. Each uses a distinct packet type so
 172         that the receiver knows which data values are valid and which
 173         are undefined.
 174       </para>
 175       <table frame='all'>
 176         <title>Sensor Packet Contents</title>
 177         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 178           <colspec align='right' colwidth='*' colname='Offset'/>
 179           <colspec align='center' colwidth='3*' colname='Data Type'/>
 180           <colspec align='left' colwidth='3*' colname='Name'/>
 181           <colspec align='left' colwidth='9*' colname='Description'/>
 182           <thead>
 183             <row>
 184               <entry align='center'>Offset</entry>
 185               <entry align='center'>Data Type</entry>
 186               <entry align='center'>Name</entry>
 187               <entry align='center'>Description</entry>
 188             </row>
 189           </thead>
 190           <tbody>
 191             <row>
 192               <entry>5</entry><entry>uint8_t</entry><entry>state</entry><entry>Flight state</entry>
 193             </row>
 194             <row>
 195               <entry>6</entry><entry>int16_t</entry><entry>accel</entry><entry>accelerometer (TM only)</entry>
 196             </row>
 197             <row>
 198               <entry>8</entry><entry>int16_t</entry><entry>pres</entry><entry>pressure sensor</entry>
 199             </row>
 200             <row>
 201               <entry>10</entry><entry>int16_t</entry><entry>temp</entry><entry>temperature sensor</entry>
 202             </row>
 203             <row>
 204               <entry>12</entry><entry>int16_t</entry><entry>v_batt</entry><entry>battery voltage</entry>
 205             </row>
 206             <row>
 207               <entry>14</entry><entry>int16_t</entry><entry>sense_d</entry><entry>drogue continuity sense (TM/Tm)</entry>
 208             </row>
 209             <row>
 210               <entry>16</entry><entry>int16_t</entry><entry>sense_m</entry><entry>main continuity sense (TM/Tm)</entry>
 211             </row>
 212             <row>
 213               <entry>18</entry><entry>int16_t</entry><entry>accel</entry><entry>m/s² * 16</entry>
 214             </row>
 215             <row>
 216               <entry>20</entry><entry>int16_t</entry><entry>speed</entry><entry>m/s * 16</entry>
 217             </row>
 218             <row>
 219               <entry>22</entry><entry>int16_t</entry><entry>height</entry><entry>m</entry>
 220             </row>
 221             <row>
 222               <entry>24</entry><entry>int16_t</entry><entry>ground_accel</entry><entry>TM</entry>
 223             </row>
 224             <row>
 225               <entry>26</entry><entry>int16_t</entry><entry>ground_pres</entry><entry>Average barometer reading on ground</entry>
 226             </row>
 227             <row>
 228               <entry>28</entry><entry>int16_t</entry><entry>accel_plus_g</entry><entry>TM</entry>
 229             </row>
 230             <row>
 231               <entry>30</entry><entry>int16_t</entry><entry>accel_minus_g</entry><entry>TM</entry>
 232             </row>
 233             <row>
 234               <entry>32</entry>
 235             </row>
 236           </tbody>
 237         </tgroup>
 238       </table>
 239     </section>
 240     <section>
 241       <title>Configuration Data</title>
 242       <informaltable frame='none' label='' tocentry='0'>
 243         <tgroup cols='2' align='center' colsep='1' rowsep='1'>
 244           <colspec align='center' colwidth='*' colname='Offset'/>
 245           <colspec align='left' colwidth='3*' colname='Description'/>
 246           <thead>
 247             <row>
 248               <entry>Type</entry>
 249               <entry>Description</entry>
 250             </row>
 251           </thead>
 252           <tbody>
 253             <row>
 254               <entry>0x04</entry>
 255               <entry>Configuration Data</entry>
 256             </row>
 257           </tbody>
 258         </tgroup>
 259       </informaltable>
 260       <table frame='all'>
 261         <title>Sensor Packet Contents</title>
 262         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 263           <colspec align='right' colwidth='*' colname='Offset'/>
 264           <colspec align='center' colwidth='3*' colname='Data Type'/>
 265           <colspec align='left' colwidth='3*' colname='Name'/>
 266           <colspec align='left' colwidth='9*' colname='Description'/>
 267           <thead>
 268             <row>
 269               <entry align='center'>Offset</entry>
 270               <entry align='center'>Data Type</entry>
 271               <entry align='center'>Name</entry>
 272               <entry align='center'>Description</entry>
 273             </row>
 274           </thead>
 275           <tbody>
 276             <row>
 277               <entry>5</entry><entry>uint8_t</entry><entry>type</entry><entry>Device type</entry>
 278             </row>
 279             <row>
 280               <entry>6</entry><entry>uint16_t</entry><entry>flight</entry><entry>Flight number</entry>
 281             </row>
 282             <row>
 283               <entry>8</entry><entry>uint8_t</entry><entry>config_major</entry><entry>Config major version</entry>
 284             </row>
 285             <row>
 286               <entry>9</entry><entry>uint8_t</entry><entry>config_minor</entry><entry>Config minor version</entry>
 287             </row>
 288             <row>
 289               <entry>10</entry><entry>uint16_t</entry><entry>main_deploy</entry><entry>Main deploy alt in meters</entry>
 290             </row>
 291             <row>
 292               <entry>12</entry><entry>uint32_t</entry><entry>flight_log_max</entry><entry>Maximum flight log size (B)</entry>
 293             </row>
 294             <row>
 295               <entry>16</entry><entry>char</entry><entry>callsign[8]</entry><entry>Radio operator identifier</entry>
 296             </row>
 297             <row>
 298               <entry>24</entry><entry>char</entry><entry>version[8]</entry><entry>Software version identifier</entry>
 299             </row>
 300             <row>
 301               <entry>32</entry>
 302             </row>
 303           </tbody>
 304         </tgroup>
 305       </table>
 306     </section>
 307     <section>
 308       <title>GPS Location</title>
 309       <informaltable frame='none' label='' tocentry='0'>
 310         <tgroup cols='2' align='center' colsep='1' rowsep='1'>
 311           <colspec align='center' colwidth='*' colname='Offset'/>
 312           <colspec align='left' colwidth='3*' colname='Description'/>
 313           <thead>
 314             <row>
 315               <entry>Type</entry>
 316               <entry>Description</entry>
 317             </row>
 318           </thead>
 319           <tbody>
 320             <row>
 321               <entry>0x05</entry>
 322               <entry>GPS Location</entry>
 323             </row>
 324           </tbody>
 325         </tgroup>
 326       </informaltable>
 327       <table frame='all'>
 328         <title>GPS Location Packet Contents</title>
 329         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 330           <colspec align='right' colwidth='*' colname='Offset'/>
 331           <colspec align='center' colwidth='3*' colname='Data Type'/>
 332           <colspec align='left' colwidth='3*' colname='Name'/>
 333           <colspec align='left' colwidth='9*' colname='Description'/>
 334           <thead>
 335             <row>
 336               <entry align='center'>Offset</entry>
 337               <entry align='center'>Data Type</entry>
 338               <entry align='center'>Name</entry>
 339               <entry align='center'>Description</entry>
 340             </row>
 341           </thead>
 342           <tbody>
 343             <row>
 344               <entry>5</entry><entry>uint8_t</entry><entry>flags</entry><entry>GPS Flags (see below)</entry>
 345             </row>
 346             <row>
 347               <entry>6</entry><entry>int16_t</entry><entry>altitude</entry><entry>m</entry>
 348             </row>
 349             <row>
 350               <entry>8</entry><entry>int32_t</entry><entry>latitude</entry><entry>degrees * 10<superscript>7</superscript></entry>
 351             </row>
 352             <row>
 353               <entry>12</entry><entry>int32_t</entry><entry>longitude</entry><entry>degrees * 10<superscript>7</superscript></entry>
 354             </row>
 355             <row>
 356               <entry>16</entry><entry>uint8_t</entry><entry>year</entry>
 357             </row>
 358             <row>
 359               <entry>17</entry><entry>uint8_t</entry><entry>month</entry>
 360             </row>
 361             <row>
 362               <entry>18</entry><entry>uint8_t</entry><entry>day</entry>
 363             </row>
 364             <row>
 365               <entry>19</entry><entry>uint8_t</entry><entry>hour</entry>
 366             </row>
 367             <row>
 368               <entry>20</entry><entry>uint8_t</entry><entry>minute</entry>
 369             </row>
 370             <row>
 371               <entry>21</entry><entry>uint8_t</entry><entry>second</entry>
 372             </row>
 373             <row>
 374               <entry>22</entry><entry>uint8_t</entry><entry>pdop</entry><entry>* 5</entry>
 375             </row>
 376             <row>
 377               <entry>23</entry><entry>uint8_t</entry><entry>hdop</entry><entry>* 5</entry>
 378             </row>
 379             <row>
 380               <entry>24</entry><entry>uint8_t</entry><entry>vdop</entry><entry>* 5</entry>
 381             </row>
 382             <row>
 383               <entry>25</entry><entry>uint8_t</entry><entry>mode</entry><entry>N, A, D, E, M, S</entry>
 384             </row>
 385             <row>
 386               <entry>26</entry><entry>uint16_t</entry><entry>ground_speed</entry><entry>cm/s</entry>
 387             </row>
 388             <row>
 389               <entry>28</entry><entry>uint8_t</entry><entry>course</entry><entry>/ 2</entry>
 390             </row>
 391             <row>
 392               <entry>29</entry><entry>uint8_t</entry><entry>unused[2]</entry>
 393             </row>
 394             <row>
 395               <entry>32</entry>
 396             </row>
 397           </tbody>
 398         </tgroup>
 399       </table>
 400     </section>
 401     <section>
 402       <title>GPS Satellite Data</title>
 403       <informaltable frame='none' label='' tocentry='0'>
 404         <tgroup cols='2' align='center' colsep='1' rowsep='1'>
 405           <colspec align='center' colwidth='*' colname='Offset'/>
 406           <colspec align='left' colwidth='3*' colname='Description'/>
 407           <thead>
 408             <row>
 409               <entry>Type</entry>
 410               <entry>Description</entry>
 411             </row>
 412           </thead>
 413           <tbody>
 414             <row>
 415               <entry>0x06</entry>
 416               <entry>GPS Satellite Data</entry>
 417             </row>
 418           </tbody>
 419         </tgroup>
 420       </informaltable>
 421       <table frame='all'>
 422         <title>GPS Satellite Data Contents</title>
 423         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 424           <colspec align='right' colwidth='*' colname='Offset'/>
 425           <colspec align='center' colwidth='3*' colname='Data Type'/>
 426           <colspec align='left' colwidth='3*' colname='Name'/>
 427           <colspec align='left' colwidth='9*' colname='Description'/>
 428           <thead>
 429             <row>
 430               <entry align='center'>Offset</entry>
 431               <entry align='center'>Data Type</entry>
 432               <entry align='center'>Name</entry>
 433               <entry align='center'>Description</entry>
 434             </row>
 435           </thead>
 436           <tbody>
 437             <row>
 438               <entry>5</entry><entry>uint8_t</entry><entry>channels</entry>
 439             </row>
 440             <row>
 441               <entry>6</entry><entry>uint8_t</entry><entry>sat_0_id</entry>
 442             </row>
 443             <row>
 444               <entry>7</entry><entry>uint8_t</entry><entry>sat_0_c_n_1</entry>
 445             </row>
 446             <row>
 447               <entry>8</entry><entry>uint8_t</entry><entry>sat_1_id</entry>
 448             </row>
 449             <row>
 450               <entry>9</entry><entry>uint8_t</entry><entry>sat_1_c_n_1</entry>
 451             </row>
 452             <row>
 453               <entry>10</entry><entry>uint8_t</entry><entry>sat_2_id</entry>
 454             </row>
 455             <row>
 456               <entry>11</entry><entry>uint8_t</entry><entry>sat_2_c_n_1</entry>
 457             </row>
 458             <row>
 459               <entry>12</entry><entry>uint8_t</entry><entry>sat_3_id</entry>
 460             </row>
 461             <row>
 462               <entry>13</entry><entry>uint8_t</entry><entry>sat_3_c_n_1</entry>
 463             </row>
 464             <row>
 465               <entry>14</entry><entry>uint8_t</entry><entry>sat_4_id</entry>
 466             </row>
 467             <row>
 468               <entry>15</entry><entry>uint8_t</entry><entry>sat_4_c_n_1</entry>
 469             </row>
 470             <row>
 471               <entry>16</entry><entry>uint8_t</entry><entry>sat_5_id</entry>
 472             </row>
 473             <row>
 474               <entry>17</entry><entry>uint8_t</entry><entry>sat_5_c_n_1</entry>
 475             </row>
 476             <row>
 477               <entry>18</entry><entry>uint8_t</entry><entry>sat_6_id</entry>
 478             </row>
 479             <row>
 480               <entry>19</entry><entry>uint8_t</entry><entry>sat_6_c_n_1</entry>
 481             </row>
 482             <row>
 483               <entry>20</entry><entry>uint8_t</entry><entry>sat_7_id</entry>
 484             </row>
 485             <row>
 486               <entry>21</entry><entry>uint8_t</entry><entry>sat_7_c_n_1</entry>
 487             </row>
 488             <row>
 489               <entry>22</entry><entry>uint8_t</entry><entry>sat_8_id</entry>
 490             </row>
 491             <row>
 492               <entry>23</entry><entry>uint8_t</entry><entry>sat_8_c_n_1</entry>
 493             </row>
 494             <row>
 495               <entry>24</entry><entry>uint8_t</entry><entry>sat_9_id</entry>
 496             </row>
 497             <row>
 498               <entry>25</entry><entry>uint8_t</entry><entry>sat_9_c_n_1</entry>
 499             </row>
 500             <row>
 501               <entry>26</entry><entry>uint8_t</entry><entry>sat_10_id</entry>
 502             </row>
 503             <row>
 504               <entry>27</entry><entry>uint8_t</entry><entry>sat_10_c_n_1</entry>
 505             </row>
 506             <row>
 507               <entry>28</entry><entry>uint8_t</entry><entry>sat_11_id</entry>
 508             </row>
 509             <row>
 510               <entry>29</entry><entry>uint8_t</entry><entry>sat_11_c_n_1</entry>
 511             </row>
 512             <row>
 513               <entry>30</entry><entry>uin8_t</entry><entry>unused30</entry>
 514             </row>
 515             <row>
 516               <entry>31</entry><entry>uin8_t</entry><entry>unused31</entry>
 517             </row>
 518             <row>
 519               <entry>32</entry>
 520             </row>
 521           </tbody>
 522         </tgroup>
 523       </table>
 524     </section>
 525   </section>
 526 </article>
 527
 528 <!--
 529
 530
 531
 532
 533  Rethinking this (over IRC), and thinking about telemetry from a
 534  companion board, it looks like 32 bytes per packet would be better (12
 535  channels of A/D from telescience would require 24 bytes).
 536
 537  Packet type 0x06: GPS satellites
 538  1 packet per second.
 539
 540
 541  TeleScience
 542
 543 <entry>5</entry><entry>uint8_t</entry><entry>channels</entry>
 544 <entry>6</entry><entry>uint16_t</entry><entry>data[12]</entry>
 545 <entry>30</entry><entry>uint8_t</entry><entry>unused[2]</entry>
 546 <entry>32</entry>
 547
 548  [ 2-line signature. Click/Enter to show. ]
 549  - -
 550  keith.packard@intel.com
 551  [ application/pgp-signature ]
 552   Keith Packard <keithp@keithp.com> (Mon. 18:59) (me sent)
 553   Subject: Re: New telemetry ideas
 554   To: bdale@gag.com
 555   Date: Mon, 27 Jun 2011 18:59:08 -0700
 556
 557   [ multipart/signed ]
 558   [ text/plain ]
 559   On Mon, 27 Jun 2011 14:25:00 -0700, Keith Packard <keithp@keithp.com> wrote:
 560   Non-text part: multipart/signed
 561
 562   > Packet type 0x05: GPS location
 563   > 1 packet per second
 564   >
 565   > 5       uint8_t         flags
 566
 567   Let's add another field here:
 568
 569 <entry>6</entry><entry>int16_t</entry><entry>gps_tick</entry><entry>tick when GPS data was received</entry>
 570
 571   That leaves a single byte unused
 572 -->