doc: Update micropeak docs to include lots of pictures
[fw/altos] / doc / micropeak.xsl
index 8c487e5d97d0d60d8d1cfc892b431356107892e7..66b04072a7634cc3b047adedab05f411554725cd 100644 (file)
       <year>2012</year>
       <holder>Bdale Garbee and Keith Packard</holder>
     </copyright>
+    <mediaobject>
+      <imageobject>
+       <imagedata fileref="micropeak-dime.jpg" width="6in"/>
+      </imageobject>
+    </mediaobject>
     <legalnotice>
       <para>
         This document is released under the terms of the
          determination.
        </revremark>
       </revision>
+      <revision>
+       <revnumber>1.3.2</revnumber>
+       <date>12 February 2014</date>
+       <revremark>
+         Add a "Download" button to the main window, which makes it
+         quicker to access the download function. Update the data
+         download documentation to reflect the new MicroPeak USB
+         adapter design. Monitor data during download to let you see
+         if the USB connection is working at all by showing the
+         characters received from the MicroPeak USB adapter.
+       </revremark>
+      </revision>
     </revhistory>
   </bookinfo>
   <dedication>
@@ -87,6 +104,13 @@ NAR #88757, TRA #12200
          holder with the positive (+) terminal facing away from the
          circuit board.
        </para>
+       <informalfigure>
+         <mediaobject>
+           <imageobject>
+             <imagedata fileref="micropeak-back.jpg" width="4.5in"/>
+           </imageobject>
+         </mediaobject>
+       </informalfigure>
       </listitem>
       <listitem>
        <para>
@@ -187,6 +211,13 @@ NAR #88757, TRA #12200
   </chapter>
   <chapter>
     <title>The MicroPeak USB adapter</title>
+    <informalfigure>
+      <mediaobject>
+       <imageobject>
+         <imagedata fileref="MicroPeakUSB-2.0.jpg" width="4.5in"/>
+       </imageobject>
+      </mediaobject>
+    </informalfigure>
     <para>
       MicroPeak stores barometric pressure information for the first
       48 seconds of the flight in on-board non-volatile memory. The
@@ -213,32 +244,80 @@ NAR #88757, TRA #12200
       <itemizedlist>
        <listitem>
          <para>
-           Connect the MicroPeak USB adapter to a USB cable and plug it
-           in to your computer.
+           Plug the MicroPeak USB adapter in to your computer.
          </para>
        </listitem>
        <listitem>
+         <?dbfo keep-together="always"?>
          <para>
-           Start the MicroPeak application, locate the File menu and
-           select the Download entry.
+           Start the MicroPeak application.
          </para>
+         <informalfigure>
+           <mediaobject>
+             <imageobject>
+               <imagedata fileref="micropeak-nofont.svg" width="0.5in"/>
+             </imageobject>
+           </mediaobject>
+         </informalfigure>
        </listitem>
        <listitem>
+         <?dbfo keep-together="always"?>
          <para>
-           The MicroPeak USB adapter has a small phototransistor on
-           the end of the board furthest from the USB
-           connector. Locate this and place the LED on the MicroPeak
-           directly in contact with it. The MicroPeak LED and the
-           MicroPeak USB adapter photo need to be touching—even a
-           millimeters of space between them will reduce the light
-           intensity from the LED enough that the phototransistor
-           will not sense it. Turn on the MicroPeak board and adjust
-           the position until the blue LED on the MicroPeak USB
-           adapter blinks in time with the orange LED on the
-           MicroPeak board.
+            Click on the Download button at the top of the window.
          </para>
+         <informalfigure>
+           <mediaobject>
+             <imageobject>
+               <imagedata fileref="micropeak-app.png" width="4.5in"/>
+             </imageobject>
+           </mediaobject>
+         </informalfigure>
        </listitem>
        <listitem>
