diff options
| -rw-r--r-- | doc/Makefile | 4 | ||||
| -rw-r--r-- | doc/companion.xsl | 347 |
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> |