git.gag.com Git - fw/altos/blob - doc/companion.txt

   1 = AltOS Companion Port
   2 Keith Packard <keithp@keithp.com>; Bdale Garbee <bdale@gag.com>
   3 :doctype: article
   4 :copyright: Bdale Garbee and Keith Packard 2018
   5 :stylesheet: am.css
   6 :linkcss:
   7 :pdf-stylesdir: .
   8 :pdf-style: altusmetrum
   9 :pdf-fontsdir: fonts
  10 :toc:
  11
  12         include::header.adoc[]
  13
  14 == Companion Port
  15
  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).
  21
  22         The Companion Port provides two different functions:
  23
  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.
  30
  31
  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
  36
  37 == Companion SPI Protocol
  38
  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.
  43
  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.
  52
  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.
  55
  56 == SPI Message Formats
  57
  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.
  61
  62         .Companion Command Message
  63         [options="border",cols="1,3,3,9"]
  64         |====
  65         |Offset
  66         |Data Type
  67         |Name
  68         |Description
  69
  70         |0
  71         |uint8_t
  72         |command
  73         |Command identifier
  74
  75         |1
  76         |uint8_t
  77         |flight_state
  78         |Current flight computer state
  79
  80         |2
  81         |uint16_t
  82         |tick
  83         |Flight computer clock (100 ticks/second)
  84
  85         |4
  86         |uint16_t
  87         |serial
  88         |Flight computer serial number
  89
  90         |6
  91         |uint16_t
  92         |flight
  93         |Flight number
  94
  95         |8
  96         |
  97         |
  98         |
  99
 100         |====
 101
 102         .Companion Command Identifiers
 103         [options="border",cols="1,3,9"]
 104         |====
 105         |Value
 106         |Name
 107         |Description
 108
 109         |1
 110         |SETUP
 111         |Supply the flight computer with companion
 112         information
 113
 114         |2
 115         |FETCH
 116         |Return telemetry information
 117
 118         |3
 119         |NOTIFY
 120         |Tell companion board when flight state changes
 121         |====
 122
 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.
 127
 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.
 131
 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.
 135
 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.
 141
 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
 147         flight ends.
 148
 149         === SETUP reply message
 150
 151                 .SETUP reply contents
 152                 [options="border",cols="1,3,3,9"]
 153                 |====
 154                 |Offset
 155                 |Data Type
 156                 |Name
 157                 |Description
 158
 159                 |0
 160                 |uint16_t
 161                 |board_id
 162                 |Board identifier
 163
 164                 |2
 165                 |uint16_t
 166                 |board_id_inverse
 167                 |~board_id—used to tell if a board is present
 168
 169                 |4
 170                 |uint8_t
 171                 |update_period
 172                 |Minimum time (in 100Hz ticks) between FETCH commands
 173
 174                 |5
 175                 |uint8_t
 176                 |channels
 177                 |Number of data channels to retrieve in FETCH command
 178
 179                 |6
 180                 |
 181                 |
 182                 |
 183                 |====
 184
 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.
 189
 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.
 195
 196         === FETCH reply message
 197
 198                 .FETCH reply contents
 199                 [options="border",cols="1,3,3,9"]
 200                 |====
 201                 |Offset
 202                 |Data Type
 203                 |Name
 204                 |Description
 205
 206                 |0
 207                 |uint16_t
 208                 |data0
 209                 |0th data item
 210
 211                 |2
 212                 |uint16_t
 213                 |data1
 214                 |1st data item
 215
 216                 |...
 217                 |
 218                 |
 219                 |
 220                 |====
 221
 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.
 226
 227 == History and Motivation
 228
 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
 234         board to use.
 235
 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.
 241
 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.
 247
 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.