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