doc: Remove duplicate documentation about max flight log

[fw/altos] / doc / altusmetrum.xsl

diff --git a/doc/altusmetrum.xsl b/doc/altusmetrum.xsl
index 08787369430b5f6fb583e46e241926370fd8ec9c..329739e04014fde856e560aedc9e7af5a7d9256a 100644 (file)
--- a/doc/altusmetrum.xsl
+++ b/doc/altusmetrum.xsl
@@ -445,10 +445,10 @@ NAR #88757, TRA #12200
         close the window before performing other desired radio operations.
       </para>
       <para>
         close the window before performing other desired radio operations.
       </para>
       <para>

-        TeleMetrum only enables packet command mode in 'idle' mode, so
+        TeleMetrum only enables radio commanding in 'idle' mode, so

         make sure you have TeleMetrum lying horizontally when you turn
         it on. Otherwise, TeleMetrum will start in 'pad' mode ready for
         make sure you have TeleMetrum lying horizontally when you turn
         it on. Otherwise, TeleMetrum will start in 'pad' mode ready for

-        flight and will not be listening for command packets from TeleDongle.
+        flight, and will not be listening for command packets from TeleDongle.

       </para>
       <para>
        TeleMini listens for a command packet for five seconds after
       </para>
       <para>
        TeleMini listens for a command packet for five seconds after


@@ -462,12 +462,10 @@ NAR #88757, TRA #12200
        operation can be performed.
       </para>
       <para>
        operation can be performed.
       </para>
       <para>

-        When packet command mode is enabled, you can monitor the link
-        by watching the lights on the
-        devices. The red LED will flash each time they
-        transmit a packet while the green LED will light up
-        on TeleDongle while it is waiting to receive a packet from
-       the altimeter.
+        You can monitor the operation of the radio link by watching the 
+        lights on the devices. The red LED will flash each time a packet
+        is tramsitted, while the green LED will light up on TeleDongle when 
+        it is waiting to receive a packet from the altimeter.

       </para>
     </section>
     <section>
       </para>
     </section>
     <section>


@@ -538,31 +536,18 @@ NAR #88757, TRA #12200
         or radio link via TeleDongle.
       </para>
       <section>
         or radio link via TeleDongle.
       </para>
       <section>

-        <title>Radio Frequencies</title>
+        <title>Radio Frequency</title>

         <para>
         <para>

-         The Altus Metrum boards support frequencies in the 70cm
+         Altus Metrum boards support radio frequencies in the 70cm

          band. By default, the configuration interface provides a
          band. By default, the configuration interface provides a

-         list of 10 common frequencies in 100kHz channels starting at
+         list of 10 "standard" frequencies in 100kHz channels starting at

          434.550MHz.  However, the firmware supports use of
          any 50kHz multiple within the 70cm band. At any given
          434.550MHz.  However, the firmware supports use of
          any 50kHz multiple within the 70cm band. At any given

-         launch, we highly recommend coordinating who will use each
-         frequency and when to avoid interference.  And of course, both
+         launch, we highly recommend coordinating when and by whom each
+         frequency will be used to avoid interference.  And of course, both

          altimeter and TeleDongle must be configured to the same
          frequency to successfully communicate with each other.
         </para>
          altimeter and TeleDongle must be configured to the same
          frequency to successfully communicate with each other.
         </para>

-        <para>
-          To set the radio frequency, use the 'c R' command to specify the
-         radio transceiver configuration parameter. This parameter is computed
-         using the desired frequency, 'F', the radio calibration parameter, 'C' (showed by the 'c s' command) and
-         the standard calibration reference frequency, 'S', (normally 434.550MHz):
-         <programlisting>
-           R = F / S * C
-         </programlisting>
-         Round the result to the nearest integer value.
-          As with all 'c' sub-commands, follow this with a 'c w' to write the
-          change to the parameter block in the on-board flash on
-          your altimeter board if you want the change to stay in place across reboots.
-        </para>

       </section>
       <section>
         <title>Apogee Delay</title>
       </section>
       <section>
         <title>Apogee Delay</title>


