doc: Complete initial telemetry description

Finish describing the contents and modulation scheme for telemetry
data.

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

diff --git a/doc/telemetry.xsl b/doc/telemetry.xsl
index 8f0c3ff0a3081d0b60ca437385bfa5980181d11a..d2b17126743457df94f5f4644db92ca5c8dfdaed 100644 (file)
--- a/doc/telemetry.xsl
+++ b/doc/telemetry.xsl
@@ -31,37 +31,6 @@
       </revision>
     </revhistory>
   </articleinfo>
       </revision>
     </revhistory>
   </articleinfo>

-  <section>
-    <title>History and Motivation</title>
-    <para>
-      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.
-    </para>
-    <para>
-      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.
-    </para>
-    <para>
-      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.
-    </para>
-  </section>

   <section>
     <title>Packet Format Design</title>
     <para>
   <section>
     <title>Packet Format Design</title>
     <para>


@@ -95,7 +64,7 @@
       <table frame='all'>
        <title>Telemetry Packet Header</title>
        <tgroup cols='4' align='center' colsep='1' rowsep='1'>
       <table frame='all'>
        <title>Telemetry Packet Header</title>
        <tgroup cols='4' align='center' colsep='1' rowsep='1'>

-         <colspec align='right' colwidth='*' colname='Offset'/>
+         <colspec align='center' colwidth='*' colname='Offset'/>

          <colspec align='center' colwidth='3*' colname='Data Type'/>
          <colspec align='left' colwidth='3*' colname='Name'/>
          <colspec align='left' colwidth='9*' colname='Description'/>
          <colspec align='center' colwidth='3*' colname='Data Type'/>
          <colspec align='left' colwidth='3*' colname='Name'/>
          <colspec align='left' colwidth='9*' colname='Description'/>


@@ -172,10 +141,15 @@
        that the receiver knows which data values are valid and which
        are undefined.
       </para>
        that the receiver knows which data values are valid and which
        are undefined.
       </para>

+      <para>
+       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
+      </para>

       <table frame='all'>
        <title>Sensor Packet Contents</title>
        <tgroup cols='4' align='center' colsep='1' rowsep='1'>
       <table frame='all'>
        <title>Sensor Packet Contents</title>
        <tgroup cols='4' align='center' colsep='1' rowsep='1'>

-         <colspec align='right' colwidth='*' colname='Offset'/>
+         <colspec align='center' colwidth='*' colname='Offset'/>

          <colspec align='center' colwidth='3*' colname='Data Type'/>
          <colspec align='left' colwidth='3*' colname='Name'/>
          <colspec align='left' colwidth='9*' colname='Description'/>
          <colspec align='center' colwidth='3*' colname='Data Type'/>
          <colspec align='left' colwidth='3*' colname='Name'/>
          <colspec align='left' colwidth='9*' colname='Description'/>


@@ -257,10 +231,18 @@
          </tbody>
        </tgroup>
       </informaltable>
          </tbody>
        </tgroup>
       </informaltable>

+      <para>
+       This provides a description of the software installed on the
+       flight computer as well as any user-specified configuration data.
+      </para>
+      <para>
+       Configuration data packets are transmitted once per second
+       during all phases of the flight
+      </para>

       <table frame='all'>
        <title>Sensor Packet Contents</title>
        <tgroup cols='4' align='center' colsep='1' rowsep='1'>
       <table frame='all'>
        <title>Sensor Packet Contents</title>
        <tgroup cols='4' align='center' colsep='1' rowsep='1'>

-         <colspec align='right' colwidth='*' colname='Offset'/>
+         <colspec align='center' colwidth='*' colname='Offset'/>

          <colspec align='center' colwidth='3*' colname='Data Type'/>
          <colspec align='left' colwidth='3*' colname='Name'/>
          <colspec align='left' colwidth='9*' colname='Description'/>
          <colspec align='center' colwidth='3*' colname='Data Type'/>
          <colspec align='left' colwidth='3*' colname='Name'/>
          <colspec align='left' colwidth='9*' colname='Description'/>


@@ -324,10 +306,19 @@
          </tbody>
        </tgroup>
       </informaltable>
          </tbody>
        </tgroup>
       </informaltable>

