]> git.gag.com Git - fw/altos/blob - doc/telegps.xsl
Set version to 1.5.9.1
[fw/altos] / doc / telegps.xsl
1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3   "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
4 <book>
5   <title>TeleGPS Owner's Manual</title>
6   <subtitle>A recording GPS tracker</subtitle>
7   <bookinfo>
8     <author>
9       <firstname>Keith</firstname>
10       <surname>Packard</surname>
11     </author>
12     <copyright>
13       <year>2014</year>
14       <holder>Bdale Garbee and Keith Packard</holder>
15     </copyright>
16     <mediaobject>
17       <imageobject>
18         <imagedata fileref="telegps-v1.0-top.jpg" width="4in"/>
19       </imageobject>
20     </mediaobject>
21     <legalnotice>
22       <para>
23         This document is released under the terms of the
24         <ulink url="http://creativecommons.org/licenses/by-sa/3.0/">
25           Creative Commons ShareAlike 3.0
26         </ulink>
27         license.
28       </para>
29     </legalnotice>
30     <revhistory>
31       <revision>
32         <revnumber>1.4.1</revnumber>
33         <date>20 June 2014</date>
34         <revremark>
35           Minor release fixing some installation bugs.
36         </revremark>
37       </revision>
38       <revision>
39         <revnumber>1.4</revnumber>
40         <date>13 June 2014</date>
41         <revremark>
42           Initial release
43         </revremark>
44       </revision>
45     </revhistory>
46   </bookinfo>
47   <dedication>
48     <title>Acknowledgements</title>
49     <para>
50       Have fun using these products, and we hope to meet all of you
51       out on the rocket flight line somewhere.
52       <literallayout>
53 Bdale Garbee, KB0G
54 NAR #87103, TRA #12201
55
56 Keith Packard, KD7SQG
57 NAR #88757, TRA #12200
58       </literallayout>
59     </para>
60   </dedication>
61   <chapter>
62     <title>Quick Start Guide</title>
63     <para>
64       TeleGPS is designed to be easy to use. Requiring no external
65       components, flying takes just a few steps.
66     </para>
67     <para>
68       First, download and install the software from <ulink
69       url="http://altusmetrum.org/AltOS"/>. This will make sure that
70       you have the right device drivers installed.
71     </para>
72     <para>
73       Next, plug in the battery and USB cable and connect TeleGPS to
74       your computer. This will charge the battery and allow you to
75       configure the device.
76     </para>
77     <para>
78       Start the TeleGPS application and set the callsign and frequency
79       on your TeleGPS device; refer to the Configure TeleGPS section
80       in the TeleGPS Application chapter for instructions.
81     </para>
82     <para>
83       Unplug TeleGPS when the battery charger light goes green. This
84       will enable the radio and logging portions of the TeleGPS
85       firmware.
86     </para>
87     <para>
88       Connect TeleDongle to your computer and start TeleGPS or start
89       AltosDroid on your android device and connect to TeleBT. Set the
90       frequency to match the TeleGPS and you should be receiving telemetry.
91     </para>
92   </chapter>
93   <chapter>
94     <title>Handling Precautions</title>
95     <para>
96       All Altus Metrum products are sophisticated electronic devices.  
97       When handled gently and properly installed in an air-frame, they
98       will deliver impressive results.  However, as with all electronic 
99       devices, there are some precautions you must take.
100     </para>
101     <para>
102       The Lithium polymer batteries have an
103       extraordinary power density.  This is great because we can fly with
104       much less battery mass... but if they are punctured
105       or their contacts are allowed to short, they can and will release their
106       energy very rapidly!
107       Thus we recommend that you take some care when handling TeleGPS
108       to keep conductive material from coming in contact with the exposed metal elements.
109     </para>
110     <para>
111       As with all other rocketry electronics, Altus Metrum devices must 
112       be protected from exposure to corrosive motor exhaust and ejection 
113       charge gasses.
114     </para>
115   </chapter>
116   <chapter>
117     <title>TeleGPS Hardware</title>
118     <section>
119       <title>Hooking Up Lithium Polymer Batteries</title>
120       <para>
121         TeleGPS has a two pin JST PH series connector to connect up
122         a single-cell Lithium Polymer cell (3.7V nominal). You can
123         purchase matching batteries from the Altus Metrum store, or
124         other vendors, or you can make your own. Pin 1 of the
125         connector is positive, pin 2 is negative. Spark Fun sells a
126         cable with the connector attached, which they call a <ulink
127         url="https://www.sparkfun.com/products/9914">JST Jumper 2
128         Wire Assembly</ulink>.
129       </para>
130       <para>
131         Many RC vendors also sell lithium polymer batteries with
132         this same connector. All that we have found use the opposite
133         polarity, and if you use them that way, you will damage or
134         destroy TeleGPS.
135       </para>
136     </section>
137     <section>
138       <title>On-board Data Recording</title>
139       <para>
140         TeleGPS logs GPS data at a user-configurable rate. Data are
141         logged to a 2MB on-board flash memory part, which can be
142         partitioned into several equal-sized blocks, one for each
143         flight. 64kB of this storage are reserved to hold
144         configuration data, leaving 1984kB for flight data.
145       </para>
146       <para>
147         The on-board flash is partitioned into separate flight logs,
148         each of a fixed maximum size. Increase the maximum size of
149         each log and you reduce the number of flights that can be
150         stored. Decrease the size and you can store more flights.
151       </para>
152       <para>
153         To compute the amount of space needed for a single log, you
154         can divide the expected time (in seconds) by the sample period
155         (by default, 1 second per sample) and then multiply the result
156         by 32 bytes per sample. For instance, a sample period of 1
157         second and a flight lasting one hour will take 32 * 3600 =
158         115200 bytes. TeleGPS does try to reduce log space used by not
159         recording position information when it isn't moving, so actual
160         space consumed may be less than this.
161       </para>
162       <para>
163         The default size allows for four flights of 496kB each, which
164         provides over four hours of logging at 1 sample per second.
165       </para>
166       <para>
167         TeleGPS will not overwrite existing flight data, so be sure to
168         download flight data and erase it from the onboard flash
169         before it fills up. TeleGPS will still report telemetry even
170         if memory is full, so the only thing you will lose is the
171         on-board data log.
172       </para>
173     </section>
174     <section>
175       <title>Installation</title>
176       <para>
177         The battery connectors are a standard 2-pin JST connector and
178         match batteries sold by Spark Fun. These batteries are
179         single-cell Lithium Polymer batteries that nominally provide 3.7
180         volts.  Other vendors sell similar batteries for RC aircraft
181         using mating connectors, however the polarity for those is
182         generally reversed from the batteries used by Altus Metrum
183         products. In particular, the Tenergy batteries supplied for use
184         in Featherweight flight computers are not compatible with Altus
185         Metrum flight computers or battery chargers. <emphasis>Check
186         polarity and voltage before connecting any battery not purchased
187         from Altus Metrum or Spark Fun.</emphasis>
188       </para>
189       <para>
190         TeleGPS uses an integrate GPS patch antenna and won't
191         receive GPS signals if installed inside a metal or carbon
192         fiber compartment. Test GPS reception and telemetry
193         transmission with the system installed and all other
194         electronics powered up to verify signal reception and make
195         sure there isn't any interference from other systems.
196       </para>
197     </section>
198   </chapter>
199   <chapter>
200     <title>System Operation</title>
201     <section>
202       <title>GFSK Telemetry</title>
203       <para>
204         TeleGPS's native telemetry system doesn't use a 'normal packet
205         radio' mode like APRS because it's not very efficient.  The
206         GFSK modulation we use is FSK with the base-band pulses passed
207         through a Gaussian filter before they go into the modulator to
208         limit the transmitted bandwidth.  When combined with forward
209         error correction and interleaving, this allows us to have a
210         very robust 19.2 kilobit data link with only 10-40 milliwatts
211         of transmit power, a whip antenna in the rocket, and a
212         hand-held Yagi on the ground.  We've had flights to above 21k
213         feet AGL with great reception, and calculations suggest we
214         should be good to well over 40k feet AGL with a 5-element yagi
215         on the ground with our 10mW units and over 100k feet AGL with
216         the 40mW devices.
217       </para>
218     </section>
219     <section>
220       <title>APRS</title>
221       <para>
222         TeleGPS can send APRS if desired, and the
223         interval between APRS packets can be configured. As each APRS
224         packet takes a full second to transmit, we recommend an
225         interval of at least 5 seconds to avoid consuming too much
226         battery power or radio channel bandwidth. You can configure
227         the APRS interval using AltosUI; that process is described in
228         the Configure Altimeter section of the AltosUI chapter.
229       </para>
230       <para>
231         AltOS uses the APRS compressed position report data format,
232         which provides for higher position precision and shorter
233         packets than the original APRS format. It also includes
234         altitude data, which is invaluable when tracking rockets. We
235         haven't found a receiver which doesn't handle compressed
236         positions, but it's just possible that you have one, so if you
237         have an older device that can receive the raw packets but
238         isn't displaying position information, it's possible that this
239         is the cause.
240       </para>
241       <para>
242         The APRS packet format includes a comment field that can have
243         arbitrary text in it. AltOS uses this to send status
244         information about the flight computer. It sends four fields as
245         shown in the following table.
246       </para>
247       <table frame='all'>
248         <title>Altus Metrum APRS Comments</title>
249         <?dbfo keep-together="always"?>
250         <tgroup cols='3' align='center' colsep='1' rowsep='1'>
251           <colspec align='center' colwidth='*' colname='Field'/>
252           <colspec align='center' colwidth='*' colname='Example'/>
253           <colspec align='center' colwidth='4*' colname='Description'/>
254           <thead>
255             <row>
256               <entry align='center'>Field</entry>
257               <entry align='center'>Example</entry>
258               <entry align='center'>Description</entry>
259             </row>
260           </thead>
261           <tbody>
262             <row>
263               <entry>1</entry>
264               <entry>L</entry>
265               <entry>GPS Status U for unlocked, L for locked</entry>
266             </row>
267             <row>
268               <entry>2</entry>
269               <entry>6</entry>
270               <entry>Number of Satellites in View</entry>
271             </row>
272             <row>
273               <entry>3</entry>
274               <entry>B4.0</entry>
275               <entry>Battery Voltage</entry>
276             </row>
277           </tbody>
278         </tgroup>
279       </table>
280       <para>
281         Here's an example of an APRS comment showing GPS lock with 6
282         satellites in view and a battery at 4.0V.
283         <screen>
284           L6 B4.0
285         </screen>
286       </para>
287       <para>
288         Make sure your primary battery is above 3.8V and GPS is locked
289         with at least 5 or 6 satellites in view before starting. If GPS
290         is switching between L and U regularly, then it doesn't have a
291         good lock and you should wait until it becomes stable.
292       </para>
293       <para>
294         If the GPS receiver loses lock, the APRS data transmitted will
295         contain the last position for which GPS lock was
296         available. You can tell that this has happened by noticing
297         that the GPS status character switches from 'L' to 'U'. Before
298         GPS has locked, APRS will transmit zero for latitude,
299         longitude and altitude.
300       </para>
301     </section>
302     <section>
303       <title>Configurable Parameters</title>
304       <para>
305         Configuring TeleGPS is very
306         simple; the few configurable parameters can all be set
307         using the TeleGPS application over USB. Read
308         the Configure TeleGPS section in the TeleGPS Software chapter below
309         for more information.
310       </para>
311       <section>
312         <title>Radio Frequency</title>
313         <para>
314           Altus Metrum boards support radio frequencies in the 70cm
315           band. By default, the configuration interface provides a
316           list of 10 “standard” frequencies in 100kHz channels starting at
317           434.550MHz.  However, the firmware supports use of
318           any 50kHz multiple within the 70cm band. At any given
319           launch, we highly recommend coordinating when and by whom each
320           frequency will be used to avoid interference.  And of course, both
321           TeleGPS and the receiver must be configured to the same
322           frequency to successfully communicate with each other.
323         </para>
324       </section>
325       <section>
326         <title>Callsign</title>
327         <para>
328           This sets the callsign used for telemetry and APRS to
329           identify the device.
330         </para>
331       </section>
332       <section>
333         <title>Telemetry/RDF/APRS Enable</title>
334         <para>
335           You can completely disable the radio, if necessary, leaving
336           TeleGPS only logging data to internal memory.
337         </para>
338       </section>
339       <section>
340         <title>APRS Interval</title>
341         <para>
342           This selects how often APRS packets are transmitted. Set
343           this to zero to disable APRS without also disabling the
344           regular telemetry and RDF transmissions. As APRS takes a
345           full second to transmit a single position report, we
346           recommend sending packets no more than once every 5 seconds.
347         </para>
348       </section>
349       <section>
350         <title>Maximum Flight Log</title>
351         <para>
352           Changing this value will set the maximum amount of flight
353           log storage that an individual flight will use. The
354           available storage is divided into as many flights of the
355           specified size as can fit in the available space. You can
356           download and erase individual flight logs. If you fill up
357           the available storage, future flights will not get logged
358           until you erase some of the stored ones.
359         </para>
360       </section>
361       <section>
362         <title>Logging Trigger Motion</title>
363         <para>
364           If TeleGPS moves less than this distance over a long period
365           of time, it will not log that location, saving storage space.
366         </para>
367       </section>
368       <section>
369         <title>Position Reporting Interval</title>
370         <para>
371           This sets how often TeleGPS reports position information via
372           telemetry and to the on-board log. Reducing this value will
373           save power and logging memory consumption.
374         </para>
375       </section>
376     </section>
377   </chapter>
378   <chapter>
379     <title>TeleGPS Application</title>
380     <para>
381       The TeleGPS application provides a graphical user interface for
382       interacting with the Altus Metrum product family. TeleGPS can
383       monitor telemetry data, configure devices and many other
384       tasks. The primary interface window is for displaying data
385       received over the telemetry link. There are additional
386       tasks available from the main window menu bar. This chapter
387       is split into sections, each of which documents one of the tasks
388       provided from the top-level toolbar.
389     </para>
390     <section>
391       <title>Telemetry Monitoring</title>
392       <para>
393         This is the window brought up when you start the
394         application. If you have a TeleDongle device connected to the
395         computer, it will automatically be selected for telemetry monitoring
396       </para>
397       <para>
398         All telemetry data received are automatically recorded in
399         suitable log files. The name of the files includes the current
400         date and TeleGPS serial and flight numbers.
401       </para>
402       <para>
403         The radio frequency being monitored by the TeleDongle device
404         is displayed at the top of the window. You can configure the
405         frequency by clicking on the frequency box and selecting the
406         desired frequency. The TeleGPS application remembers the last
407         frequency selected for each TeleDongle and selects that
408         automatically the next time you use that device.
409       </para>
410       <para>
411         Below the TeleDongle frequency selector, the window contains a few
412         significant pieces of information about the altimeter providing
413         the telemetry data stream:
414       </para>
415       <itemizedlist>
416         <listitem>
417           <para>The configured call-sign</para>
418         </listitem>
419         <listitem>
420           <para>The device serial number</para>
421         </listitem>
422         <listitem>
423           <para>The flight number. TeleGPS remembers how many
424           times it has flown.
425           </para>
426         </listitem>
427         <listitem>
428           <para>
429             The Received Signal Strength Indicator value. This lets
430             you know how strong a signal TeleDongle is receiving. The
431             radio inside TeleDongle operates down to about -100dBm;
432             weaker signals may not be receivable. The packet link uses
433             error detection and correction techniques which prevent
434             incorrect data from being reported.
435           </para>
436         </listitem>
437         <listitem>
438           <para>
439             The age of the displayed data, in seconds since the last 
440             successfully received telemetry packet.  In normal operation
441             this will stay in the low single digits.  If the number starts
442             counting up, then you are no longer receiving data over the radio
443             link from the flight computer.
444           </para>
445         </listitem>
446       </itemizedlist>
447       <para>
448         Finally, the largest portion of the window contains a set of
449         tabs, each of which contain some information about the TeleGPS
450         board. The final 'table' tab displays many of the raw telemetry
451         values in one place in a spreadsheet-like format.
452       </para>
453       <section>
454         <title>Map</title>
455         <para>
456           The Map tab shows the TeleGPS track over time on top of map
457           data making it easy to locate the device.
458         </para>
459         <informalfigure>
460           <mediaobject>
461             <imageobject>
462               <imagedata fileref="telegps-map.png" width="5.5in"/>
463             </imageobject>
464           </mediaobject>
465         </informalfigure>
466         <para>
467           The map's default scale is approximately 3m (10ft) per pixel. The map
468           can be dragged using the left mouse button. The map will attempt
469           to keep the rocket roughly centered while data is being received.
470         </para>
471         <para>
472           You can adjust the style of map and the zoom level with
473           buttons on the right side of the map window. You can draw a
474           line on the map by moving the mouse over the map with a
475           button other than the left one pressed, or by pressing the
476           left button while also holding down the shift key. The
477           length of the line in real-world units will be shown at the
478           start of the line.
479         </para>
480         <para>
481           Images are fetched automatically via the Google Maps Static API,
482           and cached on disk for reuse. If map images cannot be downloaded,
483           the rocket's path will be traced on a dark gray background
484           instead.
485         </para>
486         <para>
487           You can pre-load images for your favorite launch sites
488           before you leave home; check out the 'Preload Maps' section below.
489         </para>
490       </section>
491       <section>
492         <title>Location</title>
493         <para>
494           The Location tab shows the raw GPS data received from TeleGPS.
495         </para>
496         <informalfigure>
497           <mediaobject>
498             <imageobject>
499               <imagedata fileref="telegps-location.png" width="5.5in"/>
500             </imageobject>
501           </mediaobject>
502         </informalfigure>
503       </section>
504       <section>
505         <title>Status</title>
506         <para>
507           The Status tab shows data relative to the location of
508           TeleGPS when the application first received telemetry from
509           it.
510         </para>
511         <informalfigure>
512           <mediaobject>
513             <imageobject>
514               <imagedata fileref="telegps-status.png" width="5.5in"/>
515             </imageobject>
516           </mediaobject>
517         </informalfigure>
518       </section>
519       <section>
520         <title>Table</title>
521         <para>
522           The Table tab shows detailed information about the GPS
523           receiver
524         </para>
525         <informalfigure>
526           <mediaobject>
527             <imageobject>
528               <imagedata fileref="telegps-table.png" width="5.5in"/>
529             </imageobject>
530           </mediaobject>
531         </informalfigure>
532       </section>
533     </section>
534     <!--
535         <variablelist>
536           <varlistentry>
537             <term></term>
538             <listitem>
539               <para>
540               </para>
541             </listitem>
542           </varlistentry>
543         </variablelist>
544     -->
545     <section>
546       <title>TeleGPS Menus</title>
547       <para>
548         TeleGPS has three or four menus at the top of the window:
549         <variablelist>
550           <varlistentry>
551             <term>File</term>
552             <listitem>
553               <para>
554                 New Window, Graph Data, Export Data, Load Maps, Preferences, Close and Exit
555               </para>
556             </listitem>
557           </varlistentry>
558           <varlistentry>
559             <term>Monitor</term>
560             <listitem>
561               <para>
562                 Connect Device, Disconnect and Scan Channels
563               </para>
564             </listitem>
565           </varlistentry>
566           <varlistentry>
567             <term>Device</term>
568             <listitem>
569               <para>
570                 Download Data, Configure Device and Flash Device
571               </para>
572             </listitem>
573           </varlistentry>
574           <varlistentry>
575             <term>Frequency</term>
576             <listitem>
577               <para>
578                 This shows the current monitoring frequency with a
579                 drop-down menu listing other configured
580                 frequencies. You can change the set of frequencies
581                 shown here from the Preferences dialog. This menu is
582                 only shown when the TeleGPS application is connected
583                 to a TeleDongle or TeleBT device.
584               </para>
585             </listitem>
586           </varlistentry>
587         </variablelist>
588       </para>
589       <section>
590         <title>New Window</title>
591         <para>
592           This creates another telemetry monitoring window, in case
593           you have multiple TeleDongle devices connected to the
594           computer.
595         </para>
596       </section>
597       <section>
598         <title>Graph Data</title>
599         <para>
600           This brings up a file dialog to load a saved log, either
601           a .telem file of recorded telemetry or .eeprom of saved
602           data from on-board memory. It looks a bit like the flight
603           monitoring window, using a selection of tabs to show
604           different views of the saved data.
605         </para>
606         <section>
607           <title>Graph</title>
608           <para>
609             The Graph tab shows a plot of the the GPS data
610             collected. The X axis is time in seconds; there are a
611             variety of Y axes available for different kinds of data.
612           </para>
613           <informalfigure>
614             <mediaobject>
615               <imageobject>
616                 <imagedata fileref="telegps-graph-graph.png" width="6in" scalefit="1"/>
617               </imageobject>
618             </mediaobject>
619           </informalfigure>
620         </section>
621         <section>
622           <title>Configure Graph</title>
623           <informalfigure>
624             <mediaobject>
625               <imageobject>
626                 <imagedata fileref="telegps-graph-configure.png" width="6in" scalefit="1"/>
627               </imageobject>
628             </mediaobject>
629           </informalfigure>
630           <para>
631             This selects which graph elements to show, and, at the
632             bottom, lets you switch between metric and imperial units
633           </para>
634         </section>
635         <section>
636           <title>Statistics</title>
637           <informalfigure>
638             <mediaobject>
639               <imageobject>
640                 <imagedata fileref="telegps-graph-stats.png" width="6in" scalefit="1"/>
641               </imageobject>
642             </mediaobject>
643           </informalfigure>
644           <para>
645             Shows overall data computed from the flight.
646           </para>
647         </section>
648         <section>
649           <title>Map</title>
650           <informalfigure>
651             <mediaobject>
652               <imageobject>
653                 <imagedata fileref="telegps-graph-map.png" width="6in" scalefit="1"/>
654               </imageobject>
655             </mediaobject>
656           </informalfigure>
657           <para>
658             Shows a map of the area overlaid with the GPS track. As with
659             the telemetry monitoring window, you can select the style
660             of map and zoom level using buttons along the side;
661             you can scroll the map by dragging within the map pressing
662             the left button and you can draw a line to measure
663             distances using either the left button with the shift key,
664             or any other button.
665           </para>
666         </section>
667       </section>
668       <section>
669         <title>Export Data</title>
670         <para>
671           This tool takes the raw data files and makes them available for
672           external analysis. When you select this button, you are prompted to 
673           select a data file, which can be either a .eeprom or .telem.
674           The .eeprom files contain higher resolution and more continuous data, 
675           while .telem files contain receiver signal strength information.  
676           Next, a second dialog appears which is used to select
677           where to write the resulting file. It has a selector to choose
678           between CSV and KML file formats.
679         </para>
680         <section>
681           <title>Comma Separated Value Format</title>
682           <para>
683             This is a text file containing the data in a form suitable for
684             import into a spreadsheet or other external data analysis
685             tool. The first few lines of the file contain the version and
686             configuration information from TeleGPS, then
687             there is a single header line which labels all of the
688             fields. All of these lines start with a '#' character which
689             many tools can be configured to skip over.
690           </para>
691           <para>
692             The remaining lines of the file contain the data, with each
693             field separated by a comma and at least one space. All of
694             the sensor values are converted to standard units, with the
695             barometric data reported in both pressure, altitude and
696             height above pad units.
697           </para>
698         </section>
699         <section>
700           <title>Keyhole Markup Language (for Google Earth)</title>
701           <para>
702             This is the format used by Google Earth to provide an overlay 
703             within that application. With this, you can use Google Earth to 
704             see the whole flight path in 3D.
705           </para>
706         </section>
707       </section>
708       <section>
709         <title>Load Maps</title>
710         <informalfigure>
711           <mediaobject>
712             <imageobject>
713               <imagedata fileref="load-maps.png" width="5.2in" scalefit="1"/>
714             </imageobject>
715           </mediaobject>
716         </informalfigure>
717         <para>
718           Before using TeleGPS, you can use Load Maps to load map data
719           in case you don't have access to the internet while
720           receiving telemetry.
721         </para>
722         <para>
723           There's a drop-down menu of rocket launch sites we know
724           about; if your favorites aren't there, please let us know
725           the lat/lon and name of the site. The contents of this list
726           are actually downloaded from our server at run-time, so as
727           new sites are sent in, they'll get automatically added to
728           this list.  If the launch site isn't in the list, you can
729           manually enter the lat/lon values
730         </para>
731         <para>
732           There are four different kinds of maps you can view; you can
733           select which to download by selecting as many as you like from
734           the available types:
735           <variablelist>
736             <varlistentry>
737               <term>Hybrid</term>
738               <listitem>
739                 <para>
740                   A combination of satellite imagery and road data. This
741                   is the default view.
742                 </para>
743               </listitem>
744             </varlistentry>
745             <varlistentry>
746               <term>Satellite</term>
747               <listitem>
748                 <para>
749                   Just the satellite imagery without any annotation.
750                 </para>
751               </listitem>
752             </varlistentry>
753             <varlistentry>
754               <term>Roadmap</term>
755               <listitem>
756                 <para>
757                   Roads, political boundaries and a few geographic features.
758                 </para>
759               </listitem>
760             </varlistentry>
761             <varlistentry>
762               <term>Terrain</term>
763               <listitem>
764                 <para>
765                   Contour intervals and shading that show hills and
766                   valleys.
767                 </para>
768               </listitem>
769             </varlistentry>
770           </variablelist>
771         </para>
772         <para>
773           You can specify the range of zoom levels to download; smaller
774           numbers show more area with less resolution. The default
775           level, 0, shows about 3m/pixel. One zoom level change
776           doubles or halves that number.
777         </para>
778         <para>
779           The Tile Radius value sets how large an area around the center
780           point to download. Each tile is 512x512 pixels, and the
781           'radius' value specifies how many tiles away from the center
782           will be downloaded. Specify a radius of 0 and you get only the
783           center tile. A radius of 1 loads a 3x3 grid, centered on the
784           specified location.
785         </para>
786         <para>
787           Clicking the 'Load Map' button will fetch images from Google
788           Maps; note that Google limits how many images you can fetch at
789           once, so if you load more than one launch site, you may get
790           some gray areas in the map which indicate that Google is tired
791           of sending data to you. Try again later.
792         </para>
793       </section>
794       <section>
795         <title>Preferences</title>
796         <informalfigure>
797           <mediaobject>
798             <imageobject>
799               <imagedata fileref="telegps-preferences.png" width="2.4in" scalefit="1"/>
800             </imageobject>
801           </mediaobject>
802         </informalfigure>
803         <section>
804           <title>Voice Settings</title>
805           <para>
806             AltosUI provides voice announcements during flight so that you
807             can keep your eyes on the sky and still get information about
808             the current flight status. However, sometimes you don't want
809             to hear them.
810           </para>
811           <variablelist>
812             <varlistentry>
813               <term>Enable</term>
814               <listitem>
815                 <para>Turns all voice announcements on and off</para>
816               </listitem>
817             </varlistentry>
818             <varlistentry>
819               <term>Test Voice</term>
820               <listitem>
821                 <para>
822                   Plays a short message allowing you to verify
823                   that the audio system is working and the volume settings
824                   are reasonable
825                 </para>
826               </listitem>
827             </varlistentry>
828           </variablelist>
829         </section>
830         <section>
831           <title>Log Directory</title>
832           <para>
833             AltosUI logs all telemetry data and saves all TeleMetrum flash
834             data to this directory. This directory is also used as the
835             staring point when selecting data files for display or export.
836           </para>
837           <para>
838             Click on the directory name to bring up a directory choosing
839             dialog, select a new directory and click 'Select Directory' to
840             change where AltosUI reads and writes data files.
841           </para>
842         </section>
843         <section>
844           <title>Callsign</title>
845           <para>
846             This value is transmitted in each command packet sent from 
847             TeleDongle and received from an altimeter.  It is not used in 
848             telemetry mode, as the callsign configured in the altimeter board
849             is included in all telemetry packets.  Configure this
850             with the AltosUI operators call sign as needed to comply with
851             your local radio regulations.
852           </para>
853           <para>
854             Note that to successfully command a flight computer over the radio
855             (to configure the altimeter, monitor idle, or fire pyro charges), 
856             the callsign configured here must exactly match the callsign
857             configured in the flight computer.  This matching is case 
858             sensitive.
859           </para>
860         </section>
861         <section>
862           <title>Imperial Units</title>
863           <para>
864             This switches between metric units (meters) and imperial
865             units (feet and miles). This affects the display of values
866             use during flight monitoring, configuration, data graphing
867             and all of the voice announcements. It does not change the
868             units used when exporting to CSV files, those are always
869             produced in metric units.
870           </para>
871         </section>
872         <section>
873           <title>Serial Debug</title>
874           <para>
875             This causes all communication with a connected device to be
876             dumped to the console from which AltosUI was started. If
877             you've started it from an icon or menu entry, the output
878             will simply be discarded. This mode can be useful to debug
879             various serial communication issues.
880           </para>
881         </section>
882         <section>
883           <title>Font Size</title>
884           <para>
885             Selects the set of fonts used in the flight monitor
886             window. Choose between the small, medium and large sets.
887           </para>
888         </section>
889         <section>
890           <title>Look &amp; Feel</title>
891           <para>
892             Adjust the style of the windows. By default, the TeleGPS
893             application attempts to blend in with the native style.
894           </para>
895         </section>
896         <section>
897           <title>Manage Frequencies</title>
898           <para>
899             This brings up a dialog where you can configure the set of
900             frequencies shown in the various frequency menus. You can
901             add as many as you like, or even reconfigure the default
902             set. Changing this list does not affect the frequency
903             settings of any devices, it only changes the set of
904             frequencies shown in the menus.
905           </para>
906         </section>
907       </section>
908       <section>
909         <title>Close</title>
910         <para>
911           This closes the current window, leaving any other windows
912           open and the application running.
913         </para>
914       </section>
915       <section>
916         <title>Exit</title>
917         <para>
918           This closes all TeleGPS windows and terminates the application.
919         </para>
920       </section>
921       <section>
922         <title>Connect Device</title>
923         <para>
924           Selecting this item brings up a dialog box listing all of
925           the connected TeleDongle devices. When you choose one of
926           these, AltosUI will display telemetry data as received by
927           the selected TeleDongle device.
928         </para>
929         <informalfigure>
930           <mediaobject>
931             <imageobject>
932               <imagedata fileref="device-selection.png" width="3.1in"/>
933             </imageobject>
934           </mediaobject>
935         </informalfigure>
936       </section>
937       <section>
938         <title>Disconnect</title>
939         <para>
940           Disconnects the currently connected TeleDongle or TeleBT
941         </para>
942       </section>
943       <section>
944         <title>Scan Channels</title>
945         <para>
946           Scans the configured set of frequencies looking for
947           telemetry signals. A list of all of the discovered signals
948           is show; selecting one of those and clicking on 'Monitor'
949           will select that frequency in the associated TeleGPS
950           application window.
951         </para>
952         <informalfigure>
953           <mediaobject>
954             <imageobject>
955               <imagedata fileref="telegps-scan.png" width="3.1in"/>
956             </imageobject>
957           </mediaobject>
958         </informalfigure>
959       </section>
960       <section>
961         <title>Download Data</title>
962         <para>
963           TeleGPS records data to its internal flash memory.
964           On-board data is recorded at the same rate as telemetry
965           but is not subject to radio drop-outs. As
966           such, it generally provides a more complete and precise record.
967           The 'Download Data' menu entry allows you to read the
968           flash memory and write it to disk. 
969         </para>
970         <para>
971           Select the 'Download Data' menu entry to bring up a list of
972           connected TeleGPS devices. After the device has been
973           selected, a dialog showing the data stored in the
974           device will be shown allowing you to select which entries to
975           download and which to delete. You must erase flights in order for the space they
976           consume to be reused by another track. This prevents
977           accidentally losing data if you neglect to download
978           data before starting TeleGPS again. Note that if there is no more
979           space available in the device, then no data will be recorded.
980         </para>
981         <para>
982           The file name for each data log is computed automatically
983           from the recorded date, altimeter serial number and flight
984           number information.
985         </para>
986       </section>
987       <section>
988         <title>Configure Device</title>
989         <informalfigure>
990           <mediaobject>
991             <imageobject>
992               <imagedata fileref="telegps-configure.png" width="3.6in" scalefit="1"/>
993             </imageobject>
994           </mediaobject>
995         </informalfigure>
996         <para>
997           Select this button and then select any connected TeleGPS
998           device from the list provided.
999         </para>
1000         <para>
1001           The first few lines of the dialog provide information about the
1002           connected device, including the product name,
1003           software version and hardware serial number. Below that are the
1004           individual configuration entries.
1005         </para>
1006         <para>
1007           At the bottom of the dialog, there are four buttons:
1008         </para>
1009         <variablelist>
1010           <varlistentry>
1011             <term>Save</term>
1012             <listitem>
1013               <para>
1014                 This writes any changes to the
1015                 configuration parameter block in flash memory. If you don't
1016                 press this button, any changes you make will be lost.
1017               </para>
1018             </listitem>
1019           </varlistentry>
1020           <varlistentry>
1021             <term>Reset</term>
1022             <listitem>
1023               <para>
1024                 This resets the dialog to the most recently saved values,
1025                 erasing any changes you have made.
1026               </para>
1027             </listitem>
1028           </varlistentry>
1029           <varlistentry>
1030             <term>Reboot</term>
1031             <listitem>
1032               <para>
1033                 This reboots the device. This will restart logging for
1034                 a new flight number, if any log information has been
1035                 saved for the current flight.
1036               </para>
1037             </listitem>
1038           </varlistentry>
1039           <varlistentry>
1040             <term>Close</term>
1041             <listitem>
1042               <para>
1043                 This closes the dialog. Any unsaved changes will be
1044                 lost.
1045               </para>
1046             </listitem>
1047           </varlistentry>
1048         </variablelist>
1049         <para>
1050           The rest of the dialog contains the parameters to be configured.
1051         </para>
1052         <section>
1053           <title>Frequency</title>
1054           <para>
1055             This configures which of the frequencies to use for both
1056             telemetry and packet command mode. Note that if you set this
1057             value via packet command mode, the TeleDongle frequency will
1058             also be automatically reconfigured to match so that
1059             communication will continue afterwards.
1060           </para>
1061         </section>
1062         <section>
1063           <title>RF Calibration</title>
1064           <para>
1065             The radios in every Altus Metrum device are calibrated at the
1066             factory to ensure that they transmit and receive on the
1067             specified frequency.  If you need to you can adjust the calibration 
1068             by changing this value.  Do not do this without understanding what
1069             the value means, read the appendix on calibration and/or the source
1070             code for more information.  To change a TeleDongle's calibration, 
1071             you must reprogram the unit completely.
1072           </para>
1073         </section>
1074         <section>
1075           <title>Telemetry/RDF/APRS Enable</title>
1076           <para>
1077             Enables the radio for transmission during flight. When
1078             disabled, the radio will not transmit anything during flight
1079             at all.
1080           </para>
1081         </section>
1082         <section>
1083           <title>APRS Interval</title>
1084           <para>
1085             How often to transmit GPS information via APRS (in
1086             seconds). When set to zero, APRS transmission is
1087             disabled. This option is available on TeleMetrum v2 and
1088             TeleMega boards. TeleMetrum v1 boards cannot transmit APRS
1089             packets. Note that a single APRS packet takes nearly a full
1090             second to transmit, so enabling this option will prevent
1091             sending any other telemetry during that time.
1092           </para>
1093         </section>
1094         <section>
1095           <title>Callsign</title>
1096           <para>
1097             This sets the call sign included in each telemetry packet. Set this
1098             as needed to conform to your local radio regulations.
1099           </para>
1100         </section>
1101         <section>
1102           <title>Maximum Log Size</title>
1103           <para>
1104             This sets the space (in kilobytes) allocated for each data
1105             log. The available space will be divided into chunks of this
1106             size. A smaller value will allow more logs to be stored,
1107             a larger value will record data for longer times.
1108           </para>
1109         </section>
1110         <section>
1111           <title>Logging Trigger Motion</title>
1112           <para>
1113             If TeleGPS moves less than this distance over a long period
1114             of time, it will not log that location, saving storage space.
1115           </para>
1116         </section>
1117         <section>
1118           <title>Position Reporting Interval</title>
1119           <para>
1120             This sets how often TeleGPS reports position information via
1121             telemetry and to the on-board log. Reducing this value will
1122             save power and logging memory consumption.
1123           </para>
1124         </section>
1125       </section>
1126       <section>
1127         <title>Flash Device</title>
1128         <para>
1129           This reprograms TeleGPS devices with new firmware. Please
1130           read the directions for flashing devices in the Updating
1131           Device Firmware chapter below.
1132         </para>
1133       </section>
1134     </section>
1135   </chapter>
1136   <chapter>
1137     <title>Updating Device Firmware</title>
1138     <para>
1139       TeleGPS is programmed directly over its USB connectors.
1140     </para>
1141     <para>
1142       You may wish to begin by ensuring you have current firmware images.
1143       These are distributed as part of the TeleGPS software bundle that
1144       also includes the TeleGPS ground station program.  Newer ground
1145       station versions typically work fine with older firmware versions,
1146       so you don't need to update your devices just to try out new
1147       software features.  You can always download the most recent
1148       version from <ulink url="http://www.altusmetrum.org/AltOS/"/>.
1149     </para>
1150     <section>
1151       <title>
1152         Updating TeleGPS Firmware
1153       </title>
1154       <orderedlist inheritnum='inherit' numeration='arabic'>
1155         <listitem>
1156           <para>
1157             Attach a battery and power switch to the target
1158             device. Power up the device.
1159           </para>
1160         </listitem>
1161         <listitem>
1162           <para>
1163             Using a Micro USB cable, connect the target device to your
1164             computer's USB socket.
1165           </para>
1166         </listitem>
1167         <listitem>
1168           <para>
1169             Run TeleGPS, and select 'Flash Device' from the Device menu.
1170           </para>
1171         </listitem>
1172         <listitem>
1173           <para>
1174             Select the target device in the Device Selection dialog.
1175           </para>
1176         </listitem>
1177         <listitem>
1178           <para>
1179             Select the image you want to flash to the device, which
1180             should have a name in the form
1181             &lt;product&gt;-v&lt;product-version&gt;-&lt;software-version&gt;.ihx, such
1182             as TeleGPS-v1.0-1.4.0.ihx.
1183           </para>
1184         </listitem>
1185         <listitem>
1186           <para>
1187             Make sure the configuration parameters are reasonable
1188             looking. If the serial number and/or RF configuration
1189             values aren't right, you'll need to change them.
1190           </para>
1191         </listitem>
1192         <listitem>
1193           <para>
1194             Hit the 'OK' button and the software should proceed to flash
1195             the device with new firmware, showing a progress bar.
1196           </para>
1197         </listitem>
1198         <listitem>
1199           <para>
1200             Verify that the device is working by using the 'Configure
1201             Altimeter' item to check over the configuration.
1202           </para>
1203         </listitem>
1204       </orderedlist>
1205 <!--
1206       <section>
1207         <title>Recovering From Self-Flashing Failure</title>
1208         <para>
1209           If the firmware loading fails, it can leave the device
1210           unable to boot. Not to worry, you can force the device to
1211           start the boot loader instead, which will let you try to
1212           flash the device again.
1213         </para>
1214         <para>
1215           On each device, connecting two pins from one of the exposed
1216           connectors will force the boot loader to start, even if the
1217           regular operating system has been corrupted in some way.
1218         </para>
1219         <variablelist>
1220           <varlistentry>
1221             <term>TeleMega</term>
1222             <listitem>
1223               <para>
1224                 Connect pin 6 and pin 1 of the companion connector. Pin 1
1225                 can be identified by the square pad around it, and then
1226                 the pins could sequentially across the board. Be very
1227                 careful to <emphasis>not</emphasis> short pin 8 to
1228                 anything as that is connected directly to the battery. Pin
1229                 7 carries 3.3V and the board will crash if that is
1230                 connected to pin 1, but shouldn't damage the board.
1231               </para>
1232             </listitem>
1233           </varlistentry>
1234           <varlistentry>
1235             <term>TeleMetrum v2</term>
1236             <listitem>
1237               <para>
1238                 Connect pin 6 and pin 1 of the companion connector. Pin 1
1239                 can be identified by the square pad around it, and then
1240                 the pins could sequentially across the board. Be very
1241                 careful to <emphasis>not</emphasis> short pin 8 to
1242                 anything as that is connected directly to the battery. Pin
1243                 7 carries 3.3V and the board will crash if that is
1244                 connected to pin 1, but shouldn't damage the board.
1245               </para>
1246             </listitem>
1247           </varlistentry>
1248           <varlistentry>
1249             <term>EasyMini</term>
1250             <listitem>
1251               <para>
1252                 Connect pin 6 and pin 1 of the debug connector, which is
1253                 the six holes next to the beeper. Pin 1 can be identified
1254                 by the square pad around it, and then the pins could
1255                 sequentially across the board, making Pin 6 the one on the
1256                 other end of the row.
1257               </para>
1258             </listitem>
1259           </varlistentry>
1260         </variablelist>
1261       </section>
1262     -->
1263     </section>
1264   </chapter>
1265   <chapter>
1266     <title>Technical Information</title>
1267     <section>
1268       <title>GPS Receiver</title>
1269       <para>
1270         TeleGPS uses the u-Blox Max-7Q GPS receiver.
1271       </para>
1272     </section>
1273     <section>
1274       <title>Micro-controller</title>
1275       <para>
1276         TeleGPS uses an NXP LPC11U14 micro-controller. This tiny
1277         CPU contains 32kB of flash for the application and 4kB of RAM for
1278         temporary data storage.
1279       </para>
1280     </section>
1281     <section>
1282       <title>Lithium Polymer Battery</title>
1283       <para>
1284         Shipping restrictions may prevent us from including a battery
1285         battery with TeleGPS.
1286       </para>
1287     </section>
1288     <section>
1289       <title>Mechanical Considerations</title>
1290       <para>
1291         TeleGPS is designed to be rugged enough for typical rocketry
1292         applications.  The 4 mounting holes on the board are sized for 
1293         use with 4-40 or M3 screws.
1294       </para>
1295     </section>
1296     <section>
1297       <title>On-board data storage</title>
1298       <para>
1299         TeleGPS has 2MB of non-volatile storage, separate from the
1300         code storage memory. The TeleGPS firmware uses this to log
1301         information during flight.
1302       </para>
1303     </section>
1304   </chapter>
1305   <appendix>
1306     <title>Release Notes</title>
1307     <simplesect>
1308       <title>Version 1.41</title>
1309       <xi:include
1310           xmlns:xi="http://www.w3.org/2001/XInclude"
1311           href="release-notes-1.4.1.xsl"
1312           xpointer="xpointer(/article/*)"/>
1313     </simplesect>
1314     <simplesect>
1315       <title>Version 1.4</title>
1316       <xi:include
1317           xmlns:xi="http://www.w3.org/2001/XInclude"
1318           href="release-notes-1.4.xsl"
1319           xpointer="xpointer(/article/*)"/>
1320     </simplesect>
1321   </appendix>
1322 </book>
1323 <!--  LocalWords:  Altusmetrum TeleGPS
1324 -->