@@ -575,20 +560,14 @@ NAR #88757, TRA #12200
           primary and backup pyrotechnic charges do not fire simultaneously.
         </para>
         <para>
           primary and backup pyrotechnic charges do not fire simultaneously.
         </para>
         <para>

-          To set the apogee delay, use the 'c d' command.
-          As with all 'c' sub-commands, follow this with a 'c w' to write the
-          change to the parameter block in the on-board DataFlash chip.
-        </para>
-        <para>
-          Please note that the Altus Metrum apogee detection algorithm
-          fires exactly at apogee.  If you are also flying an
-          altimeter like the PerfectFlite MAWD, which only supports
-          selecting 0 or 1 seconds of apogee delay, you may wish to
-          set the MAWD to 0 seconds delay and set the TeleMetrum to
-          fire your backup 2 or 3 seconds later to avoid any chance of
-          both charges firing simultaneously.  We've flown several
-          air-frames this way quite happily, including Keith's
-          successful L3 cert.
+          The Altus Metrum apogee detection algorithm fires exactly at
+          apogee.  If you are also flying an altimeter like the
+          PerfectFlite MAWD, which only supports selecting 0 or 1
+          seconds of apogee delay, you may wish to set the MAWD to 0
+          seconds delay and set the TeleMetrum to fire your backup 2
+          or 3 seconds later to avoid any chance of both charges
+          firing simultaneously.  We've flown several air-frames this
+          way quite happily, including Keith's successful L3 cert.

         </para>
       </section>
       <section>
         </para>
       </section>
       <section>


@@ -603,99 +582,90 @@ NAR #88757, TRA #12200
           than the primary so that both pyrotechnic charges don't fire
           simultaneously.
         </para>
           than the primary so that both pyrotechnic charges don't fire
           simultaneously.
         </para>

-        <para>
-          To set the main deployment altitude, use the 'c m' command.
-          As with all 'c' sub-commands, follow this with a 'c w' to write the
-          change to the parameter block in the on-board DataFlash chip.
-        </para>

       </section>
       </section>

-    </section>
-    <section>
-      <title>Calibration</title>
-      <para>
-        There are only two calibrations required for a TeleMetrum board, and
-        only one for TeleDongle and TeleMini.
-      </para>

       <section>
       <section>

-        <title>Radio Frequency</title>
-        <para>
-          The radio frequency is synthesized from a clock based on the 48 MHz
-          crystal on the board.  The actual frequency of this oscillator must be
-          measured to generate a calibration constant.  While our GFSK modulation
-          bandwidth is wide enough to allow boards to communicate even when
-          their oscillators are not on exactly the same frequency, performance
-          is best when they are closely matched.
-          Radio frequency calibration requires a calibrated frequency counter.
-          Fortunately, once set, the variation in frequency due to aging and
-          temperature changes is small enough that re-calibration by customers
-          should generally not be required.
-        </para>
-        <para>
-          To calibrate the radio frequency, connect the UHF antenna port to a
-          frequency counter, set the board to 434.550MHz, and use the 'C'
-          command to generate a CW carrier.  Wait for the transmitter temperature
-          to stabilize and the frequency to settle down.
-          Then, divide 434.550 MHz by the
-          measured frequency and multiply by the current radio cal value show
-          in the 'c s' command.  For an unprogrammed board, the default value
-          is 1186611.  Take the resulting integer and program it using the 'c f'
-          command.  Testing with the 'C' command again should show a carrier
-          within a few tens of Hertz of the intended frequency.
-          As with all 'c' sub-commands, follow this with a 'c w' to write the
-          change to the parameter block in the on-board DataFlash chip.
-        </para>
+       <title>Maximum Flight Log</title>

        <para>
        <para>