+      <para>
+       This packet provides all of the information available from the
+       Venus SkyTraq GPS receiver—position, time, speed and precision
+       estimates. 
+      </para>
+      <para>
+       GPS Location packets are transmitted once per second during
+       all phases of the flight
+      </para>

       <table frame='all'>
        <title>GPS Location Packet Contents</title>
        <tgroup cols='4' align='center' colsep='1' rowsep='1'>
       <table frame='all'>
        <title>GPS Location Packet Contents</title>
        <tgroup cols='4' align='center' colsep='1' rowsep='1'>

-         <colspec align='right' colwidth='*' colname='Offset'/>
+         <colspec align='center' colwidth='*' colname='Offset'/>

          <colspec align='center' colwidth='3*' colname='Data Type'/>
          <colspec align='left' colwidth='3*' colname='Name'/>
          <colspec align='left' colwidth='9*' colname='Description'/>
          <colspec align='center' colwidth='3*' colname='Data Type'/>
          <colspec align='left' colwidth='3*' colname='Name'/>
          <colspec align='left' colwidth='9*' colname='Description'/>


@@ -341,7 +332,8 @@
          </thead>
          <tbody>
            <row>
          </thead>
          <tbody>
            <row>

-             <entry>5</entry><entry>uint8_t</entry><entry>flags</entry><entry>GPS Flags (see below)</entry>
+             <entry>5</entry><entry>uint8_t</entry><entry>flags</entry>
+             <entry>See GPS Flags table below</entry>

            </row>
            <row>
              <entry>6</entry><entry>int16_t</entry><entry>altitude</entry><entry>m</entry>
            </row>
            <row>
              <entry>6</entry><entry>int16_t</entry><entry>altitude</entry><entry>m</entry>


@@ -380,7 +372,8 @@
              <entry>24</entry><entry>uint8_t</entry><entry>vdop</entry><entry>* 5</entry>
            </row>
            <row>
              <entry>24</entry><entry>uint8_t</entry><entry>vdop</entry><entry>* 5</entry>
            </row>
            <row>

-             <entry>25</entry><entry>uint8_t</entry><entry>mode</entry><entry>N, A, D, E, M, S</entry>
+             <entry>25</entry><entry>uint8_t</entry><entry>mode</entry>
+             <entry>See GPS Mode table below</entry>

            </row>
            <row>
              <entry>26</entry><entry>uint16_t</entry><entry>ground_speed</entry><entry>cm/s</entry>
            </row>
            <row>
              <entry>26</entry><entry>uint16_t</entry><entry>ground_speed</entry><entry>cm/s</entry>


@@ -389,7 +382,7 @@
              <entry>28</entry><entry>uint8_t</entry><entry>course</entry><entry>/ 2</entry>
            </row>
            <row>
              <entry>28</entry><entry>uint8_t</entry><entry>course</entry><entry>/ 2</entry>
            </row>
            <row>

-             <entry>29</entry><entry>uint8_t</entry><entry>unused[2]</entry>
+             <entry>29</entry><entry>uint8_t</entry><entry>unused[3]</entry>

            </row>
            <row>
              <entry>32</entry>
            </row>
            <row>
              <entry>32</entry>


@@ -397,6 +390,116 @@
          </tbody>
        </tgroup>
       </table>
          </tbody>
        </tgroup>
       </table>

