doc: Add companion SPI message protocol doc

Signed-off-by: Keith Packard <keithp@keithp.com>

2 files changed, 349 insertions, 2 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 14bce5c9..6c77f0ee 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -10,8 +10,8 @@ RELNOTES=\
 	release-notes-1.0.1.html
 
 RELNOTES_XSL=$(RELNOTES:.html=.xsl)
-HTML=altusmetrum.html altos.html telemetry.html $(RELNOTES)
-PDF=altusmetrum.pdf altos.pdf telemetry.pdf
+HTML=altusmetrum.html altos.html telemetry.html companion.html $(RELNOTES)
+PDF=altusmetrum.pdf altos.pdf telemetry.pdf companion.pdf
 DOC=$(HTML) $(PDF)
 HTMLSTYLE=/usr/share/xml/docbook/stylesheet/docbook-xsl/html/docbook.xsl
 FOSTYLE=/usr/share/xml/docbook/stylesheet/docbook-xsl/fo/docbook.xsl
diff --git a/doc/companion.xsl b/doc/companion.xsl
new file mode 100644
index 00000000..1215d9af
--- /dev/null
+++ b/doc/companion.xsl
@@ -0,0 +1,347 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
+
+<article>
+  <articleinfo>
+    <title>AltOS Companion Port</title>
+    <subtitle>Protocol Definitions</subtitle>
+    <author>
+      <firstname>Keith</firstname>
+      <surname>Packard</surname>
+    </author>
+    <copyright>
+      <year>2012</year>
+      <holder>Keith Packard</holder>
+    </copyright>
+    <legalnotice>
+      <para>
+	This document is released under the terms of the
+	<ulink url="http://creativecommons.org/licenses/by-sa/3.0/">
+	  Creative Commons ShareAlike 3.0
+	</ulink>
+	license.
+      </para>
+    </legalnotice>
+    <revhistory>
+      <revision>
+	<revnumber>0.1</revnumber>
+	<date>13 January 2012</date>
+	<revremark>Initial content</revremark>
+      </revision>
+    </revhistory>
+  </articleinfo>
+  <section>
+    <title>Companion Port</title>
+    <para>
+      Many Altus Metrum products come with an eight pin Micro MaTch
+      connector, called the Companion Port. This is often used to
+      program devices using a programming cable. However, it can also
+      be used to connect TeleMetrum to external companion boards
+      (hence the name).
+    </para>
+    <para>
+      The Companion Port provides two different functions:
+      <itemizedlist>
+	<listitem>
+	  Power. Both battery-level and 3.3V regulated power are
+	  available. Note that the amount of regulated power is not
+	  huge; TeleMetrum contains a 150mA regulator and uses, at
+	  peak, about 120mA or so. For applications needing more than
+	  a few dozen mA, placing a separate regulator on them and
+	  using the battery for power is probably a good idea.
+	</listitem>
+	<listitem>
+	  SPI. The flight computer operates as a SPI master, using
+	  a protocol defined in this document. Companion boards
+	  provide a matching SPI slave implementation which supplies
+	  telemetry information for the radio downlink during flight
+	</listitem>
+      </itemizedlist>
+    </para>
+  </section>
+  <section>
+    <title>Companion SPI Protocol</title>
+    <para>
+      The flight computer implements a SPI master communications
+      channel over the companion port, and uses this to get
+      information about a connected companion board and then to get
+      telemetry data for transmission during flight.
+    </para>
+    <para>
+      At startup time, the flight computer sends a setup request
+      packet, and the companion board returns a board identifier, the
+      desired telemetry update period and the number of data channels
+      provided. The flight computer doesn't interpret the telemetry
+      data at all, simply packing it up and sending it over the link.
+      Telemetry packets are 32 bytes long, and companion packets use 8
+      bytes as a header leaving room for a maximum of 12 16-bit data
+      values.
+    </para>
+    <para>
+      Because of the limits of the AVR processors used in the first
+      two companion boards, the SPI data rate is set to 187.5kbaud.
+    </para>
+  </section>
+  <section>
+    <title>SPI Message Formats</title>
+    This section first defines the command message format sent from
+    the flight computer to the companion board, and then the various
+    reply message formats for each type of command message.
+    <section>
+      <title>Command Message</title>
+      <table frame='all'>
+	<title>Companion Command Message</title>
+	<tgroup cols='4' align='center' colsep='1' rowsep='1'>
+	  <colspec align='center' colwidth='*' colname='Offset'/>
+	  <colspec align='center' colwidth='3*' colname='Data Type'/>
+	  <colspec align='left' colwidth='3*' colname='Name'/>
+	  <colspec align='left' colwidth='9*' colname='Description'/>
+	  <thead>
+	    <row>
+	      <entry align='center'>Offset</entry>
+	      <entry align='center'>Data Type</entry>
+	      <entry align='center'>Name</entry>
+	      <entry align='center'>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry>0</entry>
+	      <entry>uint8_t</entry>
+	      <entry>command</entry>
+	      <entry>Command identifier</entry>
+	    </row>
+	    <row>
+	      <entry>1</entry>
+	      <entry>uint8_t</entry>
+	      <entry>flight_state</entry>
+	      <entry>Current flight computer state</entry>
+	    </row>
+	    <row>
+	      <entry>2</entry>
+	      <entry>uint16_t</entry>
+	      <entry>tick</entry>
+	      <entry>Flight computer clock (100 ticks/second)</entry>
+	    </row>
+	    <row>
+	      <entry>4</entry>
+	      <entry>uint16_t</entry>
+	      <entry>serial</entry>
+	      <entry>Flight computer serial number</entry>
+	    </row>
+	    <row>
+	      <entry>6</entry>
+	      <entry>uint16_t</entry>
+	      <entry>flight</entry>
+	      <entry>Flight number</entry>
+	    </row>
+	    <row>
+	      <entry>8</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+      <table frame='all'>
+	<title>Companion Command Identifiers</title>
+	<tgroup cols='3' align='center' colsep='1' rowsep='1'>
+	  <colspec align='center' colwidth='*' colname='Value'/>
+	  <colspec align='left' colwidth='3*' colname='Name'/>
+	  <colspec align='left' colwidth='9*' colname='Description'/>
+	  <thead>
+	    <row>
+	      <entry>Value</entry>
+	      <entry>Name</entry>
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry>1</entry>
+	      <entry>SETUP</entry>
+	      <entry>Supply the flight computer with companion
+	      information</entry>
+	    </row>
+	    <row>
+	      <entry>2</entry>
+	      <entry>FETCH</entry>
+	      <entry>Return telemetry information</entry>
+	    </row>
+	    <row>
+	      <entry>3</entry>
+	      <entry>NOTIFY</entry>
+	      <entry>Tell companion board when flight state
+	      changes</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+      <para>
+	The flight computer will send a SETUP message shortly after
+	power-up and will then send FETCH messages no more often than
+	the rate specified in the SETUP reply. NOTIFY messages will be
+	sent whenever the flight state changes.
+      </para>
+      <para>
+	'flight_state' records the current state of the flight,
+	whether on the pad, under power, coasting to apogee or
+	descending on the drogue or main chute.
+      </para>
+      <para>
+	'tick' provides the current flight computer clock, which 
+	be used to synchronize data recorded on the flight computer
+	with that recorded on the companion board in post-flight analysis.
+      </para>
+      <para>
+	'serial' is the product serial number of the flight computer,
+	'flight' is the flight sequence number. Together, these two
+	uniquely identify the flight and can be recorded with any
+	companion board data logging to associate the companion data
+	with the proper flight.
+      </para>
+      <para>
+	NOTIFY commands require no reply at all, they are used solely
+	to inform the companion board when the state of the flight, as
+	computed by the flight computer, changes. Companion boards can
+	use this to change data collection parameters, disabling data
+	logging until the flight starts and terminating it when the
+	flight ends.
+      </para>
+    </section>
+    <section>
+      <title>SETUP reply message</title>
+      <table frame='all'>
+	<title>SETUP reply contents</title>
+	<tgroup cols='4' align='center' colsep='1' rowsep='1'>
+	  <colspec align='center' colwidth='*' colname='Offset'/>
+	  <colspec align='center' colwidth='3*' colname='Data Type'/>
+	  <colspec align='left' colwidth='3*' colname='Name'/>
+	  <colspec align='left' colwidth='9*' colname='Description'/>
+	  <thead>
+	    <row>
+	      <entry align='center'>Offset</entry>
+	      <entry align='center'>Data Type</entry>
+	      <entry align='center'>Name</entry>
+	      <entry align='center'>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry>0</entry>
+	      <entry>uint16_t</entry>
+	      <entry>board_id</entry>
+	      <entry>Board identifier</entry>
+	    </row>
+	    <row>
+	      <entry>2</entry>
+	      <entry>uint16_t</entry>
+	      <entry>board_id_inverse</entry>
+	      <entry>~board_id—used to tell if a board is present</entry>
+	    </row>
+	    <row>
+	      <entry>4</entry>
+	      <entry>uint8_t</entry>
+	      <entry>update_period</entry>
+	      <entry>Minimum time (in 100Hz ticks) between FETCH commands</entry>
+	    </row>
+	    <row>
+	      <entry>5</entry>
+	      <entry>uint8_t</entry>
+	      <entry>channels</entry>
+	      <entry>Number of data channels to retrieve in FETCH command</entry>
+	    </row>
+	    <row>
+	      <entry>6</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+      <para>
+	The SETUP reply contains enough information to uniquely
+	identify the companion board to the end user as well as for
+	the flight computer to know how many data values to expect in
+	reply to a FETCH command, and how often to fetch that data.
+      </para>
+      <para>
+	To detect the presence of a companion board, the flight
+	computer checks to make sure that board_id_inverse is the
+	bit-wise inverse of board_id. Current companion boards use
+	USB product ID as the board_id, but the flight computer does
+	not interpret this data and so it can be any value.
+      </para>
+    </section>
+    <section>
+      <title>FETCH reply message</title>
+      <table frame='all'>
+	<title>FETCH reply contents</title>
+	<tgroup cols='4' align='center' colsep='1' rowsep='1'>
+	  <colspec align='center' colwidth='*' colname='Offset'/>
+	  <colspec align='center' colwidth='3*' colname='Data Type'/>
+	  <colspec align='left' colwidth='3*' colname='Name'/>
+	  <colspec align='left' colwidth='9*' colname='Description'/>
+	  <thead>
+	    <row>
+	      <entry align='center'>Offset</entry>
+	      <entry align='center'>Data Type</entry>
+	      <entry align='center'>Name</entry>
+	      <entry align='center'>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry>0</entry>
+	      <entry>uint16_t</entry>
+	      <entry>data0</entry>
+	      <entry>0th data item</entry>
+	    </row>
+	    <row>
+	      <entry>2</entry>
+	      <entry>uint16_t</entry>
+	      <entry>data1</entry>
+	      <entry>1st data item</entry>
+	    </row>
+	    <row>
+	      <entry>...</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+      <para>
+	The FETCH reply contains arbitrary data to be reported over
+	the flight computer telemetry link. The number of 16-bit data items
+	must match the 'channels' value provided in the SETUP reply
+	message.
+      </para>
+    </section>
+  </section>
+  <section>
+    <title>History and Motivation</title>
+    <para>
+      To allow cross-programming, the original TeleMetrum and
+      TeleDongle designs needed to include some kind of
+      connector. With that in place, adding the ability to connect
+      external cards to TeleMetrum was fairly simple. We set the
+      software piece of this puzzle aside until we had a companion
+      board to use.
+    </para>
+    <para>
+      The first companion board was TeleScience. Designed to collect
+      temperature data from the nose and fin of the airframe, the main
+      requirement for the companion port was that it be able to report
+      telemetry data during flight as a back-up in case the
+      TeleScience on-board data was lost.
+    </para>
+    <para>
+      The second companion board, TelePyro, provides 8 additional
+      channels for deployment, staging or other activities. To avoid
+      re-programming the TeleMetrum to use TelePyro, we decided to
+      provide enough information over the companion link for it to
+      independently control those channels.
+    </para>
+    <para>
+      Providing a standard, constant interface between the flight
+      computer and companion boards allows for the base flight
+      computer firmware to include support for companion boards.
+    </para>
+  </section>
+</article>