1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
7 <title>AltOS Companion Port</title>
8 <subtitle>Protocol Definitions</subtitle>
10 <firstname>Keith</firstname>
11 <surname>Packard</surname>
15 <holder>Keith Packard</holder>
19 This document is released under the terms of the
20 <ulink url="http://creativecommons.org/licenses/by-sa/3.0/">
21 Creative Commons ShareAlike 3.0
28 <revnumber>0.1</revnumber>
29 <date>13 January 2012</date>
30 <revremark>Initial content</revremark>
35 <title>Companion Port</title>
37 Many Altus Metrum products come with an eight pin Micro MaTch
38 connector, called the Companion Port. This is often used to
39 program devices using a programming cable. However, it can also
40 be used to connect TeleMetrum to external companion boards
44 The Companion Port provides two different functions:
47 Power. Both battery-level and 3.3V regulated power are
48 available. Note that the amount of regulated power is not
49 huge; TeleMetrum contains a 150mA regulator and uses, at
50 peak, about 120mA or so. For applications needing more than
51 a few dozen mA, placing a separate regulator on them and
52 using the battery for power is probably a good idea.
55 SPI. The flight computer operates as a SPI master, using
56 a protocol defined in this document. Companion boards
57 provide a matching SPI slave implementation which supplies
58 telemetry information for the radio downlink during flight
64 <title>Companion SPI Protocol</title>
66 The flight computer implements a SPI master communications
67 channel over the companion port, and uses this to get
68 information about a connected companion board and then to get
69 telemetry data for transmission during flight.
72 At startup time, the flight computer sends a setup request
73 packet, and the companion board returns a board identifier, the
74 desired telemetry update period and the number of data channels
75 provided. The flight computer doesn't interpret the telemetry
76 data at all, simply packing it up and sending it over the link.
77 Telemetry packets are 32 bytes long, and companion packets use 8
78 bytes as a header leaving room for a maximum of 12 16-bit data
82 Because of the limits of the AVR processors used in the first
83 two companion boards, the SPI data rate is set to 187.5kbaud.
87 <title>SPI Message Formats</title>
88 This section first defines the command message format sent from
89 the flight computer to the companion board, and then the various
90 reply message formats for each type of command message.
92 <title>Command Message</title>
94 <title>Companion Command Message</title>
95 <tgroup cols='4' align='center' colsep='1' rowsep='1'>
96 <colspec align='center' colwidth='*' colname='Offset'/>
97 <colspec align='center' colwidth='3*' colname='Data Type'/>
98 <colspec align='left' colwidth='3*' colname='Name'/>
99 <colspec align='left' colwidth='9*' colname='Description'/>
102 <entry align='center'>Offset</entry>
103 <entry align='center'>Data Type</entry>
104 <entry align='center'>Name</entry>
105 <entry align='center'>Description</entry>
111 <entry>uint8_t</entry>
112 <entry>command</entry>
113 <entry>Command identifier</entry>
117 <entry>uint8_t</entry>
118 <entry>flight_state</entry>
119 <entry>Current flight computer state</entry>
123 <entry>uint16_t</entry>
125 <entry>Flight computer clock (100 ticks/second)</entry>
129 <entry>uint16_t</entry>
130 <entry>serial</entry>
131 <entry>Flight computer serial number</entry>
135 <entry>uint16_t</entry>
136 <entry>flight</entry>
137 <entry>Flight number</entry>
146 <title>Companion Command Identifiers</title>
147 <tgroup cols='3' align='center' colsep='1' rowsep='1'>
148 <colspec align='center' colwidth='*' colname='Value'/>
149 <colspec align='left' colwidth='3*' colname='Name'/>
150 <colspec align='left' colwidth='9*' colname='Description'/>
155 <entry>Description</entry>
162 <entry>Supply the flight computer with companion
168 <entry>Return telemetry information</entry>
172 <entry>NOTIFY</entry>
173 <entry>Tell companion board when flight state
180 The flight computer will send a SETUP message shortly after
181 power-up and will then send FETCH messages no more often than
182 the rate specified in the SETUP reply. NOTIFY messages will be
183 sent whenever the flight state changes.
186 'flight_state' records the current state of the flight,
187 whether on the pad, under power, coasting to apogee or
188 descending on the drogue or main chute.
191 'tick' provides the current flight computer clock, which
192 be used to synchronize data recorded on the flight computer
193 with that recorded on the companion board in post-flight analysis.
196 'serial' is the product serial number of the flight computer,
197 'flight' is the flight sequence number. Together, these two
198 uniquely identify the flight and can be recorded with any
199 companion board data logging to associate the companion data
200 with the proper flight.
203 NOTIFY commands require no reply at all, they are used solely
204 to inform the companion board when the state of the flight, as
205 computed by the flight computer, changes. Companion boards can
206 use this to change data collection parameters, disabling data
207 logging until the flight starts and terminating it when the
212 <title>SETUP reply message</title>
214 <title>SETUP reply contents</title>
215 <tgroup cols='4' align='center' colsep='1' rowsep='1'>
216 <colspec align='center' colwidth='*' colname='Offset'/>
217 <colspec align='center' colwidth='3*' colname='Data Type'/>
218 <colspec align='left' colwidth='3*' colname='Name'/>
219 <colspec align='left' colwidth='9*' colname='Description'/>
222 <entry align='center'>Offset</entry>
223 <entry align='center'>Data Type</entry>
224 <entry align='center'>Name</entry>
225 <entry align='center'>Description</entry>
231 <entry>uint16_t</entry>
232 <entry>board_id</entry>
233 <entry>Board identifier</entry>
237 <entry>uint16_t</entry>
238 <entry>board_id_inverse</entry>
239 <entry>~board_id—used to tell if a board is present</entry>
243 <entry>uint8_t</entry>
244 <entry>update_period</entry>
245 <entry>Minimum time (in 100Hz ticks) between FETCH commands</entry>
249 <entry>uint8_t</entry>
250 <entry>channels</entry>
251 <entry>Number of data channels to retrieve in FETCH command</entry>
260 The SETUP reply contains enough information to uniquely
261 identify the companion board to the end user as well as for
262 the flight computer to know how many data values to expect in
263 reply to a FETCH command, and how often to fetch that data.
266 To detect the presence of a companion board, the flight
267 computer checks to make sure that board_id_inverse is the
268 bit-wise inverse of board_id. Current companion boards use
269 USB product ID as the board_id, but the flight computer does
270 not interpret this data and so it can be any value.
274 <title>FETCH reply message</title>
276 <title>FETCH reply contents</title>
277 <tgroup cols='4' align='center' colsep='1' rowsep='1'>
278 <colspec align='center' colwidth='*' colname='Offset'/>
279 <colspec align='center' colwidth='3*' colname='Data Type'/>
280 <colspec align='left' colwidth='3*' colname='Name'/>
281 <colspec align='left' colwidth='9*' colname='Description'/>
284 <entry align='center'>Offset</entry>
285 <entry align='center'>Data Type</entry>
286 <entry align='center'>Name</entry>
287 <entry align='center'>Description</entry>
293 <entry>uint16_t</entry>
295 <entry>0th data item</entry>
299 <entry>uint16_t</entry>
301 <entry>1st data item</entry>
310 The FETCH reply contains arbitrary data to be reported over
311 the flight computer telemetry link. The number of 16-bit data items
312 must match the 'channels' value provided in the SETUP reply
318 <title>History and Motivation</title>
320 To allow cross-programming, the original TeleMetrum and
321 TeleDongle designs needed to include some kind of
322 connector. With that in place, adding the ability to connect
323 external cards to TeleMetrum was fairly simple. We set the
324 software piece of this puzzle aside until we had a companion
328 The first companion board was TeleScience. Designed to collect
329 temperature data from the nose and fin of the airframe, the main
330 requirement for the companion port was that it be able to report
331 telemetry data during flight as a back-up in case the
332 TeleScience on-board data was lost.
335 The second companion board, TelePyro, provides 8 additional
336 channels for deployment, staging or other activities. To avoid
337 re-programming the TeleMetrum to use TelePyro, we decided to
338 provide enough information over the companion link for it to
339 independently control those channels.
342 Providing a standard, constant interface between the flight
343 computer and companion boards allows for the base flight
344 computer firmware to include support for companion boards.