--- /dev/null
+<?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>
projects / fw / altos / commitdiff