diff options
Diffstat (limited to 'doc/companion.xsl')
| -rw-r--r-- | doc/companion.xsl | 353 |
1 files changed, 0 insertions, 353 deletions
diff --git a/doc/companion.xsl b/doc/companion.xsl deleted file mode 100644 index 14e2194e..00000000 --- a/doc/companion.xsl +++ /dev/null @@ -1,353 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE article 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> - <para> - 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. - </para> - </listitem> - <listitem> - <para> - 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 - </para> - </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> - <para> - 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. - </para> - <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> |