-         when the radio calibration value is changed, the radio
-         frequency value is reset to the same value, so you'll need
-         to recompute and reset the radio frequency value using the
-         new radio calibration value.
+         TeleMetrum version 1.1 has 2MB of on-board flash storage,
+         enough to hold over 40 minutes of data at full data rate
+         (100 samples/second). TeleMetrum 1.0 has 1MB of on-board
+         storage. As data are stored at a reduced rate during descent
+         (10 samples/second), there's plenty of space to store many
+         flights worth of data.
+       </para>
+       <para>
+         The on-board flash is partitioned into separate flight logs,
+         each of a fixed maximum size. Increase the maximum size of
+         each log and you reduce the number of flights that can be
+         stored. Decrease the size and TeleMetrum can store more
+         flights.
+       </para>
+       <para>
+         All of the configuration data is also stored in the flash
+         memory, which consumes 64kB on TeleMetrum v1.1 and 256B on
+         TeleMetrum v1.0. This configuration space is not available
+         for storing flight log data.
+       </para>
+       <para>
+         To compute the amount of space needed for a single flight,
+         you can multiply the expected ascent time (in seconds) by
+         800, multiply the expected descent time (in seconds) by 80
+         and add the two together. That will slightly under-estimate
+         the storage (in bytes) needed for the flight. For instance,
+         a flight spending 20 seconds in ascent and 150 seconds in
+         descent will take about (20 * 800) + (150 * 80) = 28000
+         bytes of storage. You could store dozens of these flights in
+         the on-board flash.
+       </para>
+       <para>
+         The default size, 192kB, allows for 10 flights of storage on
+         TeleMetrum v1.1 and 5 flights on TeleMetrum v1.0. This
+         ensures that you won't need to erase the memory before
+         flying each time while still allowing more than sufficient
+         storage for each flight.
+       </para>
+       <para>
+         As TeleMini does not contain an accelerometer, it stores
+         data at 10 samples per second during ascent and one sample
+         per second during descent. Each sample is a two byte reading
+         from the barometer. These are stored in 5kB of
+         on-chip flash memory which can hold 256 seconds at the
+         ascent rate or 2560 seconds at the descent rate. Because of
+         the limited storage, TeleMini cannot hold data for more than
+         one flight, and so must be erased after each flight or it
+         will not capture data for subsequent flights.

        </para>
       </section>
       <section>
        </para>
       </section>
       <section>

-        <title>TeleMetrum Accelerometer</title>
-        <para>
-          The TeleMetrum accelerometer we use has its own 5 volt power supply and
-          the output must be passed through a resistive voltage divider to match
-          the input of our 3.3 volt ADC.  This means that unlike the barometric
-          sensor, the output of the acceleration sensor is not ratio-metric to
-          the ADC converter, and calibration is required.  We also support the
-          use of any of several accelerometers from a Freescale family that
-          includes at least +/- 40g, 50g, 100g, and 200g parts.  Using gravity,
-          a simple 2-point calibration yields acceptable results capturing both
-          the different sensitivities and ranges of the different accelerometer
-          parts and any variation in power supply voltages or resistor values
-          in the divider network.
-        </para>
-        <para>
-          To calibrate the acceleration sensor, use the 'c a 0' command.  You
-          will be prompted to orient the board vertically with the UHF antenna
-          up and press a key, then to orient the board vertically with the
-          UHF antenna down and press a key.
-          As with all 'c' sub-commands, follow this with a 'c w' to write the
-          change to the parameter block in the on-board DataFlash chip.
-        </para>
-        <para>
-          The +1g and -1g calibration points are included in each telemetry
-          frame and are part of the header extracted by ao-dumplog after flight.
-          Note that we always store and return raw ADC samples for each
-          sensor... nothing is permanently "lost" or "damaged" if the
-          calibration is poor.
-        </para>
-        <para>
-         In the unlikely event an accel cal that goes badly, it is possible
-         that TeleMetrum may always come up in 'pad mode' and as such not be
-         listening to either the USB or radio link.  If that happens,
-         there is a special hook in the firmware to force the board back
-         in to 'idle mode' so you can re-do the cal.  To use this hook, you
-         just need to ground the SPI clock pin at power-on.  This pin is
-         available as pin 2 on the 8-pin companion connector, and pin 1 is
-         ground.  So either carefully install a fine-gauge wire jumper
-         between the two pins closest to the index hole end of the 8-pin
-         connector, or plug in the programming cable to the 8-pin connector
-         and use a small screwdriver or similar to short the two pins closest
-         to the index post on the 4-pin end of the programming cable, and
-         power up the board.  It should come up in 'idle mode' (two beeps).
-        </para>
+       <title>Ignite Mode</title>
+       <para>
+         Instead of firing one charge at apogee and another charge at
+         a fixed height above the ground, you can configure the
+         altimeter to fire both at apogee or both during
+         descent. This was added to support an airframe that has two
+         TeleMetrum computers, one in the fin can and one in the
+         nose.
+       </para>
+       <para>
+         Providing the ability to use both igniters for apogee or
+         main allows some level of redundancy without needing two
+         flight computers.  In Redundant Apogee or Redundant Main
+         mode, the two charges will be fired two seconds apart.
+       </para>
+      </section>
+      <section>
+       <title>Pad Orientation</title>
+       <para>
+         TeleMetrum measures acceleration along the axis of the
+         board. Which way the board is oriented affects the sign of
+         the acceleration value. Instead of trying to guess which way
+         the board is mounted in the air frame, TeleMetrum must be
+         explicitly configured for either Antenna Up or Antenna
+         Down. The default, Antenna Up, expects the end of the
+         TeleMetrum board connected to the 70cm antenna to be nearest
+         the nose of the rocket, with the end containing the screw
+         terminals nearest the tail.
+       </para>

       </section>
     </section>
 
       </section>
     </section>
 


