diff options
Diffstat (limited to 'doc/companion.txt')
| -rw-r--r-- | doc/companion.txt | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/doc/companion.txt b/doc/companion.txt new file mode 100644 index 00000000..75ffa228 --- /dev/null +++ b/doc/companion.txt @@ -0,0 +1,241 @@ += AltOS Companion Port +:doctype: article +:toc: + +== 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. + + .Companion Command Message + [options="border",cols="1,3,3,9"] + |==== + |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 + [options="border",cols="1,3,9"] + |==== + |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 + [options="border",cols="1,3,3,9"] + |==== + |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 + [options="border",cols="1,3,3,9"] + |==== + |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. |