X-Git-Url: https://git.gag.com/?p=fw%2Faltos;a=blobdiff_plain;f=doc%2Fcompanion.xsl;fp=doc%2Fcompanion.xsl;h=0000000000000000000000000000000000000000;hp=14e2194e3bd26d5f5aee4ccab14ae545d01a788b;hb=22f399b13fbbc980315a1f6a9f5616586b680d77;hpb=14ad137fd14707bc7b45a3512a4a6f81915ca1c1 diff --git a/doc/companion.xsl b/doc/companion.xsl deleted file mode 100644 index 14e2194e..00000000 --- a/doc/companion.xsl +++ /dev/null @@ -1,353 +0,0 @@ - - - -
- - AltOS Companion Port - Protocol Definitions - - Keith - Packard - - - 2012 - Keith Packard - - - - This document is released under the terms of the - - Creative Commons ShareAlike 3.0 - - license. - - - - - 0.1 - 13 January 2012 - Initial content - - - -
- 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. - -
- Command Message - - Companion Command Message - - - - - - - - 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 - - - - - - - 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 - - - - - - - - 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 - - - - - - - - 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. - -
-