doc: Convert telemetry and companion docs to asciidoc

Signed-off-by: Keith Packard <keithp@keithp.com>

1 files changed, 571 insertions, 0 deletions

diff --git a/doc/telemetry.txt b/doc/telemetry.txt
new file mode 100644
index 00000000..36d2edba
--- /dev/null
+++ b/doc/telemetry.txt
@@ -0,0 +1,571 @@
+= AltOS Telemetry
+:doctype: article
+:toc:
+:numbered:
+
+== Packet Format Design
+
+	AltOS telemetry data is split into multiple different packets,
+	all the same size, but each includs an identifier so that the
+	ground station can distinguish among different types. A single
+	flight board will transmit multiple packet types, each type on
+	a different schedule. The ground software need look for only a
+	single packet size, and then decode the information within the
+	packet and merge data from multiple packets to construct the
+	full flight computer state.
+
+	Each AltOS packet is 32 bytes long. This size was chosen based
+	on the known telemetry data requirements. The power of two
+	size allows them to be stored easily in flash memory without
+	having them split across blocks or leaving gaps at the end.
+
+	All packet types start with a five byte header which encodes
+	the device serial number, device clock value and the packet
+	type. The remaining 27 bytes encode type-specific data.
+
+== Packet Formats
+
+      This section first defines the packet header common to all packets
+      and then the per-packet data layout.
+
+	=== Packet Header
+
+		.Telemetry Packet Header
+		[options="border",cols="2,3,3,9"]
+		|====
+		|Offset	|Data Type	|Name	|Description
+		|0	|uint16_t	|serial	|Device serial Number
+		|2	|uint16_t	|tick	|Device time in 100ths of a second
+		|4	|uint8_t	|type	|Packet type
+		|5
+		|====
+
+		Each packet starts with these five bytes which serve to identify
+		which device has transmitted the packet, when it was transmitted
+		and what the rest of the packet contains.
+
+	=== TeleMetrum v1.x, TeleMini and TeleNano Sensor Data
+
+		.Sensor Packet Type
+		[options="border",cols="1,3"]
+		|====
+		|Type	|Description
+		|0x01	|TeleMetrum v1.x Sensor Data
+		|0x02	|TeleMini Sensor Data
+		|0x03	|TeleNano Sensor Data
+		|====
+
+		TeleMetrum v1.x, TeleMini and TeleNano share this same
+		packet format for sensor data. Each uses a distinct
+		packet type so that the receiver knows which data
+		values are valid and which are undefined.
+
+		Sensor Data packets are transmitted once per second on
+		the ground, 10 times per second during ascent and once
+		per second during descent and landing
+
+		.Sensor Packet Contents
+		[options="border",cols="2,3,3,9"]
+		|====
+		|Offset	|Data Type	|Name		|Description
+		|5	|uint8_t	|state		|Flight state
+		|6	|int16_t	|accel		|accelerometer (TM only)
+		|8	|int16_t	|pres		|pressure sensor
+		|10	|int16_t	|temp		|temperature sensor
+		|12	|int16_t	|v_batt		|battery voltage
+		|14	|int16_t	|sense_d	|drogue continuity sense (TM/Tm)
+		|16	|int16_t	|sense_m	|main continuity sense (TM/Tm)
+		|18	|int16_t	|acceleration	|m/s² * 16
+		|20	|int16_t	|speed		|m/s * 16
+		|22	|int16_t	|height		|m
+		|24	|int16_t	|ground_pres	|Average barometer reading on ground
+		|26	|int16_t	|ground_accel	|TM
+		|28	|int16_t	|accel_plus_g	|TM
+		|30	|int16_t	|accel_minus_g	|TM
+		|32
+		|====
+
+	=== TeleMega Sensor Data
+
+		.TeleMega Packet Type
+		[options="border",cols="1,3"]
+		|====
+		|Type	|Description
+		|0x08	|TeleMega IMU Sensor Data
+		|0x09	|TeleMega Kalman and Voltage Data
+		|====
+
+		TeleMega has a lot of sensors, and so it splits the sensor
+		data into two packets. The raw IMU data are sent more often;
+		the voltage values don't change very fast, and the Kalman
+		values can be reconstructed from the IMU data.
+
+		IMU Sensor Data packets are transmitted once per second on the
+		ground, 10 times per second during ascent and once per second
+		during descent and landing
+
+		Kalman and Voltage Data packets are transmitted once per second on the
+		ground, 5 times per second during ascent and once per second
+		during descent and landing
+
+		The high-g accelerometer is reported separately from the data
+		for the 9-axis IMU (accel/gyro/mag). The 9-axis IMU is mounted
+		so that the X axis is "across" the board (along the short
+		axis0, the Y axis is "along" the board (along the long axis,
+		with the high-g accelerometer) and the Z axis is "through" the
+		board (perpendicular to the board). Rotation measurements are
+		around the respective axis, so Y rotation measures the spin
+		rate of the rocket while X and Z rotation measure the tilt
+		rate.
+
+		The overall tilt angle of the rocket is computed by first
+		measuring the orientation of the rocket on the pad using the 3
+		axis accelerometer, and then integrating the overall tilt rate
+		from the 3 axis gyroscope to compute the total orientation
+		change of the airframe since liftoff.
+
+		.TeleMega IMU Sensor Packet Contents
+		[options="border",cols="2,3,3,9"]
+		|====
+		|Offset	|Data Type	|Name		|Description
+		|5	|uint8_t	|orient		|Angle from vertical in degrees
+		|6	|int16_t	|accel		|High G accelerometer
+		|8	|int32_t	|pres		|pressure (Pa * 10)
+		|12	|int16_t	|temp		|temperature (°C * 100)
+		|14	|int16_t	|accel_x	|X axis acceleration (across)
+		|16	|int16_t	|accel_y	|Y axis acceleration (along)
+		|18	|int16_t	|accel_z	|Z axis acceleration (through)
+		|20	|int16_t	|gyro_x		|X axis rotation (across)
+		|22	|int16_t	|gyro_y		|Y axis rotation (along)
+		|24	|int16_t	|gyro_z		|Z axis rotation (through)
+		|26	|int16_t	|mag_x		|X field strength (across)
+		|28	|int16_t	|mag_y		|Y field strength (along)
+		|30	|int16_t	|mag_z		|Z field strength (through)
+		|32
+		|====
+
+		.TeleMega Kalman and Voltage Data Packet Contents
+		[options="border",cols="2,3,3,9"]
+		|====
+		|Offset	|Data Type	|Name		|Description
+		|5	|uint8_t	|state		|Flight state
+		|6	|int16_t	|v_batt		|battery voltage
+		|8	|int16_t	|v_pyro		|pyro battery voltage
+		|10	|int8_t[6]	|sense		|pyro continuity sense
+		|16	|int32_t	|ground_pres	|Average barometer reading on ground
+		|20	|int16_t	|ground_accel	|Average accelerometer reading on ground
+		|22	|int16_t	|accel_plus_g	|Accel calibration at +1g
+		|24	|int16_t	|accel_minus_g	|Accel calibration at -1g
+		|26	|int16_t	|acceleration	|m/s² * 16
+		|28	|int16_t	|speed		|m/s * 16
+		|30	|int16_t	|height		|m
+		|32
+		|====
+
+	=== TeleMetrum v2 Sensor Data
+
+		.TeleMetrum v2 Packet Type
+		[options="border",cols="1,3"]
+		|====
+		|Type	|Description
+		|0x0A	|TeleMetrum v2 Sensor Data
+		|0x0B	|TeleMetrum v2 Calibration Data
+		|====
+
+		TeleMetrum v2 has higher resolution barometric data than
+		TeleMetrum v1, and so the constant calibration data is
+		split out into a separate packet.
+
+		TeleMetrum v2 Sensor Data packets are transmitted once per second on the
+		ground, 10 times per second during ascent and once per second
+		during descent and landing
+
+		TeleMetrum v2 Calibration Data packets are always transmitted once per second.
+
+		.TeleMetrum v2 Sensor Packet Contents
+		[options="border",cols="2,3,3,9"]
+		|====
+		|Offset	|Data Type	|Name		|Description
+		|5	|uint8_t	|state		|Flight state
+		|6	|int16_t	|accel		|accelerometer
+		|8	|int32_t	|pres		|pressure sensor (Pa * 10)
+		|12	|int16_t	|temp		|temperature sensor (°C * 100)
+		|14	|int16_t	|acceleration	|m/s² * 16
+		|16	|int16_t	|speed		|m/s * 16
+		|18	|int16_t	|height		|m
+		|20	|int16_t	|v_batt		|battery voltage
+		|22	|int16_t	|sense_d	|drogue continuity sense
+		|24	|int16_t	|sense_m	|main continuity sense
+		|26	|pad[6]		|pad bytes	|
+		|32
+		|====
+
+		.TeleMetrum v2 Calibration Data Packet Contents
+		[options="border",cols="2,3,3,9"]
+		|====
+		|Offset	|Data Type	|Name		|Description
+		|5	|pad[3]		|pad bytes	|
+		|8	|int32_t	|ground_pres	|Average barometer reading on ground
+		|12	|int16_t	|ground_accel	|Average accelerometer reading on ground
+		|14	|int16_t	|accel_plus_g	|Accel calibration at +1g
+		|16	|int16_t	|accel_minus_g	|Accel calibration at -1g
+		|18	|pad[14]	|pad bytes	|
+		|32
+		|====
+
+	=== Configuration Data
+
+		.Configuration Packet Type
+		[options="border",cols="1,3"]
+		|====
+		|Type	|Description
+		|0x04	|Configuration Data
+		|====
+
+		This provides a description of the software installed on the
+		flight computer as well as any user-specified configuration data.
+
+		Configuration data packets are transmitted once per second
+		during all phases of the flight
+
+		.Configuration Packet Contents
+		[options="border",cols="2,3,3,9"]
+		|====
+		|Offset	|Data Type	|Name		|Description
+		|5	|uint8_t	|type		|Device type
+		|6	|uint16_t	|flight		|Flight number
+		|8	|uint8_t	|config_major	|Config major version
+		|9	|uint8_t	|config_minor	|Config minor version
+		|10	|uint16_t	|apogee_delay	|Apogee deploy delay in seconds
+		|12	|uint16_t	|main_deploy	|Main deploy alt in meters
+		|14	|uint16_t	|flight_log_max	|Maximum flight log size (kB)
+		|16	|char		|callsign[8]	|Radio operator identifier
+		|24	|char		|version[8]	|Software version identifier
+		|32
+		|====
+
+	=== GPS Location
+
+		.GPS Packet Type
+		[options="border",cols="1,3"]
+		|====
+		|Type	|Description
+		|0x05	|GPS Location
+		|====
+
+		This packet provides all of the information available from the
+		GPS receiver—position, time, speed and precision
+		estimates.
+
+		GPS Location packets are transmitted once per second during
+		all phases of the flight
+
+		.GPS Location Packet Contents
+		[options="border",cols="2,3,3,9"]
+		|====
+		|Offset	|Data Type	|Name		|Description
+		|5	|uint8_t	|flags		|See GPS Flags table below
+		|6	|int16_t	|altitude	|m
+		|8	|int32_t	|latitude	|degrees * 107
+		|12	|int32_t	|longitude	|degrees * 107
+		|16	|uint8_t	|year		|
+		|17	|uint8_t	|month		|
+		|18	|uint8_t	|day		|
+		|19	|uint8_t	|hour		|
+		|20	|uint8_t	|minute		|
+		|21	|uint8_t	|second		|
+		|22	|uint8_t	|pdop		|* 5
+		|23	|uint8_t	|hdop		|* 5
+		|24	|uint8_t	|vdop		|* 5
+		|25	|uint8_t	|mode		|See GPS Mode table below
+		|26	|uint16_t	|ground_speed	|cm/s
+		|28	|int16_t	|climb_rate	|cm/s
+		|30	|uint8_t	|course		|/ 2
+		|31	|uint8_t	|unused[1]	|
+		|32
+		|====
+
+		Packed into a one byte field are status flags and the
+		count of satellites used to compute the position
+		fix. Note that this number may be lower than the
+		number of satellites being tracked; the receiver will
+		not use information from satellites with weak signals
+		or which are close enough to the horizon to have
+		significantly degraded position accuracy.
+
+		.GPS Flags
+		[options="border",cols="1,2,7"]
+		|====
+		|Bits	|Name		|Description
+		|0-3	|nsats		|Number of satellites in solution
+		|4	|valid		|GPS solution is valid
+		|5	|running	|GPS receiver is operational
+		|6	|date_valid	|Reported date is valid
+		|7	|course_valid	|ground speed, course and climb rates are valid
+		|====
+
+		Here are all of the valid GPS operational modes. Altus
+		Metrum products will only ever report 'N' (not valid),
+		'A' (Autonomous) modes or 'E' (Estimated). The
+		remaining modes are either testing modes or require
+		additional data.
+
+		.GPS Mode
+		[options="border",cols="1,3,7"]
+		|====
+		|Mode		|Name			|Description
+		|N		|Not Valid		|All data are invalid
+		|A		|Autonomous mode	|
+		  Data are derived from satellite data
+
+		|D		|Differential Mode	|
+		  Data are augmented with differential data from a
+		  known ground station. The SkyTraq unit in TeleMetrum
+		  does not support this mode
+
+		|E		|Estimated		|
+		  Data are estimated using dead reckoning from the
+		  last known data
+
+		|M		|Manual			|
+		  Data were entered manually
+
+		|S		|Simulated		|
+		  GPS receiver testing mode
+
+		|====
+
+	=== GPS Satellite Data
+
+		.GPS Satellite Data Packet Type
+		[options="border",cols="1,3"]
+		|====
+		|Type		|Description
+		|0x06		|GPS Satellite Data
+		|====
+
+		This packet provides space vehicle identifiers and
+		signal quality information in the form of a C/N1
+		number for up to 12 satellites. The order of the svids
+		is not specified.
+
+		GPS Satellite data are transmitted once per second
+		during all phases of the flight.
+
+		.GPS Satellite Data Contents
+		[options="border",cols="2,3,3,9"]
+		|====
+		|Offset	|Data Type	|Name		|Description
+		|5	|uint8_t	|channels	|Number of reported satellite information
+		|6	|sat_info_t	|sats[12]	|See Per-Satellite data table below
+		|30	|uint8_t	|unused[2]	|
+		|32
+		|====
+
+		.GPS Per-Satellite data (sat_info_t)
+		[options="border",cols="2,3,3,9"]
+		|====
+		|Offset	|Data Type	|Name		|Description
+		|0	|uint8_t	|svid		|Space Vehicle Identifier
+		|1	|uint8_t	|c_n_1		|C/N1 signal quality indicator
+		|2
+		|====
+
+	=== Companion Data
+
+		.Companion Data Packet Type
+		[options="border",cols="1,3"]
+		|====
+		|Type	|Description
+		|0x07	|Companion Data
+		|====
+
+		When a companion board is attached to TeleMega or
+		TeleMetrum, it can provide telemetry data to be
+		included in the downlink. The companion board can
+		provide up to 12 16-bit data values.
+
+		The companion board itself specifies the transmission
+		rate. On the ground and during descent, that rate is
+		limited to one packet per second. During ascent, that
+		rate is limited to 10 packets per second.
+
+		.Companion Data Contents
+		[options="border",cols="2,3,3,9"]
+		|====
+		|Offset	|Data Type	|Name		|Description
+		|5	|uint8_t	|board_id	|Type of companion board attached
+		|6	|uint8_t	|update_period	|How often telemetry is sent, in 1/100ths of a second
+		|7	|uint8_t	|channels	|Number of data channels supplied
+		|8	|uint16_t[12]	|companion_data	|Up to 12 channels of 16-bit companion data
+		|32
+		|====
+
+== Data Transmission
+
+	Altus Metrum devices use Texas Instruments sub-GHz digital
+	radio products. Ground stations use parts with HW FEC while
+	some flight computers perform FEC in software. TeleGPS is
+	transmit-only.
+
+	.Altus Metrum Radio Parts
+	[options="border",cols="1,4,4"]
+	|====
+	|Part Number	|Description	|Used in
+
+	|CC1111
+	|10mW transceiver with integrated SoC
+	|TeleDongle v0.2, TeleBT v1.0, TeleMetrum v1.x, TeleMini
+
+	|CC1120
+	|35mW transceiver with SW FEC
+	|TeleMetrum v2, TeleMega
+
+	|CC1200
+	|35mW transceiver with HW FEC
+	|TeleDongle v3.0, TeleBT v3.0
+
+	|CC115L
+	|14mW transmitter with SW FEC
+	|TeleGPS
+
+	|====
+
+	=== Modulation Scheme
+
+		Texas Instruments provides a tool for computing
+		modulation parameters given a desired modulation
+		format and basic bit rate.
+
+		While we might like to use something with better
+		low-signal performance like BPSK, the radios we use
+		don't support that, but do support Gaussian frequency
+		shift keying (GFSK). Regular frequency shift keying
+		(FSK) encodes the signal by switching the carrier
+		between two frequencies. The Gaussian version is
+		essentially the same, but the shift between
+		frequencies gently follows a gaussian curve, rather
+		than switching immediately. This tames the bandwidth
+		of the signal without affecting the ability to
+		transmit data.
+
+		For AltOS, there are three available bit rates,
+		38.4kBaud, 9.6kBaud and 2.4kBaud resulting in the
+		following signal parmeters:
+
+		.Modulation Scheme
+		[options="border",cols="1,1,1"]
+		|====
+		|Rate		|Deviation	|Receiver Bandwidth
+		|38.4kBaud	|20.5kHz	|100kHz
+		|9.6kBaud	|5.125kHz	|25kHz
+		|2.4kBaud	|1.5kHz		|5kHz
+		|====
+
+	=== Error Correction
+
+		The cc1111 and cc1200 provide forward error correction
+		in hardware; on the cc1120 and cc115l that's done in
+		software. AltOS uses this to improve reception of weak
+		signals. As it's a rate 1/2 encoding, each bit of data
+		takes two bits when transmitted, so the effective data
+		rate is half of the raw transmitted bit rate.
+
+		.Error Correction
+		[options="border",cols="1,1,1"]
+		|====
+		|Parameter	|Value	|Description
+
+		|Error Correction
+		|Convolutional coding
+		|1/2 rate, constraint length m=4
+
+		|Interleaving
+		|4 x 4
+		|Reduce effect of noise burst
+
+		|Data Whitening
+		|XOR with 9-bit PNR
+		|Rotate right with bit 8 = bit 0 xor bit 5, initial value 111111111
+
+		|====
+
+== TeleDongle serial packet format
+
+	TeleDongle does not do any interpretation of the packet data,
+	instead it is configured to receive packets of a specified
+	length (32 bytes in this case). For each received packet,
+	TeleDongle produces a single line of text. This line starts with
+	the string "TELEM " and is followed by a list of hexadecimal
+	encoded bytes.
+
+	....
+	TELEM 224f01080b05765e00701f1a1bbeb8d7b60b070605140c000600000000000000003fa988
+	....
+
+	The hexadecimal encoded string of bytes contains a length byte,
+	the packet data, two bytes added by the cc1111 radio receiver
+	hardware and finally a checksum so that the host software can
+	validate that the line was transmitted without any errors.
+
+	.TeleDongle serial Packet Format
+
+	[options="border",cols="2,1,1,5"]
+	|====
+	|Offset	|Name	|Example	|Description
+
+	|0
+	|length
+	|22
+	|Total length of data bytes in the line. Note that
+	 this includes the added RSSI and status bytes
+
+	|1 ·· length-3
+	|packet
+	|4f ·· 00
+	|Bytes of actual packet data
+
+	|length-2
+	|rssi
+	|3f
+	|Received signal strength. dBm = rssi / 2 - 74
+
+	|length-1
+	|lqi
+	|a9
+	|Link Quality Indicator and CRC status. Bit 7
+	 is set when the CRC is correct
+
+	|length
+	|checksum
+	|88
+	|(0x5a + sum(bytes 1 ·· length-1)) % 256
+
+	|====
+
+== History and Motivation
+
+      The original AltoOS telemetry mechanism encoded everything
+      available piece of information on the TeleMetrum hardware into a
+      single unified packet. Initially, the packets contained very
+      little data—some raw sensor readings along with the current GPS
+      coordinates when a GPS receiver was connected. Over time, the
+      amount of data grew to include sensor calibration data, GPS
+      satellite information and a host of internal state information
+      designed to help diagnose flight failures in case of a loss of
+      the on-board flight data.
+
+      Because every packet contained all of the data, packets were
+      huge—95 bytes long. Much of the information was also specific to
+      the TeleMetrum hardware. With the introduction of the TeleMini
+      flight computer, most of the data contained in the telemetry
+      packets was unavailable. Initially, a shorter, but still
+      comprehensive packet was implemented. This required that the
+      ground station be pre-configured as to which kind of packet to
+      expect.
+
+      The development of several companion boards also made the
+      shortcomings evident—each companion board would want to include
+      telemetry data in the radio link; with the original design, the
+      packet would have to hold the new data as well, requiring
+      additional TeleMetrum and ground station changes.