+      <para>
+       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.
+      </para>
+      <table frame='all'>
+       <title>GPS Flags</title>
+       <tgroup cols='3' colsep='1' rowsep='1'>
+         <colspec align='center' colwidth='*' colname='bits'/>
+         <colspec align='left' colwidth='2*' colname='name'/>
+         <colspec align='left' colwidth='7*' colname='description'/>
+         <thead>
+           <row>
+             <entry align='center'>Bits</entry>
+             <entry align='center'>Name</entry>
+             <entry align='center'>Description</entry>
+           </row>
+         </thead>
+         <tbody>
+           <row>
+             <entry>0-3</entry>
+             <entry>nsats</entry>
+             <entry>Number of satellites in solution</entry>
+           </row>
+           <row>
+             <entry>4</entry>
+             <entry>valid</entry>
+             <entry>GPS solution is valid</entry>
+           </row>
+           <row>
+             <entry>5</entry>
+             <entry>running</entry>
+             <entry>GPS receiver is operational</entry>
+           </row>
+           <row>
+             <entry>6</entry>
+             <entry>date_valid</entry>
+             <entry>Reported date is valid</entry>
+           </row>
+           <row>
+             <entry>7</entry>
+             <entry>course_valid</entry>
+             <entry>ground speed, course and climb rates are valid</entry>
+           </row>
+         </tbody>
+       </tgroup>
+      </table>
+      <para>
+       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.
+      </para>
+      <table frame='all'>
+       <title>GPS Mode</title>
+       <tgroup cols='3' colsep='1' rowsep='1'>
+         <colspec align='center' colwidth='*' colname='value'/>
+         <colspec align='center' colwidth='3*' colname='name'/>
+         <colspec align='left' colwidth='7*' colname='description'/>
+         <thead>
+           <row>
+             <entry align='center'>Mode</entry>
+             <entry align='center'>Name</entry>
+             <entry align='center'>Decsription</entry>
+           </row>
+         </thead>
+         <tbody>
+           <row>
+             <entry>N</entry>
+             <entry>Not Valid</entry>
+             <entry>All data are invalid</entry>
+           </row>
+           <row>
+             <entry>A</entry>
+             <entry>Autonomous mode</entry>
+             <entry>Data are derived from satellite data</entry>
+           </row>
+           <row>
+             <entry>D</entry>
+             <entry>Differential Mode</entry>
+             <entry>
+                 Data are augmented with differential data from a
+                 known ground station. The SkyTraq unit in TeleMetrum
+                 does not support this mode
+               </entry>
+           </row>
+           <row>
+             <entry>E</entry>
+             <entry>Estimated</entry>
+             <entry>
+                 Data are estimated using dead reckoning from the
+                 last known data
+               </entry>
+           </row>
+           <row>
+             <entry>M</entry>
+             <entry>Manual</entry>
+             <entry>Data were entered manually</entry>
+           </row>
+           <row>
+             <entry>S</entry>
+             <entry>Simulated</entry>
+             <entry>GPS receiver testing mode</entry>
+           </row>
+         </tbody>
+       </tgroup>
+      </table>

     </section>
     <section>
       <title>GPS Satellite Data</title>
     </section>
     <section>
       <title>GPS Satellite Data</title>


@@ -418,6 +521,15 @@
          </tbody>
        </tgroup>
       </informaltable>
          </tbody>
        </tgroup>
       </informaltable>

+      <para>
+       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.
+      </para>
+      <para>
+       GPS Satellite data are transmitted once per second during all
+       phases of the flight.
+      </para>

       <table frame='all'>
        <title>GPS Satellite Data Contents</title>
        <tgroup cols='4' align='center' colsep='1' rowsep='1'>
       <table frame='all'>
        <title>GPS Satellite Data Contents</title>
        <tgroup cols='4' align='center' colsep='1' rowsep='1'>


@@ -436,137 +548,183 @@
          <tbody>
            <row>
              <entry>5</entry><entry>uint8_t</entry><entry>channels</entry>
          <tbody>
            <row>
              <entry>5</entry><entry>uint8_t</entry><entry>channels</entry>

+             <entry>Number of reported satellite information</entry>

            </row>
            <row>
            </row>
            <row>

-             <entry>6</entry><entry>uint8_t</entry><entry>sat_0_id</entry>
+             <entry>6</entry><entry>sat_info_t</entry><entry>sats[12]</entry>
+             <entry>See Per-Satellite data table below</entry>

            </row>
            <row>
            </row>
            <row>

-             <entry>7</entry><entry>uint8_t</entry><entry>sat_0_c_n_1</entry>
+             <entry>30</entry><entry>uint8_t</entry><entry>unused[2]</entry>

            </row>
            <row>
            </row>
            <row>

-             <entry>8</entry><entry>uint8_t</entry><entry>sat_1_id</entry>
-           </row>
-           <row>
-             <entry>9</entry><entry>uint8_t</entry><entry>sat_1_c_n_1</entry>
-           </row>
-           <row>
-             <entry>10</entry><entry>uint8_t</entry><entry>sat_2_id</entry>
-           </row>
-           <row>
-             <entry>11</entry><entry>uint8_t</entry><entry>sat_2_c_n_1</entry>
-           </row>
-           <row>
-             <entry>12</entry><entry>uint8_t</entry><entry>sat_3_id</entry>
-           </row>
-           <row>
-             <entry>13</entry><entry>uint8_t</entry><entry>sat_3_c_n_1</entry>
-           </row>
-           <row>
-             <entry>14</entry><entry>uint8_t</entry><entry>sat_4_id</entry>
-           </row>
-           <row>
-             <entry>15</entry><entry>uint8_t</entry><entry>sat_4_c_n_1</entry>
-           </row>
-           <row>
-             <entry>16</entry><entry>uint8_t</entry><entry>sat_5_id</entry>
-           </row>
-           <row>
-             <entry>17</entry><entry>uint8_t</entry><entry>sat_5_c_n_1</entry>
-           </row>
-           <row>
-             <entry>18</entry><entry>uint8_t</entry><entry>sat_6_id</entry>
+             <entry>32</entry>

            </row>
            </row>

