manual.html

A car navigation system for Unix and PocketPC.

abbreviations listed by the US Census Bureau (N for north, E for east, Blvd
for boulevard, etc..). In almost all cases, the US Census Bureau conventions
follow the usual abbreviations, so there is no need to worry here. In
addition, any of these fields is optional: not providing them only makes the
search less selective. If several matches are found, RoadMap shows a list of
all matching streets and lets the user select the appropriate one.</p><p>The
exact format of the data expected by RoadMap as a complete street name is as
follow:</p><pre>         [prefix ' '] name [[' ' suffix] ' ' type]</pre><p>The
name itself may include space characters. Potential conflicts are resolved by
excluding the prefix, suffix and type fields from the name only when a match
is found with the valid set for that county. As such, the following names
would work OK in any
circumstances:</p><pre>         N Rio del Sol St   --&gt; RoadMap detects both a prefix and a type.
         Rio del Sol St     --&gt; RoadMap detects the type, no valid prefix.
         N Rio del Sol      --&gt; RoadMap detects the prefix, no valid type.
         Rio del Sol        --&gt; RoadMap detects no valid prefix or type.</pre><p>Lets
go through an example: we will search for 100 East Washington Boulevard in Los
Angeles, California. The name of the street should be typed as
follow:</p><pre>         e washington blvd</pre><p>The 'e' stands for
&quot;east&quot;, 'blvd' stands for boulevard, according to the US Census
Bureau documentation. Note that RoadMap is not case sensitive.</p><p>The
result is a single match, so RoadMap shows the location immediately without
any additional question. However it is possible to omit either the prefix,
street type, or both, with the effect of broadening the search. Let say we
entered:</p><pre>         washington blvd</pre><p>Now RoadMap display a dialog
that lists 3 matches:</p><pre>         Washington Blvd, Los Angeles
         W Washington Blvd, Los Angeles
         E Washington Blvd, Los Angeles</pre><p>The first item in the list is
