GPS4Palm User's Manual

Table of Contents

Disclaimer and Copyright
Simulation Setup
Application Start
Menu Structure
Hard Keys
Main Forms
   Position Form
   Sky View Form
   Navigation Form
   Map Form
      Map Display
      Map Pan and Zoom
      Map Storage Format
      Map Scale
      Map Database Installation/Backup
      Map Storage on Memory Cards
      Map Selection
Approach Alert
Adding Position to Clipboard
Exporting Position via Memo to GeoDB
Option Forms
   Misc Options Form
   Map Options Form
Data Forms
   Waypoints Form
      Waypoint Edit Form
   Routes Form
      Route Edit Form
   Tracks Form
Data Exchange
Port Form
   Connecting to a Bluetooth GPS
Serial Port Multiplexing
About Form
Supplementary PalmOS Applications

Disclaimer and Copyright

GPS4Palm - PalmOS Mapping GPS Application 
	* displays GPS information
	* displays current position on map
	* automatic/manual map selection
	* automatic map download from internet
	  using external application FetchMap
	* navigation to selected waypoint
	* navigation along a route
	* track logging
	* waypoint, route, and track data exchange with host

Copyright (c)01/2003 M.Prinke <matthias.prinke(...)>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Please do not use this program for navigation!

See GNU GENERAL PUBLIC LICENSE for complete license.


This is the user's manual for GPS4Palm. It describes the current status of implementation. This document is accompanied by

Version0.9.4 beta
Creator IDGps4
Palm OS>=3.0
LibrariesMathLib, ZLib, gpslib
Miscrequired: GPS Receiver
opt.: FetchMap (Application),
Serial Port Multiplexer
GPSMan (PC Application)


The following items have to be installed on the PDA:

Simulation Setup

For testing or evaluating GPS4Palm, no actual PDA, GPS receiver or network interface (WLAN or mobile phone) is required. See section Simulation in the GPS4Palm Development Documentation for details.

Application Start

After launching GPS4Palm, a blank screen shows up for a few seconds while the application preferences are loaded, some libraries are opened and internal data structures are initialized. Depending on the PalmOS version (or exactly: version of the Serial Library), either the Port Form will be opened to let the user select the connection profiles for the serial ports the GPS receiver and the host are connected to or the default serial port settings will be applied.
If the GPS4Palm is started for the first time, the Position Form will be opened. On subsequent starts, the last main form (Position Form, Sky View Form, Navigation Form or Map Form) opened when the application was closed will be opened again.

Menu Structure

