251 lines
6.6 KiB
Plaintext
251 lines
6.6 KiB
Plaintext
= AltOS Companion Port
|
|
Keith Packard <keithp@keithp.com>; Bdale Garbee <bdale@gag.com>
|
|
:doctype: article
|
|
:copyright: Bdale Garbee and Keith Packard 2018
|
|
:stylesheet: am.css
|
|
:linkcss:
|
|
:pdf-themesdir: .
|
|
:pdf-theme: altusmetrum
|
|
:pdf-fontsdir: fonts
|
|
:toc:
|
|
|
|
include::header.adoc[]
|
|
|
|
== Companion Port
|
|
|
|
Many Altus Metrum products come with an eight pin Micro MaTch
|
|
connector, called the Companion Port. This is often used to
|
|
program devices using a programming cable. However, it can
|
|
also be used to connect TeleMetrum to external companion
|
|
boards (hence the name).
|
|
|
|
The Companion Port provides two different functions:
|
|
|
|
* Power. Both battery-level and 3.3V regulated power are
|
|
available. Note that the amount of regulated power is not
|
|
huge; TeleMetrum contains a 150mA regulator and uses, at
|
|
peak, about 120mA or so. For applications needing more than
|
|
a few dozen mA, placing a separate regulator on them and
|
|
using the battery for power is probably a good idea.
|
|
|
|
|
|
* SPI. The flight computer operates as a SPI master, using
|
|
a protocol defined in this document. Companion boards
|
|
provide a matching SPI slave implementation which supplies
|
|
telemetry information for the radio downlink during flight
|
|
|
|
== Companion SPI Protocol
|
|
|
|
The flight computer implements a SPI master communications
|
|
channel over the companion port, and uses this to get
|
|
information about a connected companion board and then to get
|
|
telemetry data for transmission during flight.
|
|
|
|
At startup time, the flight computer sends a setup request
|
|
packet, and the companion board returns a board identifier,
|
|
the desired telemetry update period and the number of data
|
|
channels provided. The flight computer doesn't interpret the
|
|
telemetry data at all, simply packing it up and sending it
|
|
over the link. Telemetry packets are 32 bytes long, and
|
|
companion packets use 8 bytes as a header leaving room for a
|
|
maximum of 12 16-bit data values.
|
|
|
|
Because of the limits of the AVR processors used in the first
|
|
two companion boards, the SPI data rate is set to 187.5kbaud.
|
|
|
|
== SPI Message Formats
|
|
|
|
This section first defines the command message format sent from
|
|
the flight computer to the companion board, and then the various
|
|
reply message formats for each type of command message.
|
|
|
|
.Companion Command Message
|
|
[options="border",cols="1,3,3,9"]
|
|
|====
|
|
|Offset
|
|
|Data Type
|
|
|Name
|
|
|Description
|
|
|
|
|0
|
|
|uint8_t
|
|
|command
|
|
|Command identifier
|
|
|
|
|1
|
|
|uint8_t
|
|
|flight_state
|
|
|Current flight computer state
|
|
|
|
|2
|
|
|uint16_t
|
|
|tick
|
|
|Flight computer clock (100 ticks/second)
|
|
|
|
|4
|
|
|uint16_t
|
|
|serial
|
|
|Flight computer serial number
|
|
|
|
|6
|
|
|uint16_t
|
|
|flight
|
|
|Flight number
|
|
|
|
|8
|
|
|
|
|
|
|
|
|
|
|
|
|
|====
|
|
|
|
.Companion Command Identifiers
|
|
[options="border",cols="1,3,9"]
|
|
|====
|
|
|Value
|
|
|Name
|
|
|Description
|
|
|
|
|1
|
|
|SETUP
|
|
|Supply the flight computer with companion
|
|
information
|
|
|
|
|2
|
|
|FETCH
|
|
|Return telemetry information
|
|
|
|
|3
|
|
|NOTIFY
|
|
|Tell companion board when flight state changes
|
|
|====
|
|
|
|
The flight computer will send a SETUP message shortly after
|
|
power-up and will then send FETCH messages no more often than
|
|
the rate specified in the SETUP reply. NOTIFY messages will be
|
|
sent whenever the flight state changes.
|
|
|
|
'flight_state' records the current state of the flight,
|
|
whether on the pad, under power, coasting to apogee or
|
|
descending on the drogue or main chute.
|
|
|
|
'tick' provides the current flight computer clock, which
|
|
be used to synchronize data recorded on the flight computer
|
|
with that recorded on the companion board in post-flight analysis.
|
|
|
|
'serial' is the product serial number of the flight computer,
|
|
'flight' is the flight sequence number. Together, these two
|
|
uniquely identify the flight and can be recorded with any
|
|
companion board data logging to associate the companion data
|
|
with the proper flight.
|
|
|
|
NOTIFY commands require no reply at all, they are used solely
|
|
to inform the companion board when the state of the flight, as
|
|
computed by the flight computer, changes. Companion boards can
|
|
use this to change data collection parameters, disabling data
|
|
logging until the flight starts and terminating it when the
|
|
flight ends.
|
|
|
|
=== SETUP reply message
|
|
|
|
.SETUP reply contents
|
|
[options="border",cols="1,3,3,9"]
|
|
|====
|
|
|Offset
|
|
|Data Type
|
|
|Name
|
|
|Description
|
|
|
|
|0
|
|
|uint16_t
|
|
|board_id
|
|
|Board identifier
|
|
|
|
|2
|
|
|uint16_t
|
|
|board_id_inverse
|
|
|~board_id—used to tell if a board is present
|
|
|
|
|4
|
|
|uint8_t
|
|
|update_period
|
|
|Minimum time (in 100Hz ticks) between FETCH commands
|
|
|
|
|5
|
|
|uint8_t
|
|
|channels
|
|
|Number of data channels to retrieve in FETCH command
|
|
|
|
|6
|
|
|
|
|
|
|
|
|
|
|
|====
|
|
|
|
The SETUP reply contains enough information to uniquely
|
|
identify the companion board to the end user as well as for
|
|
the flight computer to know how many data values to expect in
|
|
reply to a FETCH command, and how often to fetch that data.
|
|
|
|
To detect the presence of a companion board, the flight
|
|
computer checks to make sure that board_id_inverse is the
|
|
bit-wise inverse of board_id. Current companion boards use
|
|
USB product ID as the board_id, but the flight computer does
|
|
not interpret this data and so it can be any value.
|
|
|
|
=== FETCH reply message
|
|
|
|
.FETCH reply contents
|
|
[options="border",cols="1,3,3,9"]
|
|
|====
|
|
|Offset
|
|
|Data Type
|
|
|Name
|
|
|Description
|
|
|
|
|0
|
|
|uint16_t
|
|
|data0
|
|
|0th data item
|
|
|
|
|2
|
|
|uint16_t
|
|
|data1
|
|
|1st data item
|
|
|
|
|...
|
|
|
|
|
|
|
|
|
|
|
|====
|
|
|
|
The FETCH reply contains arbitrary data to be reported
|
|
over the flight computer telemetry link. The number of
|
|
16-bit data items must match the 'channels' value
|
|
provided in the SETUP reply message.
|
|
|
|
== History and Motivation
|
|
|
|
To allow cross-programming, the original TeleMetrum and
|
|
TeleDongle designs needed to include some kind of
|
|
connector. With that in place, adding the ability to connect
|
|
external cards to TeleMetrum was fairly simple. We set the
|
|
software piece of this puzzle aside until we had a companion
|
|
board to use.
|
|
|
|
The first companion board was TeleScience. Designed to collect
|
|
temperature data from the nose and fin of the airframe, the main
|
|
requirement for the companion port was that it be able to report
|
|
telemetry data during flight as a back-up in case the
|
|
TeleScience on-board data was lost.
|
|
|
|
The second companion board, TelePyro, provides 8 additional
|
|
channels for deployment, staging or other activities. To avoid
|
|
re-programming the TeleMetrum to use TelePyro, we decided to
|
|
provide enough information over the companion link for it to
|
|
independently control those channels.
|
|
|
|
Providing a standard, constant interface between the flight
|
|
computer and companion boards allows for the base flight
|
|
computer firmware to include support for companion boards.
|