+         </tbody>
+       </tgroup>
+      </table>
+      <table frame='all'>
+       <title>GPS Per-Satellite data (sat_info_t)</title>
+       <tgroup cols='4' align='center' colsep='1' rowsep='1'>
+         <colspec align='right' colwidth='*' colname='Offset'/>
+         <colspec align='center' colwidth='3*' colname='Data Type'/>
+         <colspec align='left' colwidth='3*' colname='Name'/>
+         <colspec align='left' colwidth='9*' colname='Description'/>
+         <thead>

            <row>
            <row>

-             <entry>19</entry><entry>uint8_t</entry><entry>sat_6_c_n_1</entry>
+             <entry align='center'>Offset</entry>
+             <entry align='center'>Data Type</entry>
+             <entry align='center'>Name</entry>
+             <entry align='center'>Description</entry>

            </row>
            </row>

+         </thead>
+         <tbody>

            <row>
            <row>

-             <entry>20</entry><entry>uint8_t</entry><entry>sat_7_id</entry>
+             <entry>0</entry><entry>uint8_t</entry><entry>svid</entry>
+             <entry>Space Vehicle Identifier</entry>

            </row>
            <row>
            </row>
            <row>

-             <entry>21</entry><entry>uint8_t</entry><entry>sat_7_c_n_1</entry>
+             <entry>1</entry><entry>uint8_t</entry><entry>c_n_1</entry>
+             <entry>C/N1 signal quality indicator</entry>

            </row>
            <row>
            </row>
            <row>

-             <entry>22</entry><entry>uint8_t</entry><entry>sat_8_id</entry>
+             <entry>2</entry>

            </row>
            </row>

+         </tbody>
+       </tgroup>
+      </table>
+    </section>
+  </section>
+  <section>
+    <title>Data Transmission</title>
+    <para>
+      Altus Metrum devices use the Texas Instruments CC1111
+      microcontroller which includes an integrated sub-GHz digital
+      transceiver. This transceiver is used to both transmit and
+      receive the telemetry packets. This section discusses what
+      modulation scheme is used and how this device is configured.
+    </para>
+    <section>
+      <title>Modulation Scheme</title>
+      <para>
+       Texas Instruments provides a tool for computing modulation
+       parameters given a desired modulation format and basic bit
+       rate. For AltOS, the basic bit rate was specified as 38 kBaud,
+       resulting in the following signal parmeters:
+      </para>
+      <table>
+       <tgroup cols='3'>
+         <colspec align="center" colwidth="*" colname="parameter"/>
+         <colspec align="center" text-align="." colwidth="*" colname="value"/>
+         <colspec align="center" colwidth="*" colname="description"/>
+         <thead>

            <row>
            <row>

-             <entry>23</entry><entry>uint8_t</entry><entry>sat_8_c_n_1</entry>
+             <entry align='center'>Parameter</entry>
+             <entry align='center'>Value</entry>
+             <entry align='center'>Description</entry>

            </row>
            </row>

+         </thead>
+         <tbody>

            <row>
            <row>

-             <entry>24</entry><entry>uint8_t</entry><entry>sat_9_id</entry>
+             <entry>Modulation</entry>
+             <entry>GFSK</entry>
+             <entry>Gaussian Frequency Shift Keying</entry>

            </row>
            <row>
            </row>
            <row>

-             <entry>25</entry><entry>uint8_t</entry><entry>sat_9_c_n_1</entry>
+             <entry>Deviation</entry>
+             <entry>20.507812 kHz</entry>
+             <entry>Frequency modulation</entry>

            </row>
            <row>
            </row>
            <row>

-             <entry>26</entry><entry>uint8_t</entry><entry>sat_10_id</entry>
+             <entry>Data rate</entry>
+             <entry>38.360596 kBaud</entry>
+             <entry>Raw bit rate</entry>

            </row>
            <row>
            </row>
            <row>