+         <?dbfo keep-together="always"?>
+         <para>
+           Select from the listed devices. There will probably be
+           only one.
+         </para>
+         <informalfigure>
+           <mediaobject>
+             <imageobject>
+               <imagedata fileref="micropeak-device-dialog.png" width="2.3in"/>
+             </imageobject>
+           </mediaobject>
+         </informalfigure>
+       </listitem>
+       <listitem>
+         <para>
+           The application will now wait until it receives valid data
+           from the MicroPeak USB adapter.
+         </para>
+         <informalfigure>
+           <mediaobject>
+             <imageobject>
+               <imagedata fileref="micropeak-download.png" width="2in"/>
+             </imageobject>
+           </mediaobject>
+         </informalfigure>
+         <para>
+           The MicroPeak USB adapter has a small phototransistor
+           under the hole in the center of the box.
+           Locate this, turn on the MicroPeak and place the orange LED on the MicroPeak
+           directly inside the hole, resting the MicroPeak itself on
+           the box. You should see the blue LED on the MicroPeak USB
+           adapter blinking in time with the orange LED on the
+           MicroPeak board itself.
+         </para>
+         <informalfigure>
+           <mediaobject>
+             <imageobject>
+               <imagedata fileref="MicroPeakUSB-2.0-inuse.jpg" width="4.5in"/>
+             </imageobject>
+           </mediaobject>
+         </informalfigure>
+       </listitem>
+       <listitem>
+         <?dbfo keep-together="always"?>
          <para>
            After the maximum flight height is reported, MicroPeak will
            pause for a few seconds, blink the LED four times rapidly
@@ -248,6 +327,22 @@ NAR #88757, TRA #12200
            data to a file. If not, you can power cycle the MicroPeak
            board and try again.
          </para>
+         <informalfigure>
+           <mediaobject>
+             <imageobject>
+               <imagedata fileref="micropeak-save-dialog.png" width="2.3in"/>
+             </imageobject>
+           </mediaobject>
+         </informalfigure>
+       </listitem>
+       <listitem>
+         <?dbfo keep-together="always"?>
+         <para>
+           Once the data are saved, a graph will be displayed with
+           height, speed and acceleration values computed from the
+           recorded barometric pressure data. See the next section
+           for more details on that.
+         </para>
        </listitem>
       </itemizedlist>
     </section>
@@ -275,26 +370,6 @@ NAR #88757, TRA #12200
        reasonably smooth speed and acceleration data, which would
        otherwise be swamped with noise.
       </para>
-      <para>
-       Under the Graph tab, the height, speed and acceleration values
-       are displayed together. You can zoom in on the graph by
-       clicking and dragging to sweep out an area of
-       interest. Right-click on the plot to bring up a menu that will
-       let you save, copy or print the graph.
-      </para>
-      <para>
-       The Statistics tab presents overall data from the flight. Note
-       that the Maximum height value is taken from the minumum
-       pressure captured in flight, and may be different from the
-       apparant apogee value as the on-board data are sampled twice
-       as fast as the recorded values, or because the true apogee
-       occurred after the on-board memory was full. Each value is
-       presented in several units as appropriate.
-      </para>
-      <para>
-       A table consisting of the both the raw barometric pressure
-       data and values computed from that for each recorded time.
-      </para>
       <para>
        The File menu has operations to open existing flight logs,
        Download new data from MicroPeak, Save a copy of the flight
@@ -303,9 +378,80 @@ NAR #88757, TRA #12200
        the current window or close all windows and Exit the
        application.
       </para>
