From: Keith Packard Date: Fri, 13 Jan 2012 18:40:30 +0000 (-0800) Subject: doc: Add companion SPI message protocol doc X-Git-Tag: 1.0.9.4~55 X-Git-Url: https://git.gag.com/?p=fw%2Faltos;a=commitdiff_plain;h=1b4a4c7b6a0c3f93267f33482f490e7aa25c2158 doc: Add companion SPI message protocol doc Signed-off-by: Keith Packard --- 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 @@ + + + +
+ + AltOS Companion Port + Protocol Definitions + + Keith + Packard + + + 2012 + Keith Packard + + + + This document is released under the terms of the + + Creative Commons ShareAlike 3.0 + + license. + + + + + 0.1 + 13 January 2012 + Initial content + + + +
+ Companion Port + + 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). + + + The Companion Port provides two different functions: + + + 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. + + + 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 + + + +
+
+ Companion SPI Protocol + + 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. + + + 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. + + + Because of the limits of the AVR processors used in the first + two companion boards, the SPI data rate is set to 187.5kbaud. + +
+
+ SPI Message Formats + 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. +
+ Command Message + + Companion Command Message + + + + + + + + Offset + Data Type + Name + Description + + + + + 0 + uint8_t + command + Command identifier + + + 1 + uint8_t + flight_state + Current flight computer state + + + 2 + uint16_t + tick + Flight computer clock (100 ticks/second) + + + 4 + uint16_t + serial + Flight computer serial number + + + 6 + uint16_t + flight + Flight number + + + 8 + + + +
+ + Companion Command Identifiers + + + + + + + Value + Name + Description + + + + + 1 + SETUP + Supply the flight computer with companion + information + + + 2 + FETCH + Return telemetry information + + + 3 + NOTIFY + Tell companion board when flight state + changes + + + +
+ + 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. + + + '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. + + + '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. + + + '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. + + + 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. + +
+
+ SETUP reply message + + SETUP reply contents + + + + + + + + Offset + Data Type + Name + Description + + + + + 0 + uint16_t + board_id + Board identifier + + + 2 + uint16_t + board_id_inverse + ~board_id—used to tell if a board is present + + + 4 + uint8_t + update_period + Minimum time (in 100Hz ticks) between FETCH commands + + + 5 + uint8_t + channels + Number of data channels to retrieve in FETCH command + + + 6 + + + +
+ + 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. + + + 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. + +
+
+ FETCH reply message + + FETCH reply contents + + + + + + + + Offset + Data Type + Name + Description + + + + + 0 + uint16_t + data0 + 0th data item + + + 2 + uint16_t + data1 + 1st data item + + + ... + + + +
+ + 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. + +
+
+
+ History and Motivation + + 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. + + + 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. + + + 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. + + + 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. + +
+