git.gag.com Git - fw/altos/blob - doc/companion.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 Companion Port</title>
   8     <subtitle>Protocol Definitions</subtitle>
   9     <author>
  10       <firstname>Keith</firstname>
  11       <surname>Packard</surname>
  12     </author>
  13     <copyright>
  14       <year>2012</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>13 January 2012</date>
  30         <revremark>Initial content</revremark>
  31       </revision>
  32     </revhistory>
  33   </articleinfo>
  34   <section>
  35     <title>Companion Port</title>
  36     <para>
  37       Many Altus Metrum products come with an eight pin Micro MaTch
  38       connector, called the Companion Port. This is often used to
  39       program devices using a programming cable. However, it can also
  40       be used to connect TeleMetrum to external companion boards
  41       (hence the name).
  42     </para>
  43     <para>
  44       The Companion Port provides two different functions:
  45       <itemizedlist>
  46         <listitem>
  47           <para>
  48           Power. Both battery-level and 3.3V regulated power are
  49           available. Note that the amount of regulated power is not
  50           huge; TeleMetrum contains a 150mA regulator and uses, at
  51           peak, about 120mA or so. For applications needing more than
  52           a few dozen mA, placing a separate regulator on them and
  53           using the battery for power is probably a good idea.
  54           </para>
  55         </listitem>
  56         <listitem>
  57           <para>
  58           SPI. The flight computer operates as a SPI master, using
  59           a protocol defined in this document. Companion boards
  60           provide a matching SPI slave implementation which supplies
  61           telemetry information for the radio downlink during flight
  62           </para>
  63         </listitem>
  64       </itemizedlist>
  65     </para>
  66   </section>
  67   <section>
  68     <title>Companion SPI Protocol</title>
  69     <para>
  70       The flight computer implements a SPI master communications
  71       channel over the companion port, and uses this to get
  72       information about a connected companion board and then to get
  73       telemetry data for transmission during flight.
  74     </para>
  75     <para>
  76       At startup time, the flight computer sends a setup request
  77       packet, and the companion board returns a board identifier, the
  78       desired telemetry update period and the number of data channels
  79       provided. The flight computer doesn't interpret the telemetry
  80       data at all, simply packing it up and sending it over the link.
  81       Telemetry packets are 32 bytes long, and companion packets use 8
  82       bytes as a header leaving room for a maximum of 12 16-bit data
  83       values.
  84     </para>
  85     <para>
  86       Because of the limits of the AVR processors used in the first
  87       two companion boards, the SPI data rate is set to 187.5kbaud.
  88     </para>
  89   </section>
  90   <section>
  91     <title>SPI Message Formats</title>
  92     <para>
  93     This section first defines the command message format sent from
  94     the flight computer to the companion board, and then the various
  95     reply message formats for each type of command message.
  96     </para>
  97     <section>
  98       <title>Command Message</title>
  99       <table frame='all'>
 100         <title>Companion Command Message</title>
 101         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 102           <colspec align='center' colwidth='*' colname='Offset'/>
 103           <colspec align='center' colwidth='3*' colname='Data Type'/>
 104           <colspec align='left' colwidth='3*' colname='Name'/>
 105           <colspec align='left' colwidth='9*' colname='Description'/>
 106           <thead>
 107             <row>
 108               <entry align='center'>Offset</entry>
 109               <entry align='center'>Data Type</entry>
 110               <entry align='center'>Name</entry>
 111               <entry align='center'>Description</entry>
 112             </row>
 113           </thead>
 114           <tbody>
 115             <row>
 116               <entry>0</entry>
 117               <entry>uint8_t</entry>
 118               <entry>command</entry>
 119               <entry>Command identifier</entry>
 120             </row>
 121             <row>
 122               <entry>1</entry>
 123               <entry>uint8_t</entry>
 124               <entry>flight_state</entry>
 125               <entry>Current flight computer state</entry>
 126             </row>
 127             <row>
 128               <entry>2</entry>
 129               <entry>uint16_t</entry>
 130               <entry>tick</entry>
 131               <entry>Flight computer clock (100 ticks/second)</entry>
 132             </row>
 133             <row>
 134               <entry>4</entry>
 135               <entry>uint16_t</entry>
 136               <entry>serial</entry>
 137               <entry>Flight computer serial number</entry>
 138             </row>
 139             <row>
 140               <entry>6</entry>
 141               <entry>uint16_t</entry>
 142               <entry>flight</entry>
 143               <entry>Flight number</entry>
 144             </row>
 145             <row>
 146               <entry>8</entry>
 147             </row>
 148           </tbody>
 149         </tgroup>
 150       </table>
 151       <table frame='all'>
 152         <title>Companion Command Identifiers</title>
 153         <tgroup cols='3' align='center' colsep='1' rowsep='1'>
 154           <colspec align='center' colwidth='*' colname='Value'/>
 155           <colspec align='left' colwidth='3*' colname='Name'/>
 156           <colspec align='left' colwidth='9*' colname='Description'/>
 157           <thead>
 158             <row>
 159               <entry>Value</entry>
 160               <entry>Name</entry>
 161               <entry>Description</entry>
 162             </row>
 163           </thead>
 164           <tbody>
 165             <row>
 166               <entry>1</entry>
 167               <entry>SETUP</entry>
 168               <entry>Supply the flight computer with companion
 169               information</entry>
 170             </row>
 171             <row>
 172               <entry>2</entry>
 173               <entry>FETCH</entry>
 174               <entry>Return telemetry information</entry>
 175             </row>
 176             <row>
 177               <entry>3</entry>
 178               <entry>NOTIFY</entry>
 179               <entry>Tell companion board when flight state
 180               changes</entry>
 181             </row>
 182           </tbody>
 183         </tgroup>
 184       </table>
 185       <para>
 186         The flight computer will send a SETUP message shortly after
 187         power-up and will then send FETCH messages no more often than
 188         the rate specified in the SETUP reply. NOTIFY messages will be
 189         sent whenever the flight state changes.
 190       </para>
 191       <para>
 192         'flight_state' records the current state of the flight,
 193         whether on the pad, under power, coasting to apogee or
 194         descending on the drogue or main chute.
 195       </para>
 196       <para>
 197         'tick' provides the current flight computer clock, which
 198         be used to synchronize data recorded on the flight computer
 199         with that recorded on the companion board in post-flight analysis.
 200       </para>
 201       <para>
 202         'serial' is the product serial number of the flight computer,
 203         'flight' is the flight sequence number. Together, these two
 204         uniquely identify the flight and can be recorded with any
 205         companion board data logging to associate the companion data
 206         with the proper flight.
 207       </para>
 208       <para>
 209         NOTIFY commands require no reply at all, they are used solely
 210         to inform the companion board when the state of the flight, as
 211         computed by the flight computer, changes. Companion boards can
 212         use this to change data collection parameters, disabling data
 213         logging until the flight starts and terminating it when the
 214         flight ends.
 215       </para>
 216     </section>
 217     <section>
 218       <title>SETUP reply message</title>
 219       <table frame='all'>
 220         <title>SETUP reply contents</title>
 221         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 222           <colspec align='center' colwidth='*' colname='Offset'/>
 223           <colspec align='center' colwidth='3*' colname='Data Type'/>
 224           <colspec align='left' colwidth='3*' colname='Name'/>
 225           <colspec align='left' colwidth='9*' colname='Description'/>
 226           <thead>
 227             <row>
 228               <entry align='center'>Offset</entry>
 229               <entry align='center'>Data Type</entry>
 230               <entry align='center'>Name</entry>
 231               <entry align='center'>Description</entry>
 232             </row>
 233           </thead>
 234           <tbody>
 235             <row>
 236               <entry>0</entry>
 237               <entry>uint16_t</entry>
 238               <entry>board_id</entry>
 239               <entry>Board identifier</entry>
 240             </row>
 241             <row>
 242               <entry>2</entry>
 243               <entry>uint16_t</entry>
 244               <entry>board_id_inverse</entry>
 245               <entry>~board_id—used to tell if a board is present</entry>
 246             </row>
 247             <row>
 248               <entry>4</entry>
 249               <entry>uint8_t</entry>
 250               <entry>update_period</entry>
 251               <entry>Minimum time (in 100Hz ticks) between FETCH commands</entry>
 252             </row>
 253             <row>
 254               <entry>5</entry>
 255               <entry>uint8_t</entry>
 256               <entry>channels</entry>
 257               <entry>Number of data channels to retrieve in FETCH command</entry>
 258             </row>
 259             <row>
 260               <entry>6</entry>
 261             </row>
 262           </tbody>
 263         </tgroup>
 264       </table>
 265       <para>
 266         The SETUP reply contains enough information to uniquely
 267         identify the companion board to the end user as well as for
 268         the flight computer to know how many data values to expect in
 269         reply to a FETCH command, and how often to fetch that data.
 270       </para>
 271       <para>
 272         To detect the presence of a companion board, the flight
 273         computer checks to make sure that board_id_inverse is the
 274         bit-wise inverse of board_id. Current companion boards use
 275         USB product ID as the board_id, but the flight computer does
 276         not interpret this data and so it can be any value.
 277       </para>
 278     </section>
 279     <section>
 280       <title>FETCH reply message</title>
 281       <table frame='all'>
 282         <title>FETCH reply contents</title>
 283         <tgroup cols='4' align='center' colsep='1' rowsep='1'>
 284           <colspec align='center' colwidth='*' colname='Offset'/>
 285           <colspec align='center' colwidth='3*' colname='Data Type'/>
 286           <colspec align='left' colwidth='3*' colname='Name'/>
 287           <colspec align='left' colwidth='9*' colname='Description'/>
 288           <thead>
 289             <row>
 290               <entry align='center'>Offset</entry>
 291               <entry align='center'>Data Type</entry>
 292               <entry align='center'>Name</entry>
 293               <entry align='center'>Description</entry>
 294             </row>
 295           </thead>
 296           <tbody>
 297             <row>
 298               <entry>0</entry>
 299               <entry>uint16_t</entry>
 300               <entry>data0</entry>
 301               <entry>0th data item</entry>
 302             </row>
 303             <row>
 304               <entry>2</entry>
 305               <entry>uint16_t</entry>
 306               <entry>data1</entry>
 307               <entry>1st data item</entry>
 308             </row>
 309             <row>
 310               <entry>...</entry>
 311             </row>
 312           </tbody>
 313         </tgroup>
 314       </table>
 315       <para>
 316         The FETCH reply contains arbitrary data to be reported over
 317         the flight computer telemetry link. The number of 16-bit data items
 318         must match the 'channels' value provided in the SETUP reply
 319         message.
 320       </para>
 321     </section>
 322   </section>
 323   <section>
 324     <title>History and Motivation</title>
 325     <para>
 326       To allow cross-programming, the original TeleMetrum and
 327       TeleDongle designs needed to include some kind of
 328       connector. With that in place, adding the ability to connect
 329       external cards to TeleMetrum was fairly simple. We set the
 330       software piece of this puzzle aside until we had a companion
 331       board to use.
 332     </para>
 333     <para>
 334       The first companion board was TeleScience. Designed to collect
 335       temperature data from the nose and fin of the airframe, the main
 336       requirement for the companion port was that it be able to report
 337       telemetry data during flight as a back-up in case the
 338       TeleScience on-board data was lost.
 339     </para>
 340     <para>
 341       The second companion board, TelePyro, provides 8 additional
 342       channels for deployment, staging or other activities. To avoid
 343       re-programming the TeleMetrum to use TelePyro, we decided to
 344       provide enough information over the companion link for it to
 345       independently control those channels.
 346     </para>
 347     <para>
 348       Providing a standard, constant interface between the flight
 349       computer and companion boards allows for the base flight
 350       computer firmware to include support for companion boards.
 351     </para>
 352   </section>
 353 </article>