2 Keith Packard <keithp@keithp.com>; Bdale Garbee <bdale@gag.com>
4 :copyright: Bdale Garbee and Keith Packard 2018
8 :pdf-style: altusmetrum
12 include::header.adoc[]
16 Many Altus Metrum products come with an eight pin Micro MaTch
17 connector, called the Companion Port. This is often used to
18 program devices using a programming cable. However, it can
19 also be used to connect TeleMetrum to external companion
20 boards (hence the name).
22 The Companion Port provides two different functions:
24 * Power. Both battery-level and 3.3V regulated power are
25 available. Note that the amount of regulated power is not
26 huge; TeleMetrum contains a 150mA regulator and uses, at
27 peak, about 120mA or so. For applications needing more than
28 a few dozen mA, placing a separate regulator on them and
29 using the battery for power is probably a good idea.
32 * SPI. The flight computer operates as a SPI master, using
33 a protocol defined in this document. Companion boards
34 provide a matching SPI slave implementation which supplies
35 telemetry information for the radio downlink during flight
37 == Companion SPI Protocol
39 The flight computer implements a SPI master communications
40 channel over the companion port, and uses this to get
41 information about a connected companion board and then to get
42 telemetry data for transmission during flight.
44 At startup time, the flight computer sends a setup request
45 packet, and the companion board returns a board identifier,
46 the desired telemetry update period and the number of data
47 channels provided. The flight computer doesn't interpret the
48 telemetry data at all, simply packing it up and sending it
49 over the link. Telemetry packets are 32 bytes long, and
50 companion packets use 8 bytes as a header leaving room for a
51 maximum of 12 16-bit data values.
53 Because of the limits of the AVR processors used in the first
54 two companion boards, the SPI data rate is set to 187.5kbaud.
56 == SPI Message Formats
58 This section first defines the command message format sent from
59 the flight computer to the companion board, and then the various
60 reply message formats for each type of command message.
62 .Companion Command Message
63 [options="border",cols="1,3,3,9"]
78 |Current flight computer state
83 |Flight computer clock (100 ticks/second)
88 |Flight computer serial number
102 .Companion Command Identifiers
103 [options="border",cols="1,3,9"]
111 |Supply the flight computer with companion
116 |Return telemetry information
120 |Tell companion board when flight state changes
123 The flight computer will send a SETUP message shortly after
124 power-up and will then send FETCH messages no more often than
125 the rate specified in the SETUP reply. NOTIFY messages will be
126 sent whenever the flight state changes.
128 'flight_state' records the current state of the flight,
129 whether on the pad, under power, coasting to apogee or
130 descending on the drogue or main chute.
132 'tick' provides the current flight computer clock, which
133 be used to synchronize data recorded on the flight computer
134 with that recorded on the companion board in post-flight analysis.
136 'serial' is the product serial number of the flight computer,
137 'flight' is the flight sequence number. Together, these two
138 uniquely identify the flight and can be recorded with any
139 companion board data logging to associate the companion data
140 with the proper flight.
142 NOTIFY commands require no reply at all, they are used solely
143 to inform the companion board when the state of the flight, as
144 computed by the flight computer, changes. Companion boards can
145 use this to change data collection parameters, disabling data
146 logging until the flight starts and terminating it when the
149 === SETUP reply message
151 .SETUP reply contents
152 [options="border",cols="1,3,3,9"]
167 |~board_id—used to tell if a board is present
172 |Minimum time (in 100Hz ticks) between FETCH commands
177 |Number of data channels to retrieve in FETCH command
185 The SETUP reply contains enough information to uniquely
186 identify the companion board to the end user as well as for
187 the flight computer to know how many data values to expect in
188 reply to a FETCH command, and how often to fetch that data.
190 To detect the presence of a companion board, the flight
191 computer checks to make sure that board_id_inverse is the
192 bit-wise inverse of board_id. Current companion boards use
193 USB product ID as the board_id, but the flight computer does
194 not interpret this data and so it can be any value.
196 === FETCH reply message
198 .FETCH reply contents
199 [options="border",cols="1,3,3,9"]
222 The FETCH reply contains arbitrary data to be reported
223 over the flight computer telemetry link. The number of
224 16-bit data items must match the 'channels' value
225 provided in the SETUP reply message.
227 == History and Motivation
229 To allow cross-programming, the original TeleMetrum and
230 TeleDongle designs needed to include some kind of
231 connector. With that in place, adding the ability to connect
232 external cards to TeleMetrum was fairly simple. We set the
233 software piece of this puzzle aside until we had a companion
236 The first companion board was TeleScience. Designed to collect
237 temperature data from the nose and fin of the airframe, the main
238 requirement for the companion port was that it be able to report
239 telemetry data during flight as a back-up in case the
240 TeleScience on-board data was lost.
242 The second companion board, TelePyro, provides 8 additional
243 channels for deployment, staging or other activities. To avoid
244 re-programming the TeleMetrum to use TelePyro, we decided to
245 provide enough information over the companion link for it to
246 independently control those channels.
248 Providing a standard, constant interface between the flight
249 computer and companion boards allows for the base flight
250 computer firmware to include support for companion boards.