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

   1 = AltOS Companion Port
   2 :doctype: article
   3 :toc:
   4
   5 == Companion Port
   6
   7         Many Altus Metrum products come with an eight pin Micro MaTch
   8         connector, called the Companion Port. This is often used to
   9         program devices using a programming cable. However, it can
  10         also be used to connect TeleMetrum to external companion
  11         boards (hence the name).
  12
  13         The Companion Port provides two different functions:
  14
  15         * Power. Both battery-level and 3.3V regulated power are
  16           available. Note that the amount of regulated power is not
  17           huge; TeleMetrum contains a 150mA regulator and uses, at
  18           peak, about 120mA or so. For applications needing more than
  19           a few dozen mA, placing a separate regulator on them and
  20           using the battery for power is probably a good idea.
  21
  22
  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
  28 == Companion SPI Protocol
  29
  30         The flight computer implements a SPI master communications
  31         channel over the companion port, and uses this to get
  32         information about a connected companion board and then to get
  33         telemetry data for transmission during flight.
  34
  35         At startup time, the flight computer sends a setup request
  36         packet, and the companion board returns a board identifier,
  37         the desired telemetry update period and the number of data
  38         channels provided. The flight computer doesn't interpret the
  39         telemetry data at all, simply packing it up and sending it
  40         over the link.  Telemetry packets are 32 bytes long, and
  41         companion packets use 8 bytes as a header leaving room for a
  42         maximum of 12 16-bit data values.
  43
  44         Because of the limits of the AVR processors used in the first
  45         two companion boards, the SPI data rate is set to 187.5kbaud.
  46
  47 == SPI Message Formats
  48
  49         This section first defines the command message format sent from
  50         the flight computer to the companion board, and then the various
  51         reply message formats for each type of command message.
  52
  53         .Companion Command Message
  54         [options="border",cols="1,3,3,9"]
  55         |====
  56         |Offset
  57         |Data Type
  58         |Name
  59         |Description
  60
  61         |0
  62         |uint8_t
  63         |command
  64         |Command identifier
  65
  66         |1
  67         |uint8_t
  68         |flight_state
  69         |Current flight computer state
  70
  71         |2
  72         |uint16_t
  73         |tick
  74         |Flight computer clock (100 ticks/second)
  75
  76         |4
  77         |uint16_t
  78         |serial
  79         |Flight computer serial number
  80
  81         |6
  82         |uint16_t
  83         |flight
  84         |Flight number
  85
  86         |8
  87         |
  88         |
  89         |
  90
  91         |====
  92
  93         .Companion Command Identifiers
  94         [options="border",cols="1,3,9"]
  95         |====
  96         |Value
  97         |Name
  98         |Description
  99
 100         |1
 101         |SETUP
 102         |Supply the flight computer with companion
 103         information
 104
 105         |2
 106         |FETCH
 107         |Return telemetry information
 108
 109         |3
 110         |NOTIFY
 111         |Tell companion board when flight state changes
 112         |====
 113
 114         The flight computer will send a SETUP message shortly after
 115         power-up and will then send FETCH messages no more often than
 116         the rate specified in the SETUP reply. NOTIFY messages will be
 117         sent whenever the flight state changes.
 118
 119         'flight_state' records the current state of the flight,
 120         whether on the pad, under power, coasting to apogee or
 121         descending on the drogue or main chute.
 122
 123         'tick' provides the current flight computer clock, which
 124         be used to synchronize data recorded on the flight computer
 125         with that recorded on the companion board in post-flight analysis.
 126
 127         'serial' is the product serial number of the flight computer,
 128         'flight' is the flight sequence number. Together, these two
 129         uniquely identify the flight and can be recorded with any
 130         companion board data logging to associate the companion data
 131         with the proper flight.
 132
 133         NOTIFY commands require no reply at all, they are used solely
 134         to inform the companion board when the state of the flight, as
 135         computed by the flight computer, changes. Companion boards can
 136         use this to change data collection parameters, disabling data
 137         logging until the flight starts and terminating it when the
 138         flight ends.
 139
 140         === SETUP reply message
 141
 142                 .SETUP reply contents
 143                 [options="border",cols="1,3,3,9"]
 144                 |====
 145                 |Offset
 146                 |Data Type
 147                 |Name
 148                 |Description
 149
 150                 |0
 151                 |uint16_t
 152                 |board_id
 153                 |Board identifier
 154
 155                 |2
 156                 |uint16_t
 157                 |board_id_inverse
 158                 |~board_id—used to tell if a board is present
 159
 160                 |4
 161                 |uint8_t
 162                 |update_period
 163                 |Minimum time (in 100Hz ticks) between FETCH commands
 164
 165                 |5
 166                 |uint8_t
 167                 |channels
 168                 |Number of data channels to retrieve in FETCH command
 169
 170                 |6
 171                 |
 172                 |
 173                 |
 174                 |====
 175
 176                 The SETUP reply contains enough information to uniquely
 177                 identify the companion board to the end user as well as for
 178                 the flight computer to know how many data values to expect in
 179                 reply to a FETCH command, and how often to fetch that data.
 180
 181                 To detect the presence of a companion board, the flight
 182                 computer checks to make sure that board_id_inverse is the
 183                 bit-wise inverse of board_id. Current companion boards use
 184                 USB product ID as the board_id, but the flight computer does
 185                 not interpret this data and so it can be any value.
 186
 187         === FETCH reply message
 188
 189                 .FETCH reply contents
 190                 [options="border",cols="1,3,3,9"]
 191                 |====
 192                 |Offset
 193                 |Data Type
 194                 |Name
 195                 |Description
 196
 197                 |0
 198                 |uint16_t
 199                 |data0
 200                 |0th data item
 201
 202                 |2
 203                 |uint16_t
 204                 |data1
 205                 |1st data item
 206
 207                 |...
 208                 |
 209                 |
 210                 |
 211                 |====
 212
 213                 The FETCH reply contains arbitrary data to be reported
 214                 over the flight computer telemetry link. The number of
 215                 16-bit data items must match the 'channels' value
 216                 provided in the SETUP reply message.
 217
 218 == History and Motivation
 219
 220         To allow cross-programming, the original TeleMetrum and
 221         TeleDongle designs needed to include some kind of
 222         connector. With that in place, adding the ability to connect
 223         external cards to TeleMetrum was fairly simple. We set the
 224         software piece of this puzzle aside until we had a companion
 225         board to use.
 226
 227         The first companion board was TeleScience. Designed to collect
 228         temperature data from the nose and fin of the airframe, the main
 229         requirement for the companion port was that it be able to report
 230         telemetry data during flight as a back-up in case the
 231         TeleScience on-board data was lost.
 232
 233         The second companion board, TelePyro, provides 8 additional
 234         channels for deployment, staging or other activities. To avoid
 235         re-programming the TeleMetrum to use TelePyro, we decided to
 236         provide enough information over the companion link for it to
 237         independently control those channels.
 238
 239         Providing a standard, constant interface between the flight
 240         computer and companion boards allows for the base flight
 241         computer firmware to include support for companion boards.