+      <section>
+       <title>MicroPeak Graphs</title>
+       <para>
+         Under the Graph tab, the height, speed and acceleration values
+         are displayed together. You can zoom in on the graph by
+         clicking and dragging to sweep out an area of
+         interest. Right-click on the plot to bring up a menu that will
+         let you save, copy or print the graph.
+       </para>
+       <informalfigure>
+         <mediaobject>
+           <imageobject>
+             <imagedata fileref="micropeak-graph.png" width="4.5in"/>
+           </imageobject>
+         </mediaobject>
+       </informalfigure>
+      </section>
+      <section>
+       <title>MicroPeak Flight Statistics</title>
+       <para>
+         The Statistics tab presents overall data from the flight. Note
+         that the Maximum height value is taken from the minumum
+         pressure captured in flight, and may be different from the
+         apparant apogee value as the on-board data are sampled twice
+         as fast as the recorded values, or because the true apogee
+         occurred after the on-board memory was full. Each value is
+         presented in several units as appropriate.
+       </para>
+       <informalfigure>
+         <mediaobject>
+           <imageobject>
+             <imagedata fileref="micropeak-statistics.png" width="4.5in"/>
+           </imageobject>
+         </mediaobject>
+       </informalfigure>
+      </section>
+      <section>
+       <title>Raw Data</title>
+       <para>
+         A table consisting of the both the raw barometric pressure
+         data and values computed from that for each recorded time.
+       </para>
+       <informalfigure>
+         <mediaobject>
+           <imageobject>
+             <imagedata fileref="micropeak-raw-data.png" width="4.5in"/>
+           </imageobject>
+         </mediaobject>
+       </informalfigure>
+      </section>
+      <section>
+       <title>Configuring the Graph</title>
+       <para>
+         This selects which graph elements to show, and lets you
+         switch between metric and imperial units
+       </para>
+       <informalfigure>
+         <mediaobject>
+           <imageobject>
+             <imagedata fileref="micropeak-graph-configure.png" width="4.5in"/>
+           </imageobject>
+         </mediaobject>
+       </informalfigure>
+      </section>
     </section>
     <section>
-      <title>Configuring the MicroPeak application</title>
+      <title>Setting MicroPeak Preferences</title>
+      <informalfigure>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="micropeak-preferences.png" width="1.8in"/>
+         </imageobject>
+       </mediaobject>
+      </informalfigure>
       <para>
        The MicroPeak application has a few user settings which are
        configured through the Preferences dialog, which can be
@@ -377,9 +523,11 @@ NAR #88757, TRA #12200
       </para>
       <para>
        Ground pressure is computed from an average of 16 samples,
-       taken while the altimeter is at rest. Flight pressure is
-       computed from a Kalman filter designed to smooth out any minor
-       noise in the sensor values. 
+       taken while the altimeter is at rest. The flight pressure used to
+       report maximum height is computed from a Kalman filter
+       designed to smooth out any minor noise in the sensor
+       values. The flight pressure recorded to non-volatile storage
+       is unfiltered, coming directly from the pressure sensor.
       </para>
     </section>
     <section>
@@ -426,14 +574,14 @@ NAR #88757, TRA #12200
       <para>
        MicroPeak contains a fixed atmospheric model which is used to
        convert barometric pressure into altitude. The model was
-       converted into a 469-element piece wise linear approximation
+       converted into a 469-element piece-wise linear approximation
        which is then used to compute the altitude of the ground and
        apogee. The difference between these represents the maximum
        height of the flight.
       </para>
       <para>
        The model assumes a particular set of atmospheric conditions,
-       which while a reasonable average cannot represent the changing
+       which, while a reasonable average, cannot represent the changing
        nature of the real atmosphere. Fortunately, for flights
        reasonably close to the ground, the effect of this global
        inaccuracy are largely canceled out when the computed ground
@@ -441,6 +589,11 @@ NAR #88757, TRA #12200
        the resulting height is more accurate than either the ground
        or apogee altitudes.
       </para>
+      <para>
+       Because the raw pressure data is recorded to non-volatile
+       storage, you can use that, along with a more sophisticated
+       atmospheric model, to compute your own altitude values.
+      </para>
     </section>
     <section>
       <title>Mechanical Considerations</title>
@@ -477,8 +630,9 @@ NAR #88757, TRA #12200
       <para>
        In addition to the data used to present the height of the last
        flight, MicroPeak also stores barometric information sampled
-       at regular intervals during the flight. This information can
-       be extracted from MicroPeak through any AVR programming
+       at regular intervals during the flight. This is the
+       information captured with the MicroPeak USB adapter. It can
+       also be read from MicroPeak through any AVR programming
        tool.
       </para>
       <table frame='all'>