@@ -1197,31 +1167,6 @@ NAR #88757, TRA #12200
           size. A smaller value will allow more flights to be stored,
           a larger value will record data from longer flights.
        </para>
           size. A smaller value will allow more flights to be stored,
           a larger value will record data from longer flights.
        </para>

-       <para>
-         During ascent, TeleMetrum records barometer and
-         accelerometer values 100 times per second, other analog
-         information (voltages and temperature) 6 times per second
-         and GPS data once per second. During descent, the non-GPS
-         data is recorded 1/10th as often. Each barometer +
-         accelerometer record takes 8 bytes.
-       </para>
-       <para>
-         The default, 192kB, will store over 200 seconds of data at
-         the ascent rate, or over 2000 seconds of data at the descent
-         rate. That's plenty for most flights. This leaves enough
-         storage for five flights in a 1MB system, or 10 flights in a
-         2MB system.
-       </para>
-       <para>
-         The configuration block takes the last available block of
-         memory, on v1.0 boards that's just 256 bytes. However, the
-         flash part on the v1.1 boards uses 64kB for each block.
-        </para>
-       <para>
-          TeleMini has 5kB of on-board storage, which is plenty for a
-          single flight. Make sure you download and delete the data
-          before a subsequent flight or it will not log any data.
-       </para>

       </section>
       <section>
         <title>Ignite Mode</title>
       </section>
       <section>
         <title>Ignite Mode</title>


@@ -1327,10 +1272,10 @@ NAR #88757, TRA #12200
       <section>
         <title>Callsign</title>
         <para>
       <section>
         <title>Callsign</title>
         <para>

-          This value is used in command packet mode and is transmitted
-          in each packet sent from TeleDongle and received from
-          TeleMetrum. It is not used in telemetry mode as that transmits
-          packets only from TeleMetrum to TeleDongle. Configure this
+          This value is transmitted in each command packet sent from 
+         TeleDongle and received from an altimeter.  It is not used in 
+         telemetry mode, as the callsign configured in the altimeter board
+         is included in all telemetry packets.  Configure this

           with the AltosUI operators call sign as needed to comply with
           your local radio regulations.
         </para>
           with the AltosUI operators call sign as needed to comply with
           your local radio regulations.
         </para>


@@ -1370,7 +1315,7 @@ NAR #88757, TRA #12200
         This reprograms any Altus Metrum device by using a TeleMetrum
         or TeleDongle as a programming dongle. Please read the
         directions for flashing devices in the Updating Device
         This reprograms any Altus Metrum device by using a TeleMetrum
         or TeleDongle as a programming dongle. Please read the
         directions for flashing devices in the Updating Device

-        Firmware section above
+        Firmware chapter below.

       </para>
       <para>
         Once you have the programmer and target devices connected,
       </para>
       <para>
         Once you have the programmer and target devices connected,