shown selected, and RoadMap displays a new location in the map display. In
fact, each time the user selects one address in the list, RoadMap displays the
corresponding map location. When the user hits the OK button, this simply
confirms the current choice as the final one.</p><p>Note that not providing a
prefix, suffix or street type does broaden the search, but the street name
must always be provided in full: at that time RoadMap provides only an exact
street names search. Thus providing &quot;wash&quot; instead of
&quot;washington&quot; only triggers the error message &quot;No street with
that name could be found&quot;.</p><h2><a id="id.s5.9" name="id.s5.9">5.9
</a>OTHER ADDRESS
OPTIONS<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>It is possible not to specify the street number part of an address: in that
case, all street blocks matching the street and city names will be listed. Be
careful, that might make a long list, and RoadMap has a limit of 256 items per
list (matching items beyond the 256th one are discarded).</p><p>It is also
possible to specify an approximate city search: if the city name is prefixed
with a character '?', then the name of the city is used to find the county,
but is not used in the street match: the idea is to list all similar addresses
around (i.e. in the county). This is useful when one is not sure of the city
name, or only knows the name of a city
nearby.</p><h2><a id="id.s5.10" name="id.s5.10">5.10 </a>SELECTING AN
INTERSECTION<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>The &quot;Find / Intersection..&quot; menu entry activates a dialog that
asks for two street names and a state name. RoadMap will search within the
given state for all intersections between streets that match the street names
provided. This search may take a few seconds, especially if the maps must be
read from disk.</p><p>In the (likely) case where multiple intersections have
been found, RoadMap displays a list that shows the name of the city and the
name of the county where each intersection is located. This selection list
follows the same rules as the address selection list described in the previous
sections.</p><h2><a id="id.s5.11" name="id.s5.11">5.11 </a>SELECTING A
POSITION<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>The &quot;Find / Position..&quot; menu entry activates a dialog that asks
for a longitude / latitude position. The format for the longitude and latitude
must conform to the ISO 6709-1983 standard (with some extensions).</p><p>The
format for longitude is:</p><pre>   [+-EW][d]dd[mm[ss]][.ffffff]</pre><p>The
format for latitude is:</p><pre>   [+-NS]dd[mm[ss]][.ffffff]</pre><p>Where
&quot;[d]dd&quot; or &quot;dd&quot; stands for the degrees, &quot;mm&quot;
stands for the minutes, &quot;ss&quot; stands for the seconds and
&quot;ffffff&quot; stands for the fractional part (either fraction of degrees,
minutes or seconds, depending on the context).</p><p>The main extensions
compare to ISO 6709 are as follow:</p><ul>
<li>the letters 'E', 'W', 'N' and 'S' are recognized as a replacement for '+'
or '-'.</li>
<li>the longitude may be expressed with 2 digits for the degrees.</li>
</ul><h2><a id="id.s5.12" name="id.s5.12">5.12 </a>MANAGING
<a id="trips" name="trips">TRIPS</a><a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>A trip is made of one destination point and many user-defined waypoints.
The purpose of a RoadMap trip is to describe a real-life trip and to provide
the user information about the trip progress.</p><p>RoadMap supports an
infinite number of trips: each trip context is saved in a trip file. One trip
at a time can be edited or activated. A saved trip can be reloaded from the
trip file, of course. each trip support an infinite number of
waypoints.</p><p>The last trip created or loaded will be reloaded the next
time RoadMap starts.</p><p>A trip must have been loaded before it can be
edited. There are three trip edition actions available in the
&quot;Trips&quot; menu: set the destination point, add a waypoint or remove a
waypoint. The destination point is defined using a street address by selecting
the &quot;Set Destination..&quot; entry. A waypoint is added by highlighting a
location on the map and then selecting the &quot;Add as Waypoint&quot; entry.
Waypoints can be deleted by selecting the &quot;Delete Waypoints..&quot;
entry, then selecting a specific waypoint and hitting the &quot;Delete&quot;
button.</p><p>A trip that has been created or loaded can then be activated.
Activating a trip defines the departure point (the current GPS location) and
enable the &quot;trip display&quot; mode, i.e. some trip information displayed
on top of the map. These trip displays include an arrow beside the GPS
location symbol to indicate the direction of the next waypoint (if any) or
else of the destination, as well as user configurable messages, such as
distance information, at the corners of the map. (see CONFIGURATION for more
information about these user configurable messages).</p><p>When a trip is
active, RoadMap tracks the GPS position in realtime and updates its map
accordingly. The GPS position can be shown in two modes: either North up, or
GPS direction up. In the second case, the map is rotated according to the
direction information received from the GPS. This dynamic rotation is in
addition to the map manual rotation.</p><p>A trip can be stopped at any time
and then resumed. Resuming a trip does not modify the departure point. The
trip can also be resumed in reverse mode: in that case the departure point and
the destination point switch roles. Note that this does not modify the trip,
only the way RoadMap uses the trip information. The reverse mode makes it
possible to use the same RoadMap trip on the way back.</p><p>When starting a
trip, the map will rotate to match the orientation of the vehicule. This
display mode is the most convenient as it matches the driver's or passenger's
view. It is however possible to switch the display in the &quot;North Up&quot;
mode by selecting the &quot;Trips / Resume Trip (North Up)&quot; menu
entry.</p><p>The reserve trip always works in the same mode as previously
selected the last time the trip was started or resumed: for example, if the
&quot;North Up&quot; mode was selected when the trip was resumed, then the
reverse trip will still use this &quot;North Up&quot;
mode.</p><h2><a id="id.s5.13" name="id.s5.13">5.13 </a>ROADMAP
PREFERENCES<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>It is possible to edit the roadmap's preferences (select File/Preferences
from the menu bar). Most preference items take effect only when roadmap start,
so quitting roadmap is usually required. Editing the roadmap preferences
requires a keyboard to be available. One way to configure the iPAQ preferences
is to run roadmap from the iPAQ, redirected to the desktop's or laptop's X
server.</p><h1><a id="id.s6" name="id.s6">6 </a>USING
ROADGPS<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h1>
<p>The RoadGps tool can be started on its own (using command line options
similar to those of RoadMap), or from the RoadMap's File / GPS Console menu
item.</p><p>The screen shows the list of satellites, their position in the sky
(north up) and the strength of the signal. It marks in reverse video those
satellites used to compute the current position.</p><p>More importantly,
RoadGps allows to log all the NMEA sentences received. RoadGps rotates through
up to 127 log files. The log file are created in /var/tmp, with the name
formatted as: &quot;roadgps-%d.log&quot; (where %d represents an integer in
the range 1..127).</p><p>This log file can be replayed in RoadMap using the
--gps option with an absolute file name as an argument. For
example:</p><pre>       roadmap --gps=/var/tmp/roadgps-1.log</pre><p>When
RoadGps starts, the logging function is off. Whenever the logging function is
turned on a new log file is created (if the logging function was already on,
the current log file is closed and a new one is created).</p><p>RoadGps uses a
subset of the RoadMap preferences setup, but has no preferences editor of its
own: configure RoadMap first, and then use
RoadGps.</p><h1><a id="id.s7" name="id.s7">7
</a>CONFIGURATION<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h1>
<h2><a id="id.s7.1" name="id.s7.1">7.1
</a>FILES<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>The RoadMap configuration is stored in text files located in the following
directories:</p><pre>            /usr/share/roadmap
            /usr/local/share/roadmap
            /etc/roadmap
            ~/.roadmap (equivalent to &quot;&amp;&quot; in RoadMap)
            ~/.roadmap/trips (equivalent to &quot;&amp;/trips&quot; in RoadMap)
            ~/.roadmap/maps (equivalent to &quot;&amp;/maps&quot; in RoadMap)</pre><p>The