The menu entry Mode allows to select one of the four Main Forms. The menu entry Data allows to select the Waypoints Form, the Routes Form, and the Tracks Form and to copy the current position to the Clipboard or to the application GeoDB, respectively. The menu entry Options allows to access the Option Forms and the About Form. In addition to these menu entries available on all Main Forms, additional form specific entries may exist (e.g. the Map Form's Map menu).

Hard Keys

In addition to the menu entry Mode, the hard keys can be used to switch to any of the Main Forms:
No. Default Function Form
1 Calendar Position
2 Address Book / Contacts Sky View
3 ToDo / Tasks Navigation
4 Memos / Notes Map

Main Forms

Position Form

The Position Form shows the following information in textual form: The GPS Status can be
No NMEA messages can be received. This means the GPS receiver is either disconnected, switched off or not powered.
The NMEA messages indicate that the GPS data is invalid, because the satellite coverage and/or signal-to-noise ratio is poor.
The NMEA messages indicate valid GPS information.
The time is shown as provided by the NMEA RMC message, i.e. HH:MM:SS DD:MM:YY. Latitude and Longitude, Speed Over Ground and Altitude are shown in user selected units. See section Misc Options Form for details.

Note: Some GPS receivers do not provide magnetic variation data.

Sky View Form

The Sky View Form shows the following information: A description of the Status information can be found in the section Position Form.
The outer circle of the Sky View plot denotes 0 elevation, the inner circle 45 and the center 90. The azimuth is shown directly on the circle (0/north up).
The SNR is shown as provided by the NMEA message GSV in units of dBHz with a range of 0..100 (higher means better). Bars of satellites used by the GPS receiver for the position fix are filled.

The figure shows the status while the GPS receiver had been attached indoors to a window facing more or less southwards.

Navigation Form

The Navigation Form shows the following information: A description of the GPS status information can be found in the section Position Form. Please note that some information is shown only if an Active Waypoint exists. A tap on the Waypoint ID opens a form with some information about the active waypoint. A tap on the Route Number opens a form with some information about the active route. Please note that Time To Go is calculated from the current data (VMG, DST), no filtering or averaging is done. Speed and distance are always shown in the user selected units.
The Active Waypoint is selected depending on the navigation mode: Distance and direction to the waypoint are calculated using great circle formulae, i.e. the route to the waypoint is the orthodrome. A spheroidal model of the earth is assumed, but the distance calculation is slightly corrected by using the radius of the Earth at the latitude of the current position according to WGS84 in the calculation.
The ring shows the Course Over Ground (COG) in compass fashion, i.e. the heading is read from the top of the ring. The pointer in the inner circle shows the Bearing (BRG): it points straight upwards if COG=BRG.

Navigation Form Navigation Form,
Waypoint Info
Navigation Form,
Route Info

Navigation Terms
(with kind permission from Sigurd Humerfelt)

Map Form

Map Display

The Map Form displays the current position on a map. The map is rendered from a raster image (GIF or PNG format). A High-Density Display is supported if available (e.g. 320x320 pixels on a PalmOne Tungsten T3). The scale and center coordinates of the map as well as the coordinates of the current position are printed on the map. The GPS receiver status is currently not shown.
Currently the text might cover important parts of the map. A smart text overlay technique still has to be implemented. In addition to the map/position data, other information (e.g. concerning active waypoint) has to be taken into account.

Map Pan and Zoom

The map size may be greater than the screen size. Initially, the map is centered. By tapping with the stylus on the map, the center can be changed (panning).
Using the up/down hardware keys, the map can be zoomed. It is only possible to zoom out from the original size in integer steps (1..8). Zooming is implemented by sub-sampling the image without filtering - the algoritm is fast, but the result is usually not very appealing. However, the functionality is sufficient to gain an overview of a large map.
The FiveWay controller is supported if available. Pressing the center button toggles between Zoom and Pan mode:

Currently map panning is possible to view a map, but not handled correctly by the position display function. Therefore it is recommended to use maps equal to the screen size (160 x 160 pixels on standard screen, 320 x 320 or greater on high-density screen) to avoid confusion.

Map Storage Format

The maps are stored as a File Stream PDB (actually containing a GIF or PNG image) with Type-ID "DATA" and Creator-ID "BOXR". The latter has been chosen to allow interoperation with the program ZBoxZ for up-/downloading maps from/to the desktop and to allow removing maps from the PDA.

The PDB name (max. 31 characters) should be in the format
to store the geographic reference data in the filename.

either an integer or an integer followed by the letter k (x 1,000) or by the letter M (x 1,000,000)
latitude in degrees, positive: northern hemisphere / negative: southern hemisphere
longitude in degrees, positive: eastern hemisphere / negative: western hemisphere


Map Scale

In addition to the center position, the scale has to be set correctly in order to use a digital map with GPS4Palm properly. The scale of a (paper) map is defined as:
scale = d_real / d_map
distance in reality
distance on map

For a digital map, the distance on the screen is:
d_screen [pixels] = d_map [m] * r_map [dpi] * (1/0.0254) [1/m]
d_map = d_real / scale
resolution of digital map, typically in dpi (dots per inch)

Note: GPS4Palm assumes a map resolution of 72 dpi, otherwise geo referencing will not work correctly!

Map Database Installation/Backup

Any suitable PNG or GIF map file can be converted to a PDB file for use with GPS4Palm. The image file should be renamed as described in the section Map Storage Format to allow geo referencing. The programs linbox/winbox/macbox allow to convert the image file to a Palm Database file (PDB) on differrent host operating systems, while linunbox/winunbox/macunbox convert from PDB to a regular image file. These programms are included in ZBoxZ.

The generated PDB files can be installed from the desktop to the PDA like any other Palm OS file and retrieved from the PDA during hotsync or backup.

Map Storage on Memory Cards

GPS4Palm allows to store maps on external memory cards (e.g. SD-Cards) if the PDA provides this feature (in PalmOS terms: Virtual File System). The map image files must be located in the directory /PALM/Programs/gps4palm/. The images must be stored as GIF or PNG files (not PDB files!). The file names must be chosen as described in section Map Storage Format to allow geo-referencing.

Map Selection

The Map Form provides a Map menu entry. The menu item Select opens the Map Selection Form, which shows a list of all map files available as databases (PDBs) in internal memory or as regular GIF/PNG files on external memory card (if supported). In the latter case, a card icon is shown next to the filename.

The size (in bytes), the dimensions (in pixels) and the time and date of creation of the selected file are shown at the bottom. By selecting a filename and tapping the OK button, a map file is selected and GPS4Palm switches to user selected mode. In user selected mode, the selected map is shown independently of the current position, selected scale or a valid geo reference. The Cancel button allows to leave the Map Selection Form without changing the current map or the map selection mode.

A map file can be deleted by tapping the Delete button. A confirmation request which shows the name and storage location (internal memory or memory card) of the selected file is opened.

Automatic map selection is activated with the Auto button. In auto map selection mode, all files with appropriate geo reference (see section Map Storage Format) are examined. The first map with the selected scale (see section Map Options Form) showing the current position is selected. If no suitable map is found on the PDA, the download policy (see section Map Options Form) determines further actions.

If downloading is enabled (and optionally confirmed by the user), the external application FetchMap is invoked to download a new map with the selected scale and the current position at the map's center from a web server. FetchMap stores the map file with a database name/file name as described in section Map Storage. If FetchMap has successfully completed the web access, GPS4Palm switches to the new map. If FetchMap failed (because connection to the internet could not be established or the web server could not be reached), GPS4Palm will not try again to start fetchmap unless the user selects the menu entry Map->Fetch explicitely.

If no suitable map is available, because download is disabled or failed, the screen is cleared and the message "No map available!" is shown.

Please note that the PDA's serial port might have to shared between the GPS receiver and the network interface (e.g. mobile phone, modem). See section Serial Port Multiplexing for details.

Note: The message "No map available!" does not mean that no map is available at all, but that no map with the desired scale for the current position is available (automatic map selection) or that no map has been selected yet (manual map selection)!

Approach Alert

If selected in the Misc Options Form, an Approach Alert will be issued when the Active Waypoint (see Navigation Form) is approached and one of the Main Forms (Position Form, Sky View Form, Navigation Form or Map Form) is currently open.
The approach distance is either the Proximity Distance stored in the waypoint record (see Waypoint Edit Form) or the default approach distance (100 meters) if the Proximity Distance is zero. Please note that the Proximity Distance is always set to zero by downloading Waypoints from the host to GPS4Palm.
Depending on the settings in the Misc Options Form, the Approach Alert can be audible and/or visible:

Adding Position to Clipboard

The menu entry Data->Pos. to Clip. allows to copy the date and time of fix and the current position to the Clipboard.
Date and time have the format Y-M-D H:MM, the position format depends on the settings of the Misc Options Form.

Exporting Position via Memo to GeoDB

The menu entry Data->Pos. to GeoDB allows to copy the current position to a memo which in turn can be imported to GeoDB.
The memo has the following format:
Please refer to the GeoDB documentation for more details.

Option Forms

Misc Options Form

The Misc Options Form allows to disable auto-power off while GPS4Palm is running, enable/disable automatic waypoint selection in route navigation mode (see Navigation Form), to set the Approach Alert options (see section Approach Alert), to set the Track Log options (see section Tracks Form) and to select the preferred units for data display.

The following position formats are available:
Abbr. Units Example:
D Degrees N40.1793254
DM Degrees and Minutes N4010.7596'
DMS Degrees, Minutes and Seconds N4010'45.572"
UTM Universal Transversal Mercator
Zone Designator and Number,
Easting and Northing
53T 318035.4

The position shown always refers to the WGS84 coordinate system. UTM is restricted to latitudes from 80S to 84N. In some cases, a sign is used instead of the letters N/S and E/W according to the following convention:

Map Options Form

The Map Options Form allows to select the preferred map scale and the map download policy. If the Map Form is selected and automatic map selection is enabled (see section Map Selection), the download policy specifies what is done if no map with the selected scale is available for the current position:
Map download starts automatically without request.
Map download has to be confirmed by the user.
Map download is disabled

Data Forms

Waypoints Form

The Waypoints Form allows to add, remove and view waypoints. Furthermore, it allows to select a waypoint as "Active Waypoint" used as destination in the Navigation Form.
Each table row shows waypoint ID, latitude and longitude (or ID, field, easting and northing if UTM has been chosen as position unit). Below the table, the proximity distance, display mode (currently not used) and comment for the selected waypoint is shown.
During route, waypoint or track transfers (see section Data Exchange, status information is shown next to the label Xfer.
The buttons below provide the following functions: Please note that a waypoint cannot be deleted if it is part of any route. In this case, an alert informs about the first route which contains this waypoint.
Tapping the button New or Copy switches to the Waypoint Edit Form. All waypoints are kept in a single Waypoint Database (Name: "Waypoints-Gps4", Type: WAYP).

Waypoint Edit Form

The Waypoint Edit Form allows to enter a new waypoint into the database. Depending on the selected function in the Waypoint Form (New or Copy), editing is started either from a template indicating format and precision of the coordinates or from an existing waypoint.

The values entered into the coordinate fields are validated if either the field is deselected or the button OK is pressed. If the entry is invalid, the previous entry is restored. Since specific restrictions apply to UTM coordinates, the waypoint data entered may not be accepted even if the separate entries for the fields UTM Field, Easting and Northing have already been accepted. In this case, tapping on the OK button will not close the form until the waypoint data is valid or discarded.

In addition to the position, a waypoint consists of a Waypoint Name (up to 6 characters), a Proximity Distance (in meters; denotes the required distance until the waypoint is considered to be reached), the Display Mode (currently not used) and a comment (up to 39 characters).

The button OK adds the new waypoint to the database. The button Cancel discards the data. Tapping either OK or Cancel switches to the Waypoints Form. The button Here copies the coordinates of the current position to the fields. This works only if the current GPS status is valid. The button GeoDB copies the coordinates and additional information of the location selected in GeoDB to the fields, provided that GeoDB and a suitable database are installed.
New Waypoint
(Position Unit: Degrees)
Copy Waypoint
(Position Unit: Degrees)
New Waypoint
(Position Unit: UTM)
Copy Waypoint
(Position Unit: UTM)

Routes Form

The Routes Form lists all available routes and allows to add and delete routes. Furthermore, it allows to select a route as Active Route used for navigation (see Navigation Form) provided it contains at least two waypoints.
Each table row shows route number (0..255), a route comment and the number of waypoints on the route. The route number is either determined upon downloading a route from the host or created automatically (lowest unused number) upon creation of a new route. The comment of an Active Route is shown in bold.
During route, waypoint or track transfers (see section Data Exchange, status information is shown next to the label Xfer.
The buttons below provide the following functions: Tapping the button New or Edit switches to the Route Edit Form. All routes are kept in a single Route Database (Name: "Routes-Gps4", Type: ROUT).

Route Edit Form

The Route Edit Form allows to create a new route or to modify an existing one. The current route number and the route's comment is shown in the first line, the latter can be edited.
The table on the left shows all waypoints available in the waypoint data base. The table on the right lists all waypoints which are part of the selected route.
Waypoints can be added to the route with the Add-> button, the selected waypoint from the left is inserted after the selection on the right.
The Arrow Up/Arrow Down buttons allow to move the selected waypoint up or down in the route. A waypoint is deleted from the route using the Del button. When finished, tapping the Done button switches back to the Routes Form.

Tracks Form

The Track Form allows to create a new (empty) track, to delete a track and to start/stop logging. The table shows a the track's comment on the left and the current number of logged track points on the right. The default track comment (max. 49 characters) can be edited as desired.
The Active Track (i.e. the track selected for logging) is shown in bold. Track points are logged only while any of the main forms (Position Form, Sky View Form, Navigation Form or Map Form) is selected. The logging can be stopped and resumed later, even after exiting and re-opening GPS4Palm.
During route, waypoint or track transfers (see section Data Exchange, status information is shown next to the label Xfer.

The buttons below provide the following functions:

All track comments are kept in a single Track Header Database (Name: "Trkheaders-Gps4", Type: TRKH). The track points are kept in a separate Track Point Database for each track (Name: "Trkpoints-Gps4-xxxxxx" [xxxxxx: hex number, 6 digits], Type: TRKP).

The Misc Options Form allows to select the log mode (time or distance) and the log interval. Additionally, the behaviour upon reaching the maximum number of track points (65534 points per track) can be specified: logging will either be stopped or logging wraps to the log's start.
(Logging stopped)
(Logging started)

Data Exchange

Waypoints, Routes, and Tracks can be transferred from a host (desktop computer) to GPS4Palm and vice versa using the Garmin protocol. This allows to use a variety of applications written for Garmin's handheld GPS devices, such as GPSMan (see References). Before starting a waypoint, route or track transfer, either the Waypoints Form, the Routes Form or the Tracks Form has to be selected.

The data is transferred using the selected serial host interface (see Port Form) at 9600 baud. If a serial multiplexer is used, the host is connected instead of the GPS receiver (see section Serial Port Multiplexing). GPS4Palm provides the following product data information over the Garmin protocol:
GPS product ID: 72
Software version: 100
Product description: GPilotS manager
(This information is determined by the library gpslib which provides the Garmin protocol functionality.)

Note 1: The proximity distance information currently cannot be exchanged using the waypoint transfer protocol. The track comment information currently cannot be exchanged using the track transfer protocol.

Note 2: Due to a bug in gpslib, the host does not get a proper response when requesting data but the there is no data available.

Note 3: Due to a bug in gpslib, it is not possible to retrieve a full track point database from GPS4Palm. The upper size limit is currently unknown.

Note 4: A bug in the Serial Port Driver of PalmOS V5.2.1 on the Palm Tungsten T3 prevents gpslib (and other communication software as well) from working (see GPilotS Bugs page for a short note).
As a workaround, either connect the RTS and CTS signals of the Tungsten T3 (this conflicts with the Serial Port Multiplexing option) or buy the bug fix SerialFix by Larson Computing. Yes, you have to pay for it. Shame on Palm for not providing a patch!

Port Form

The Port Form will be opened on the first application start-up or by selecting the menu entry Options->Serial Ports if the New Serial Manager is provided by the PalmOS version installed on the PDA. It allows to select different serial port settings for the GPS receiver and for data exchange with the host from the connection profiles set up in the Connection Preferences Panel.
It has to be ensured that the GPS connection is configured to the appropriate baud rate (usually 4800 baud for NMEA compliant GPS receivers). The host port uses a fixed rate of 9600 baud.
The check box RTS Controls Multiplexer can be enabled to use the RTS output for controlling an external serial port multiplexer. (see Serial Port Multiplexing for details)

Port Baud Rate Usage Protocol
GPS Port 4800 baud GPS Data NMEA
Host Port 9600 baud Waypoint,
and Track
Data Exchange
with Host (e.g. PC)

Note: PDAs without the New Serial Manager Feature Set (e.g. Handspring Visor [Deluxe]) provide only a single serial port. On those devices, the PortForm is not available.

Note: Both GPS Port and Host Port configuration are completely independent of the serial port (if any) selected as part of the Network Connnection used by FetchMap.

Connecting to a Bluetooth GPS

The Port Form's serial port selector triggers provide all connections available from the Configuration Panel Communications/Connections. The connections list can contain serial port, infrared, and Bluetooth based connections. However, adding a Bluetooth based connection seems to work only for certain classes of devices such as mobile phones, desktop computers or PDAs, while a GPS receiver is not found in the search dialog -- even if it has already been set up as a trusted device in Communications/Bluetooth.

As a workaround for establishing a connection to a Bluetooth GPS receiver, just select an arbitrary Bluetooth connection in the Port Form (e.g. "BT to <any mobile phone>"). When tapping the OK button, the GPS receiver will appear in the list of available, known or trusted Bluetooth devices and can be selected.

GPS4Palm saves the Bluetooth Device Address of the selected GPS receiver. This allows to reconnect automatically without any user intervention after leaving and restarting GPS4Palm. The saved Device Address is updated upon selection of a different Bluetooth GPS receiver from the Port Form.

Serial Port Multiplexing

Downloading maps from Internet may require multiplexing of the PDA's serial port between GPS receiver and the network interface (mobile phone, modem), because most (if not all) PalmOS PDAs provide only a single serial port.

Newer PDAs provide the Connection Manager with a list of several serial connection types (such as Cradle/Cable, Bluetooth, Infrared) and connection targets (to Modem, to PC/Handheld, to GSM Phone). If different physical -- or in case of Bluetooth logical -- connections are used for the GPS receiver and the network connection, no serial port multiplexer is needed.


  1. GPS via serial port, GSM phone via Bluetooth
  2. GPS via Bluetooth, GSM phone via serial port
  3. GPS via Bluetooth, GSM phone via Bluetooth

If however both the GPS receiver and the network connection have to share a single serial port, a multiplexer is needed or the user has to plug and unplug the peripherals manually or to use a mechanical switch. The actual multiplexer hardware required depends on the logic levels of all interfaces. The PDA must provide an output port to control the multiplexer's select input. Unfortunately, if and how this works depends on the specific PDA model used, i.e. the required code cannot rely on a common PalmOS API function.
Recent devices with the New Serial Manager Feature Set allow to control the RTS output from the Serial Manager API. If the check box RTS Controls Multiplexer is activated on the Port Form, the RTS output is kept inactive (low level, "flow off"-state) by GPS4Palm. When the network connection is established, RTS is activated (high level, "flow on"-state). Thus, RTS can be used to control a serial port multiplexer.
In this case, Hardware Flow Control has to be disabled for the network connection, otherwise RTS will be deactivated as soon as the PDA's receive FIFO is full. Consequently, the baud rate has to be kept low enough to prevent FIFO overflows. Also see Note 4 in section Data Exchange for caveats on Palm Tungsten T and T3.

An example multiplexer circuit for the Handspring Visor (Deluxe) can be found in the GPS4Palm Development Documentation.

About Form

The About Form displays the GPS4Palm logo, version number and copyleft information (see GNU GENERAL PUBLIC LICENSE for complete license).

Supplementary PalmOS Applications

The following PalmOS applications might be useful in conjunction with GPS4Palm:


I would like to thank (in no particular order):



Bearing. Direction from current position to destination (e.g. active waypoint).
Course Made Good (also: Track, COG)
Course Over Ground (also: Track, CMG)
Dilution Of Precision. Indicates quality of fix depending on geometry of constellation of satellites in view.
Desired Track
Graphics Interchange Format
Global Positioning System Fix Data. NMEA-0183 sentence format.
GPS DOP and active satellites. NMEA-0183 sentence format.
Satellites in view. NMEA-0183 sentence format.
Horizontal Dilution Of Precision.
National Marine Electronics Association. Throughout this document, NMEA refers to the NMEA-0183 message format used by GPS receivers to transmit data to external devices.
Personal Digital Assistant
Position Dilution Of Precision
Portable Network Graphics
Recommended minimum specific GPS/Transit data. NMEA-0183 sentence format.
Signal to Noise Ratio.
Speed Over Ground
Turn. Angle between COG and BRG. The direction (right or left) indicates the direction to steer to decrease TRN.
Time To Go
Coordinated Universal Time or UTC, also sometimes referred to as "Zulu time", is an atomic realization of Universal Time or Greenwich mean time, the astronomical basis for civil time. Time zones around the world are expressed as positive and negative offsets from UT. UTC differs by an integral number of seconds from atomic time and a fractional number of seconds from UT1. (Excerpt from
Universal Transverse Mercator. Denotes both a grid reference system (comprised of Field [Zone and Belt], Easting and Northing) and a specific map projection.
Vertical Dilution Of Precision
Velocity Made Good. Velocity component in direction of destination.

Have a look at my homepage for updates and other interesting things. For comments or suggestions send me an email.
© 02/2003 M.Prinke <matthias.prinke(...)>
created: 2004/01/03 17:45:00
last update:$Date: 2005-05-28 10:21:52 $
$Revision: 1.19 $