@@ -2289,6 +2234,43 @@ NAR #88757, TRA #12200
       Verify you can connect and disconnect from the units while in your
       terminal program by sending the escape-disconnect mentioned above.
     </para>
       Verify you can connect and disconnect from the units while in your
       terminal program by sending the escape-disconnect mentioned above.
     </para>

+        <para>
+          To set the radio frequency, use the 'c R' command to specify the
+         radio transceiver configuration parameter. This parameter is computed
+         using the desired frequency, 'F', the radio calibration parameter, 'C' (showed by the 'c s' command) and
+         the standard calibration reference frequency, 'S', (normally 434.550MHz):
+         <programlisting>
+           R = F / S * C
+         </programlisting>
+         Round the result to the nearest integer value.
+          As with all 'c' sub-commands, follow this with a 'c w' to write the
+          change to the parameter block in the on-board flash on
+          your altimeter board if you want the change to stay in place across reboots.
+        </para>
+        <para>
+          To set the apogee delay, use the 'c d' command.
+          As with all 'c' sub-commands, follow this with a 'c w' to write the
+          change to the parameter block in the on-board DataFlash chip.
+        </para>
+        <para>
+          To set the main deployment altitude, use the 'c m' command.
+          As with all 'c' sub-commands, follow this with a 'c w' to write the
+          change to the parameter block in the on-board DataFlash chip.
+        </para>
+        <para>
+          To calibrate the radio frequency, connect the UHF antenna port to a
+          frequency counter, set the board to 434.550MHz, and use the 'C'
+          command to generate a CW carrier.  Wait for the transmitter temperature
+          to stabilize and the frequency to settle down.
+          Then, divide 434.550 MHz by the
+          measured frequency and multiply by the current radio cal value show
+          in the 'c s' command.  For an unprogrammed board, the default value
+          is 1186611.  Take the resulting integer and program it using the 'c f'
+          command.  Testing with the 'C' command again should show a carrier
+          within a few tens of Hertz of the intended frequency.
+          As with all 'c' sub-commands, follow this with a 'c w' to write the
+          change to the parameter block in the on-board DataFlash chip.
+        </para>

     <para>
       Note that the 'reboot' command, which is very useful on the altimeters,
       will likely just cause problems with the dongle.  The *correct* way
     <para>
       Note that the 'reboot' command, which is very useful on the altimeters,
       will likely just cause problems with the dongle.  The *correct* way


@@ -2355,7 +2337,7 @@ NAR #88757, TRA #12200
       strength providing an indication of the direction from receiver to rocket.
     </para>
     <para>
       strength providing an indication of the direction from receiver to rocket.
     </para>
     <para>

-      TeleMetrum also provides GPS trekking data, which can further simplify
+      TeleMetrum also provides GPS tracking data, which can further simplify

       locating the rocket once it has landed. (The last good GPS data
       received before touch-down will be on the data screen of 'ao-view'.)
     </para>
       locating the rocket once it has landed. (The last good GPS data
       received before touch-down will be on the data screen of 'ao-view'.)
     </para>


@@ -2379,6 +2361,111 @@ NAR #88757, TRA #12200
       once you enable the voice output!
     </para>
   </appendix>
       once you enable the voice output!
     </para>
   </appendix>

