From: Keith Packard Date: Sat, 2 Jul 2011 08:50:33 +0000 (-0700) Subject: doc: Add telemetry format description X-Git-Tag: 0.9.4.3~45 X-Git-Url: https://git.gag.com/?p=fw%2Faltos;a=commitdiff_plain;h=06e82bd2c2a5eea153a053e542df9bc3537e9a01 doc: Add telemetry format description Document the telemetry packet contents. Signed-off-by: Keith Packard --- diff --git a/doc/Makefile b/doc/Makefile index 80c84409..b431f4ca 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -2,8 +2,8 @@ # http://docbook.sourceforge.net/release/xsl/current/README # -HTML=altusmetrum.html altos.html -PDF=altusmetrum.pdf altos.pdf +HTML=altusmetrum.html altos.html telemetry.html +PDF=altusmetrum.pdf altos.pdf telemetry.pdf DOC=$(HTML) $(PDF) HTMLSTYLE=/usr/share/xml/docbook/stylesheet/docbook-xsl/html/docbook.xsl FOSTYLE=/usr/share/xml/docbook/stylesheet/docbook-xsl/fo/docbook.xsl @@ -11,11 +11,13 @@ PDFSTYLE= .SUFFIXES: .xsl .html .fo .pdf +XSLTFLAGS=--stringparam section.autolabel 1 + .xsl.html: - xsltproc -o $@ $(HTMLSTYLE) $*.xsl + xsltproc $(XSLTFLAGS) -o $@ $(HTMLSTYLE) $*.xsl .xsl.fo: - xsltproc -o $@ $(FOSTYLE) $*.xsl + xsltproc $(XSLTFLAGS) -o $@ $(FOSTYLE) $*.xsl .fo.pdf: fop -fo $*.fo -pdf $@ diff --git a/doc/telemetry.xsl b/doc/telemetry.xsl new file mode 100644 index 00000000..8f0c3ff0 --- /dev/null +++ b/doc/telemetry.xsl @@ -0,0 +1,572 @@ + + + +
+ + AltOS Telemetry + Packet Definitions + + Keith + Packard + + + 2011 + Keith Packard + + + + This document is released under the terms of the + + Creative Commons ShareAlike 3.0 + + license. + + + + + 0.1 + 01 July 2011 + Initial content + + + +
+ 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. + +
+
+ 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 + + + + + + + + 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. + +
+
+ Sensor Data + + + + + + + Type + Description + + + + + 0x01 + TeleMetrum Sensor Data + + + 0x02 + TeleMini Sensor Data + + + 0x03 + TeleNano Sensor Data + + + + + + TeleMetrum, 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 Packet Contents + + + + + + + + Offset + Data Type + Name + Description + + + + + 5uint8_tstateFlight state + + + 6int16_taccelaccelerometer (TM only) + + + 8int16_tprespressure sensor + + + 10int16_ttemptemperature sensor + + + 12int16_tv_battbattery voltage + + + 14int16_tsense_ddrogue continuity sense (TM/Tm) + + + 16int16_tsense_mmain continuity sense (TM/Tm) + + + 18int16_taccelm/s² * 16 + + + 20int16_tspeedm/s * 16 + + + 22int16_theightm + + + 24int16_tground_accelTM + + + 26int16_tground_presAverage barometer reading on ground + + + 28int16_taccel_plus_gTM + + + 30int16_taccel_minus_gTM + + + 32 + + + +
+
+
+ Configuration Data + + + + + + + Type + Description + + + + + 0x04 + Configuration Data + + + + + + Sensor Packet Contents + + + + + + + + Offset + Data Type + Name + Description + + + + + 5uint8_ttypeDevice type + + + 6uint16_tflightFlight number + + + 8uint8_tconfig_majorConfig major version + + + 9uint8_tconfig_minorConfig minor version + + + 10uint16_tmain_deployMain deploy alt in meters + + + 12uint32_tflight_log_maxMaximum flight log size (B) + + + 16charcallsign[8]Radio operator identifier + + + 24charversion[8]Software version identifier + + + 32 + + + +
+
+
+ GPS Location + + + + + + + Type + Description + + + + + 0x05 + GPS Location + + + + + + GPS Location Packet Contents + + + + + + + + Offset + Data Type + Name + Description + + + + + 5uint8_tflagsGPS Flags (see below) + + + 6int16_taltitudem + + + 8int32_tlatitudedegrees * 107 + + + 12int32_tlongitudedegrees * 107 + + + 16uint8_tyear + + + 17uint8_tmonth + + + 18uint8_tday + + + 19uint8_thour + + + 20uint8_tminute + + + 21uint8_tsecond + + + 22uint8_tpdop* 5 + + + 23uint8_thdop* 5 + + + 24uint8_tvdop* 5 + + + 25uint8_tmodeN, A, D, E, M, S + + + 26uint16_tground_speedcm/s + + + 28uint8_tcourse/ 2 + + + 29uint8_tunused[2] + + + 32 + + + +
+
+
+ GPS Satellite Data + + + + + + + Type + Description + + + + + 0x06 + GPS Satellite Data + + + + + + GPS Satellite Data Contents + + + + + + + + Offset + Data Type + Name + Description + + + + + 5uint8_tchannels + + + 6uint8_tsat_0_id + + + 7uint8_tsat_0_c_n_1 + + + 8uint8_tsat_1_id + + + 9uint8_tsat_1_c_n_1 + + + 10uint8_tsat_2_id + + + 11uint8_tsat_2_c_n_1 + + + 12uint8_tsat_3_id + + + 13uint8_tsat_3_c_n_1 + + + 14uint8_tsat_4_id + + + 15uint8_tsat_4_c_n_1 + + + 16uint8_tsat_5_id + + + 17uint8_tsat_5_c_n_1 + + + 18uint8_tsat_6_id + + + 19uint8_tsat_6_c_n_1 + + + 20uint8_tsat_7_id + + + 21uint8_tsat_7_c_n_1 + + + 22uint8_tsat_8_id + + + 23uint8_tsat_8_c_n_1 + + + 24uint8_tsat_9_id + + + 25uint8_tsat_9_c_n_1 + + + 26uint8_tsat_10_id + + + 27uint8_tsat_10_c_n_1 + + + 28uint8_tsat_11_id + + + 29uint8_tsat_11_c_n_1 + + + 30uin8_tunused30 + + + 31uin8_tunused31 + + + 32 + + + +
+
+
+
+ + \ No newline at end of file