-             <entry>27</entry><entry>uint8_t</entry><entry>sat_10_c_n_1</entry>
+             <entry>RX Filter Bandwidth</entry>
+             <entry>93.75 kHz</entry>
+             <entry>Receiver Band pass filter bandwidth</entry>

            </row>
            <row>
            </row>
            <row>

-             <entry>28</entry><entry>uint8_t</entry><entry>sat_11_id</entry>
+             <entry>IF Frequency</entry>
+             <entry>140.62 kHz</entry>
+             <entry>Receiver intermediate frequency</entry>

            </row>
            </row>

+         </tbody>
+       </tgroup>
+      </table>
+    </section>
+    <section>
+      <para>
+       The cc1111 provides forward error correction in hardware,
+       which AltOS uses to improve reception of weak signals. The
+       overall effect of this is to halve the available bandwidth for
+       data from 38 kBaud to 19 kBaud.
+      </para>
+      <title>Error Correction</title>
+      <table>
+       <tgroup cols='3'>
+         <colspec align="center" colwidth="*" colname="parameter"/>
+         <colspec align="center" colwidth="*" colname="value"/>
+         <colspec align="center" colwidth="*" colname="description"/>
+         <thead>

            <row>
            <row>

-             <entry>29</entry><entry>uint8_t</entry><entry>sat_11_c_n_1</entry>
+             <entry align='center'>Parameter</entry>
+             <entry align='center'>Value</entry>
+             <entry align='center'>Description</entry>

            </row>
            </row>

+         </thead>
+         <tbody>

            <row>
            <row>

-             <entry>30</entry><entry>uin8_t</entry><entry>unused30</entry>
+             <entry>Error Correction</entry>
+             <entry>Convolutional coding FEC</entry>
+             <entry>1/2 code, constraint length m=4</entry>

            </row>
            <row>
            </row>
            <row>

-             <entry>31</entry><entry>uin8_t</entry><entry>unused31</entry>
+             <entry>Interleaving</entry>
+             <entry>4 x 4</entry>
+             <entry>Reduce effect of noise burst</entry>

            </row>
            <row>
            </row>
            <row>

-             <entry>32</entry>
+             <entry>Data Whitening</entry>
+             <entry>XOR with 9-bit PNR</entry>
+             <entry>Rotate right with bit 8 = bit 0 xor bit 5, initial
+             value 111111111</entry>

            </row>
          </tbody>
        </tgroup>
       </table>
     </section>
   </section>
            </row>
          </tbody>
        </tgroup>
       </table>
     </section>
   </section>

+  <section>
+    <title>History and Motivation</title>
+    <para>
+      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.
+    </para>
+    <para>
+      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.
+    </para>
+    <para>
+      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.
+    </para>
+  </section>

 </article>
 </article>

-      
-<!--
-
-      
-      
-  
- Rethinking this (over IRC), and thinking about telemetry from a
- companion board, it looks like 32 bytes per packet would be better (12
- channels of A/D from telescience would require 24 bytes).
-
- Packet type 0x06: GPS satellites
- 1 packet per second.
-
-
- TeleScience
-
-<entry>5</entry><entry>uint8_t</entry><entry>channels</entry>
-<entry>6</entry><entry>uint16_t</entry><entry>data[12]</entry>
-<entry>30</entry><entry>uint8_t</entry><entry>unused[2]</entry>
-<entry>32</entry>
-
- [ 2-line signature. Click/Enter to show. ]
- - - 
- keith.packard@intel.com
- [ application/pgp-signature ]
-  Keith Packard <keithp@keithp.com> (Mon. 18:59) (me sent)
-  Subject: Re: New telemetry ideas
-  To: bdale@gag.com
-  Date: Mon, 27 Jun 2011 18:59:08 -0700
-
-  [ multipart/signed ]
-  [ text/plain ]
-  On Mon, 27 Jun 2011 14:25:00 -0700, Keith Packard <keithp@keithp.com> wrote:
-  Non-text part: multipart/signed
-
-  > Packet type 0x05: GPS location
-  > 1 packet per second
-  > 
-  > 5       uint8_t         flags
-
-  Let's add another field here:
-
-<entry>6</entry><entry>int16_t</entry><entry>gps_tick</entry><entry>tick when GPS data was received</entry>
-
-  That leaves a single byte unused
--->
\ No newline at end of file