+  <appendix>
+      <title>Calibration</title>
+      <para>
+        There are only two calibrations required for a TeleMetrum board, and
+        only one for TeleDongle and TeleMini.  All boards are shipped from
+        the factory pre-calibrated, but the procedures are documented here
+       in case they are ever needed.  Re-calibration is not supported by
+       AltosUI, you must connect to the board with a serial terminal program
+       and interact directly with the on-board command interpreter to effect
+       calibration.
+      </para>
+      <section>
+        <title>Radio Frequency</title>
+        <para>
+          The radio frequency is synthesized from a clock based on the 48 MHz
+          crystal on the board.  The actual frequency of this oscillator 
+          must be measured to generate a calibration constant.  While our 
+          GFSK modulation
+          bandwidth is wide enough to allow boards to communicate even when
+          their oscillators are not on exactly the same frequency, performance
+          is best when they are closely matched.
+          Radio frequency calibration requires a calibrated frequency counter.
+          Fortunately, once set, the variation in frequency due to aging and
+          temperature changes is small enough that re-calibration by customers
+          should generally not be required.
+        </para>
+        <para>
+          To calibrate the radio frequency, connect the UHF antenna port to a
+          frequency counter, set the board to 434.550MHz, and use the 'C'
+          command in the on-board command interpreter to generate a CW 
+          carrier.  For TeleMetrum, this is best done over USB.  For TeleMini,
+         note that the only way to escape the 'C' command is via power cycle
+         since the board will no longer be listening for commands once it
+         starts generating a CW carrier.
+       </para>
+       <para>
+         Wait for the transmitter temperature to stabilize and the frequency 
+          to settle down.  Then, divide 434.550 MHz by the
+          measured frequency and multiply by the current radio cal value show
+          in the 'c s' command.  For an unprogrammed board, the default value
+          is 1186611.  Take the resulting integer and program it using the 'c f'
+          command.  Testing with the 'C' command again should show a carrier
+          within a few tens of Hertz of the intended frequency.
+          As with all 'c' sub-commands, follow this with a 'c w' to write the
+          change to the parameter block in the on-board DataFlash chip.
+        </para>
+       <para>
+         Note that any time you re-do the radio frequency calibration, the
+         radio frequency is reset to the default 434.550 Mhz.  If you want
+         to use another frequency, you will have to set that again after
+         calibration is completed.
+       </para>
+      </section>
+      <section>
+        <title>TeleMetrum Accelerometer</title>
+        <para>
+          The TeleMetrum accelerometer we use has its own 5 volt power 
+         supply and
+          the output must be passed through a resistive voltage divider to match
+          the input of our 3.3 volt ADC.  This means that unlike the barometric
+          sensor, the output of the acceleration sensor is not ratio-metric to
+          the ADC converter, and calibration is required.  Explicitly 
+         calibrating the accelerometers also allows us to load any device
+         from a Freescale family that includes at least +/- 40g, 50g, 100g, 
+         and 200g parts.  Using gravity,
+          a simple 2-point calibration yields acceptable results capturing both
+          the different sensitivities and ranges of the different accelerometer
+          parts and any variation in power supply voltages or resistor values
+          in the divider network.
+        </para>
+        <para>
+          To calibrate the acceleration sensor, use the 'c a 0' command.  You
+          will be prompted to orient the board vertically with the UHF antenna
+          up and press a key, then to orient the board vertically with the
+          UHF antenna down and press a key.  Note that the accuracy of this
+         calibration depends primarily on how perfectly vertical and still
+         the board is held during the cal process.  As with all 'c' 
+         sub-commands, follow this with a 'c w' to write the
+          change to the parameter block in the on-board DataFlash chip.
+        </para>
+        <para>
+          The +1g and -1g calibration points are included in each telemetry
+          frame and are part of the header stored in onboard flash to be
+         downloaded after flight.  We always store and return raw ADC 
+         samples for each sensor... so nothing is permanently "lost" or 
+         "damaged" if the calibration is poor.
+        </para>
+        <para>
+         In the unlikely event an accel cal goes badly, it is possible
+         that TeleMetrum may always come up in 'pad mode' and as such not be
+         listening to either the USB or radio link.  If that happens,
+         there is a special hook in the firmware to force the board back
+         in to 'idle mode' so you can re-do the cal.  To use this hook, you
+         just need to ground the SPI clock pin at power-on.  This pin is
+         available as pin 2 on the 8-pin companion connector, and pin 1 is
+         ground.  So either carefully install a fine-gauge wire jumper
+         between the two pins closest to the index hole end of the 8-pin
+         connector, or plug in the programming cable to the 8-pin connector
+         and use a small screwdriver or similar to short the two pins closest
+         to the index post on the 4-pin end of the programming cable, and
+         power up the board.  It should come up in 'idle mode' (two beeps),
+        allowing a re-cal.
+        </para>
+      </section>
+  </appendix>

   <appendix
       xmlns:xi="http://www.w3.org/2001/XInclude">
     <title>Release Notes</title>
   <appendix
       xmlns:xi="http://www.w3.org/2001/XInclude">
     <title>Release Notes</title>