1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>AltOS Companion Port</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><div><h2 class="title"><a name="idp12220528"></a>AltOS Companion Port</h2></div><div><h3 class="subtitle"><i>Protocol Definitions</i></h3></div><div><div class="author"><h3 class="author"><span class="firstname">Keith</span> <span class="surname">Packard</span></h3></div></div><div><p class="copyright">Copyright © 2012 Keith Packard</p></div><div><div class="legalnotice"><a name="idp38737264"></a><p>
2 This document is released under the terms of the
3 <a class="ulink" href="http://creativecommons.org/licenses/by-sa/3.0/" target="_top">
4 Creative Commons ShareAlike 3.0
7 </p></div></div><div><div class="revhistory"><table style="border-style:solid; width:100%;" summary="Revision History"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision 0.1</td><td align="left">13 January 2012</td></tr><tr><td align="left" colspan="2">Initial content</td></tr></table></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#idp39439264">1. Companion Port</a></span></dt><dt><span class="section"><a href="#idp39443760">2. Companion SPI Protocol</a></span></dt><dt><span class="section"><a href="#idp39446656">3. SPI Message Formats</a></span></dt><dd><dl><dt><span class="section"><a href="#idp39447936">3.1. Command Message</a></span></dt><dt><span class="section"><a href="#idp38575392">3.2. SETUP reply message</a></span></dt><dt><span class="section"><a href="#idp38596928">3.3. FETCH reply message</a></span></dt></dl></dd><dt><span class="section"><a href="#idp44090368">4. History and Motivation</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp39439264"></a>1. Companion Port</h2></div></div></div><p>
8 Many Altus Metrum products come with an eight pin Micro MaTch
9 connector, called the Companion Port. This is often used to
10 program devices using a programming cable. However, it can also
11 be used to connect TeleMetrum to external companion boards
14 The Companion Port provides two different functions:
15 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
16 Power. Both battery-level and 3.3V regulated power are
17 available. Note that the amount of regulated power is not
18 huge; TeleMetrum contains a 150mA regulator and uses, at
19 peak, about 120mA or so. For applications needing more than
20 a few dozen mA, placing a separate regulator on them and
21 using the battery for power is probably a good idea.
22 </p></li><li class="listitem"><p>
23 SPI. The flight computer operates as a SPI master, using
24 a protocol defined in this document. Companion boards
25 provide a matching SPI slave implementation which supplies
26 telemetry information for the radio downlink during flight
27 </p></li></ul></div><p>
28 </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp39443760"></a>2. Companion SPI Protocol</h2></div></div></div><p>
29 The flight computer implements a SPI master communications
30 channel over the companion port, and uses this to get
31 information about a connected companion board and then to get
32 telemetry data for transmission during flight.
34 At startup time, the flight computer sends a setup request
35 packet, and the companion board returns a board identifier, the
36 desired telemetry update period and the number of data channels
37 provided. The flight computer doesn't interpret the telemetry
38 data at all, simply packing it up and sending it over the link.
39 Telemetry packets are 32 bytes long, and companion packets use 8
40 bytes as a header leaving room for a maximum of 12 16-bit data
43 Because of the limits of the AVR processors used in the first
44 two companion boards, the SPI data rate is set to 187.5kbaud.
45 </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp39446656"></a>3. SPI Message Formats</h2></div></div></div><p>
46 This section first defines the command message format sent from
47 the flight computer to the companion board, and then the various
48 reply message formats for each type of command message.
49 </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp39447936"></a>3.1. Command Message</h3></div></div></div><div class="table"><a name="idp39448608"></a><p class="title"><b>Table 1. Companion Command Message</b></p><div class="table-contents"><table summary="Companion Command Message" border="1"><colgroup><col align="center" class="Offset"><col align="center" class="Data Type"><col align="left" class="Name"><col align="left" class="Description"></colgroup><thead><tr><th align="center">Offset</th><th align="center">Data Type</th><th align="center">Name</th><th align="center">Description</th></tr></thead><tbody><tr><td align="center">0</td><td align="center">uint8_t</td><td align="left">command</td><td align="left">Command identifier</td></tr><tr><td align="center">1</td><td align="center">uint8_t</td><td align="left">flight_state</td><td align="left">Current flight computer state</td></tr><tr><td align="center">2</td><td align="center">uint16_t</td><td align="left">tick</td><td align="left">Flight computer clock (100 ticks/second)</td></tr><tr><td align="center">4</td><td align="center">uint16_t</td><td align="left">serial</td><td align="left">Flight computer serial number</td></tr><tr><td align="center">6</td><td align="center">uint16_t</td><td align="left">flight</td><td align="left">Flight number</td></tr><tr><td align="center">8</td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="idp38559312"></a><p class="title"><b>Table 2. Companion Command Identifiers</b></p><div class="table-contents"><table summary="Companion Command Identifiers" border="1"><colgroup><col align="center" class="Value"><col align="left" class="Name"><col align="left" class="Description"></colgroup><thead><tr><th align="center">Value</th><th align="left">Name</th><th align="left">Description</th></tr></thead><tbody><tr><td align="center">1</td><td align="left">SETUP</td><td align="left">Supply the flight computer with companion
50 information</td></tr><tr><td align="center">2</td><td align="left">FETCH</td><td align="left">Return telemetry information</td></tr><tr><td align="center">3</td><td align="left">NOTIFY</td><td align="left">Tell companion board when flight state
51 changes</td></tr></tbody></table></div></div><br class="table-break"><p>
52 The flight computer will send a SETUP message shortly after
53 power-up and will then send FETCH messages no more often than
54 the rate specified in the SETUP reply. NOTIFY messages will be
55 sent whenever the flight state changes.
57 'flight_state' records the current state of the flight,
58 whether on the pad, under power, coasting to apogee or
59 descending on the drogue or main chute.
61 'tick' provides the current flight computer clock, which
62 be used to synchronize data recorded on the flight computer
63 with that recorded on the companion board in post-flight analysis.
65 'serial' is the product serial number of the flight computer,
66 'flight' is the flight sequence number. Together, these two
67 uniquely identify the flight and can be recorded with any
68 companion board data logging to associate the companion data
69 with the proper flight.
71 NOTIFY commands require no reply at all, they are used solely
72 to inform the companion board when the state of the flight, as
73 computed by the flight computer, changes. Companion boards can
74 use this to change data collection parameters, disabling data
75 logging until the flight starts and terminating it when the
77 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp38575392"></a>3.2. SETUP reply message</h3></div></div></div><div class="table"><a name="idp38576064"></a><p class="title"><b>Table 3. SETUP reply contents</b></p><div class="table-contents"><table summary="SETUP reply contents" border="1"><colgroup><col align="center" class="Offset"><col align="center" class="Data Type"><col align="left" class="Name"><col align="left" class="Description"></colgroup><thead><tr><th align="center">Offset</th><th align="center">Data Type</th><th align="center">Name</th><th align="center">Description</th></tr></thead><tbody><tr><td align="center">0</td><td align="center">uint16_t</td><td align="left">board_id</td><td align="left">Board identifier</td></tr><tr><td align="center">2</td><td align="center">uint16_t</td><td align="left">board_id_inverse</td><td align="left">~board_id—used to tell if a board is present</td></tr><tr><td align="center">4</td><td align="center">uint8_t</td><td align="left">update_period</td><td align="left">Minimum time (in 100Hz ticks) between FETCH commands</td></tr><tr><td align="center">5</td><td align="center">uint8_t</td><td align="left">channels</td><td align="left">Number of data channels to retrieve in FETCH command</td></tr><tr><td align="center">6</td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break"><p>
78 The SETUP reply contains enough information to uniquely
79 identify the companion board to the end user as well as for
80 the flight computer to know how many data values to expect in
81 reply to a FETCH command, and how often to fetch that data.
83 To detect the presence of a companion board, the flight
84 computer checks to make sure that board_id_inverse is the
85 bit-wise inverse of board_id. Current companion boards use
86 USB product ID as the board_id, but the flight computer does
87 not interpret this data and so it can be any value.
88 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp38596928"></a>3.3. FETCH reply message</h3></div></div></div><div class="table"><a name="idp38597600"></a><p class="title"><b>Table 4. FETCH reply contents</b></p><div class="table-contents"><table summary="FETCH reply contents" border="1"><colgroup><col align="center" class="Offset"><col align="center" class="Data Type"><col align="left" class="Name"><col align="left" class="Description"></colgroup><thead><tr><th align="center">Offset</th><th align="center">Data Type</th><th align="center">Name</th><th align="center">Description</th></tr></thead><tbody><tr><td align="center">0</td><td align="center">uint16_t</td><td align="left">data0</td><td align="left">0th data item</td></tr><tr><td align="center">2</td><td align="center">uint16_t</td><td align="left">data1</td><td align="left">1st data item</td></tr><tr><td align="center">...</td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break"><p>
89 The FETCH reply contains arbitrary data to be reported over
90 the flight computer telemetry link. The number of 16-bit data items
91 must match the 'channels' value provided in the SETUP reply
93 </p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp44090368"></a>4. History and Motivation</h2></div></div></div><p>
94 To allow cross-programming, the original TeleMetrum and
95 TeleDongle designs needed to include some kind of
96 connector. With that in place, adding the ability to connect
97 external cards to TeleMetrum was fairly simple. We set the
98 software piece of this puzzle aside until we had a companion
101 The first companion board was TeleScience. Designed to collect
102 temperature data from the nose and fin of the airframe, the main
103 requirement for the companion port was that it be able to report
104 telemetry data during flight as a back-up in case the
105 TeleScience on-board data was lost.
107 The second companion board, TelePyro, provides 8 additional
108 channels for deployment, staging or other activities. To avoid
109 re-programming the TeleMetrum to use TelePyro, we decided to
110 provide enough information over the companion link for it to
111 independently control those channels.
113 Providing a standard, constant interface between the flight
114 computer and companion boards allows for the base flight
115 computer firmware to include support for companion boards.
116 </p></div></div></body></html>
projects / web / altusmetrum / blob