first four directories are searched sequentially: any configuration item found
in one directory overrides all the same items found in the directories listed
before. In other words, the configuration is loaded in the following
order:</p><p>1- /usr/share/roadmap (installation defaults)</p><p>2-
/usr/local/share/roadmap (local site defaults)</p><p>3- /etc/roadmap (local
machine defaults)</p><p>4- ~/.roadmap (current user configuration)</p><p>The
directory <b>~/.roadmap</b> contains the user configuration: any user change
to the configuration is written there. The items in the user configuration
take precedence over the &quot;default&quot; configuration in the
&quot;shared&quot; directories.</p><p>The directory <b>~/.roadmap/trips</b> is
used as the default location for the trip files. Note that trip files can be
stored anywhere, not only in <b>~/.roadmap/trips</b>.</p><p>The directory
<b>~/.roadmap/maps</b> contains map files specific for this user. As a general
rule, it is not recommended for each user to have their own copy of the maps,
as these maps take a lot of space. This directory can be used however when
maps are downloaded on the fly, as shared maps are usually not writable for
users. The local rules can be established so that either all users download
maps into the shared repository, or else each user manages his own maps. On a
PDA or on a personal desktop systems the first solution makes the more sense,
but for public access computers (such as computers at an University) the
second solution might be the most convenient.</p><p>The user configuration
directories are created when needed, if they do not exist.</p><p>The syntax of
most RoadMap configuration files is similar to the X ressources file format
(the exceptions are the sprites file and the trip files). Each configuration
item is represented by one line of text, using the following
format:</p><pre>            name ': ' value</pre><p>The following
configuration files are used:</p><dl compact>
<dt><b>schema</b></dt>
<dd>The definition of the geographic entities.</dd>
<dt><b>preferences</b></dt>
<dd>User's preferences.</dd>
<dt><b>session</b></dt>
<dd>The latest context used (locations)</dd>
<dt><b>sprites</b></dt>
<dd>The definition of the graphic symbols</dd>
</dl><p>The session file contains the state of roadmap, which is saved (if
needed) when roadmap exits. The preferences file contains all the preferences
items, and can be edited by the user. The schema file describes the geographic
entities that are shown on the map; it should normally not be modified by the
users. The sprites file contains the graphical definition of the symbols usd
by RoadMap to indicates the various locations, to draw the compass,
etc..</p><h2><a id="id.s7.2" name="id.s7.2">7.2 </a>CONFIGURING THE TEXT AND
VOICE
MESSAGES<a href="#id.toc"><img src="apt_toc.gif" border="0" width="30" height="11" alt="Contents"></a></h2>
<p>The RoadMap text displays and voice messages can be configured by the user
using format strings in the preferences. The format strings contain static and
dynamic parts. The dynamic parts (or &quot;macros&quot;) are specified using
the character '%' followed by one character that denotes a predefined RoadMap
variable.</p><center><table border="1">
<tr valign="top">
<td align="left">A:</td>
<td align="left">estimated time of arrival (not yet implemented).</td>
</tr>
<tr valign="top">
<td align="left">B:</td>
<td align="left">Route bearing (not yet implemented).</td>
</tr>
<tr valign="top">
<td align="left">C:</td>
<td align="left">the name of the city for the selected or current street.</td>
</tr>
<tr valign="top">
<td align="left">D:</td>
<td align="left">Distance to the destination time (set only when a trip is