GPS4Palm Development Documentation

Table of Contents

Disclaimer and Copyright
Overview
Simulation Setup
Event Loop
Serial Port Multiplexing
   Handspring Visor
   Other/Newer PDAs
Map Selection
Interface to FetchMap
Database Formats
   Waypoint Database
   Route Database
   Track Database
Data Exchange
References

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(...)surfeu.de>

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
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
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.

Overview

This is the development documentation for GPS4Palm. It describes the current status of implementation. This document is accompanied by

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

Simulation Setup

For testing or evaluating GPS4Palm, not actual PDA, GPS receiver or network interface (WLAN or mobile phone) is required.
The PalmOS Emulator [POSE] emulates any Motorola 68k-based Palm PDA. It allows to configure any host serial port to emulate the PDA's serial port.

Example:

  1. Connect your GPS receiver to the first PC serial port
  2. Start POSE
  3. Install GPS4Palm
  4. Select the serial port via the POSE menu entry Settings->Preferences
    (e.g. /dev/ttyS0 on Linux / COM1: on Windows)
  5. Start GPS4Palm - the GPS receiver data can now be received by GPS4Palm
In a similar fashion, a mobile phone can be connected to the PC to be used by the [FetchMap] running on POSE. Alternatively, POSE can replace the PalmOS networking stack by the host PC network stack (enable "Redirect NetLib calls to Host TCP/IP" in the menu entry Settings->Preferences).

The Perl/Tk application [NMEA-Sim] allows to simulate a GPS receiver. It sends NMEA messages to the specified PC serial port. Connecting this serial port to the serial port used by POSE with a null-modem cable allows to receive the NMEA messages in GPS4Palm.

The Linux tool [ttypatch] provides a very convenient replacement for the null-modem cable. See ttypatch documentation for additional features. (Unfortunately, for Windows only a commercial tool seems to exist.)

Example:

  1. Start ttypatch (in its default configuration, it provides a virtual connection between /dev/ttyp0 and /dev/ttyp1)
  2. Configure POSE to use the serial port /dev/ttyp1
  3. Start NMEA-Sim with nmea_sim.pl --port /dev/ttyp0
  4. The messages sent by NMEA-Sim can now be received by GPS4Palm
In a similar way, waypoint and route transfers between GPS4Palm and [GPSMan] can be tested.

To check the serial connection to the PDA, the Terminal Emulator mode of the PalmOS application [ptelnet] can be very helpful. [NMEA Mon] allows to Monitor the data (NMEA messages) sent by the GPS receiver.

The article Daten von Bluetooth GPS-Maus auslesen decribes how to connect a Linux PC with a Bluetooth USB dongle to a Bluetooth GPS receiver. The GPS data can then be read from a virtual serial port (e.g. /dev/rfcomm0).

Event Loop

The function EventLoop() in GPS.c implements the application's event loop. In addition to the standard Palm OS event dispatching, the function EvtGetEvent() is called with a time-out parameter to allow periodical reading of NMEA messages from the serial buffer and updating the display. The timeout can be modified dynamically by setting the global variable gNextReadTime accordingly.

If auto power-off is disabled by the user, EvtResetAutoOffTimer() is called in the event loop to keep the auto-off timer from expiring.

Any futher operations are done in the form specific event handlers. All forms requiring data from the GPS receiver call the function ReadFromGPS() (GPS.c) upon reception of a nilEvent. ReadFromGPS() waits until sufficient data is available in the read buffer, determines start and end of an NMEA message, verifies the message checksum and passes each valid message to the function HandleMessage() (HandleMessage.c). In HandleMessage(), the information of interest (depending on the selected form) is decoded and the display is updated.

Serial Port Multiplexing

Handspring Visor

Caution:
Some Serial Port Multiplexer code is specific to the Handspring Visor (Deluxe) or the Palm III Series, respectively. Please set the appropriate define with -D<sermux_option> in the CFLAGS option of the Makefile.
On any other PDA, the software might not work properly or even damage the hardware! If you are not sure that it will work on your PDA, please do not define any <sermux_option>.

The following options are available:
SERMUX_PALMIII_RTSPalm III RTS Pin (not tested thoroughly, now obsolete)
SERMUX_VISOR_HSHandspring Visor Hotsync Pin
SERMUX_VISOR_KBDHandspring Visor Keyboard Pin

If a GPS receiver and a network interface (such as a modem or a mobile phone) both have to be connected to the PDA's serial port, a serial port multiplexer is required. The main problem is to find a way to control the select signal of the multiplexer. Obviously, there is no API function provided to do this. If there is any appropriate signal available at an external connector depends on the brand and model of the PDA.
The tool [DragonRegs] allows to display the contents of the DragonBall registers. Tying the cradle connector signals of my Handspring Visor high/low, I found the corresponding bits in the port control registers. The cradle pins are directly connected via serial resistors to the DragonBall:

Pin Resistor I/O Port Bit
/HS1 (Hotsync) 100R Port D 4
/KBD (Keyboard) 330R Port E 7

With this information (and the help of the [Motorola Dragonball User Manual]), the multiplexer control functions sermux_enable() and sermux_select() in Utils.c have been implemented.

Care has to be taken regarding the voltage levels of all interfaces involved. The schematic in figure 1 shows a multiplexer circuit. In this example, the GPS receiver provides an output level slightly lower than the power supply (VCC). The GSM phone is attached using an adaptor cable with an interface logic similar to the circuit implemented with Q1/Q2 (see below). The Visor provides 3.3V logic levels and is attached without further interface logic to the circuit shown below. One drawback of this circuit is that a 5V power supply is required.


Figure 1: Serial Port Multiplexer for Handspring Visor (example)

Figure 2 shows an improved version of the multiplexer circuit. The 74VHCXXX series is ideal for interface circuits like this, because input voltages may even exceed VCC! Please refer to the 74VHC157 datasheet and your GPS receiver's datasheet for the actual supply voltage range. Since my GPS mouse already works with 3.8V, I can use 4 NiCd batteries as power supply.


Figure 2: Serial Port Multiplexer for Handspring Visor (example)

Note:
The solutions described above are specific to the Handspring Visor Deluxe. As far as I know, some Palm PDAs use internal level shifting circuits to generate true RS-232 voltage levels on the serial interface. Any information regarding other PDAs such as

are most welcome!

Other/Newer PDAs

Some more recent PDAs provide true RS-232 signal levels and a more complete set of serial port signals:
Signal Name Function
SG Signal Ground
RXD (in) Receive Data
TXD (out) Transmit Data
CTS (in) Clear To Send (Hardware Flow Control Handshake)
RTS (out) Request To Send (Hardware Flow Control Handshake)
DTR Data Terminal Ready

See [Hardware Connection Diagrams] for the following documents:

The DTR signal would be the ideal choice for controlling the multiplexer, because it is not required for Hardware Flow Control. The New Serial Manager Feature Set of the Serial Manager API provides the control code srmCtlSetDTRAsserted for the function SrmControl() to assert/deassert the DTR pin. However, according to the PalmOS Programmer's API Reference (SDK-4): "This is not supported by all hardware."
On a Tungsten T3, the function call

err = SrmControl(gPortID, srmCtlSetDTRAsserted, &value, &valueLen);
returns the error code serErrNotSupported.

This leaves the RTS signal for controlling the multiplexer, provided that RTS/CTS Hardware Flow Control is not required. For the GPS receiver with a data rate of 4800 baud this is the case. For the network connection (e.g. over a GSM phone), this might restrict the possible baud rate to a low value to prevent receive FIFO overflows.
The Serial Manager API function SrmControl() allows to disable hardware flow control and to control RTS by software.

Note: Due to a bug in the Serial Port Driver of PalmOS V5.2.1 on the Palm Tungsten T3, serial communications without hardware flow control seems not to work on this PDA. (see GPilotS Bugs page for a short note)
As a workaround, it is proposed to connect the RTS and CTS signals of the Tungsten T3, however this conflicts with the usage of RTS for controlling the multiplexer.
PalmOne did not provide a patch yet, but a commercial bug fix SerialFix by Larson Computing is available.

The application note [Multiplexer Enables Pseudomultidrop RS-232 Transmission] describes a 4-to-1 multiplexer for RS-232 signals (true RS-232 signal levels). Even if reduced to a 2-to-1 multiplexer, the hardware effort is relatively high. Other proposals are welcome.

Map Selection

TODO: add description

Map Selection Mode

gPrefs.mapprefs.select:
SEL_USER
User selected map
SEL_AUTO
Auto selected map

Map Fetch State

gPrefs.mapprefs.fetch:
FETCH_READY
Fetching can be (re)started
FETCH_START
Fetching has been started
FETCH_STOP
Fetching disabled

Map Download Mode

gPrefs.mapprefs.download:
DLD_A
Download automatically
DLD_Q
Download after query
DLD_O
Download off


User selected Map
(gPrefs.mapprefs.select == SEL_USER)


Auto selected Map, frmOpenEvent handling
(gPrefs.mapprefs.select == SEL_AUTO)


Auto selected Map, map searching and fetching
(gPrefs.mapprefs.select == SEL_AUTO)

Interface to FetchMap

Downloading map files from web based servers is handled by the application [FetchMap]. It would be possibe to integrate its functionality in GPS4Palm, but keeping it separately has the advantages that
FetchMap is called from the function callFetchmap() in MapForm.c. First a parameter block is allocated and filled with the following data:
After it has been checked that FetchMap is available on the PDA, the ownership if the parameter block is passed (from the application) to the operating system. Otherwise it would be deallocated after stopping GPS4Palm. callFetchMap() closes the serial port, changes the serial port multiplexer from GPS receiver to mobile phone (default) and saves the Application Preferences. Finally FetchMap is started using the system call SysUIAppSwitch(). (see [Application Launching] for details)

FetchMap recognizes that is has been called from another application, because of the non-zero parameter block (this is different from the PalmOS Application Launcher) and immediately tries to establish a network connection and to download the requested map. The only user interfaces are the Progress Manager called from FetchMap and the network connection dialogs, i.e. FetchMap does not open a Form. After downloading the map (or failing because of a bad network connection or a user abort), FetchMap is stopped and GPS4Palm is started again automatically (due to the system call SysUIAppSwitch() in GPS4Palm).

GPS4Palm resumes with the Form selected previously (stored in the Application Preferences), i.e. the Map Form. Most likely the user will hardly notice that a separate application is involved.

Databases

Waypoint Database

The GPS4Palm waypoint database format mostly follows the D104_Wpt_Type described in the [GARMIN GPS Interface Specification] with the following differences: The comment string is packed, i.e. instead of occupying a fixed length of 40 characters (actually 39 + '\0'), the length is adapted to the actal contents. Since the Database Record size is maintained by the PalmOS Data Manager functions in the Database Header, a separate length field is not needed.

The resulting datatype is:

typedef struct {
  char			ident[6];	/* identifier (string)            */
  Semicircle_Type	posn;		/* position                       */
  float			dst;		/* proximity distance (meters)    */
  Symbol_Type		smbl;		/* symbol ID                      */
  byte			dspl;		/* display option                 */
  char			cmnt[1];        /* comment, actually may be       */
                                        /* longer than 1, but no more     */
					/* than 40                        */
					/* (including null terminator)    */
} packed_waypoint_t;
Each waypoint record requires 22..61 bytes. The Waypoint Database has the name "Waypoints-Gps4" and the type 'WAYP'. The waypoint records are sorted alphanumerically within the database according to their identifier.

Route Database

The GPS4Palm route database format stores the route header according to the D201_Rte_Hdr_Type described in the [GARMIN GPS Interface Specification]. The comment field provides additional space for a string delimiter ('\0'). Additional fields are provided for internal use: Since the route database stores just references to the waypoint records in the waypoint database, the available memory is used quite efficiently. If the waypoint database has been deleted, the route database is invalid (and thus will be deleted opon application start).

The resulting datatype is:

typedef struct {
  G_byte	nmbr;			/* route number */
  G_char	cmnt[21];		/* comment */
  UInt16	items;			/* number of waypoints on route   */
  UInt32	wpt_rec_id[1];		/* array of waypoint record IDs,  */
  					/* actually may be longer than 1  */
} route_t;
Each route requires 24 bytes for the header plus 4 bytes for each route waypoint. The Route Database has the name "Routes-Gps4" and the type 'ROUT'. The route records are sorted within the database according to the route number.

Track Databases

The GPS4Palm track header database format stores the track headers according to the D310_Trk_Hdr_Type described in the [GARMIN GPS Interface Specification]. The number of tracks is limited to 255, but this limit has been chosen arbitrarily.

The track header record datatype is:

typedef struct
{
  G_boolean dspl;		/* display on the map? */
  G_byte color;			/* color (same as D108) */
  G_char trk_ident[50];		/* null-terminated string */
}
D310_Trk_Hdr_Type;
Currently trkhdr.dspl is set to true and trkhdr.color is set to Default_Color upon creation of a new route. The Track Header Database has the name "Trkheaders-Gps4" and the type 'TRKH'.

The track points are stored in a separate database for each track. The Track Point Databases have the naming scheme "Trkpoints-Gps4-xxxxxx", where "xxxxxx" is the 3-byte unique record ID (hex; 0..9,A..F) of the associated track header. The Track Point Database type is 'TRKP'.

The GPS4Palm track point database format stores the track points according to the D300_Trk_Point_Type described in the [GARMIN GPS Interface Specification]. The maximum number of track points per track is 65535 (maximum number of records per PalmOS database).


Figure 3: Track Header Database and Track Point Databases

Each track header requires 52 bytes, eack track point requires 13 bytes.

Note:
Exchange of track header information with the host is currently not supported.

Data Exchange

Data can be transferred from a host (desktop computer) to GPS4Palm and vice versa using the Garmin protocol (see [GARMIN GPS Interface Specification]). This feature is provided by [gpslib]. GPS4Palm requires gpslib Rev. 1.33.
The data is transferred using the serial interface at 9600 baud. If a serial multiplexer is used, the host is connected instead of the GPS receiver (see section Serial Port Multiplexing). Switching between GPS (NMEA) data reception and Garmin data exchange requires the following steps (see WaypointForm.c, RouteForm.c or TrackForm.c):
  1. close serial port
  2. call GarminSetHostMode() to open serial port at 9600 baud, initialize gpslib and enable Host Mode; this also configures the Garmin GPS device emulated by GPS4Palm (Garmin III)
  3. host establishes connection (query of GPS device information and protocol capabilities)
  4. data transfers (upload and/or download)
  5. call GPSEndOfOperation() to terminate Garmin mode and close serial port
  6. open serial port for NMEA reception at 4800 baud
GPS4Palm provides the following product data information (defined by gpslib):
GPS product ID: 72
Software version: 100
Product description: GPilotS manager
Currently only the following exchange protocols/data types have been implemented:

References


Have a look at my homepage for updates and other interesting things. For comments or suggestions send me an email.

http://members.surfeu.de/matthias.prinke/gps4palm_e.html
© 02/2003 M.Prinke <matthias.prinke(...)surfeu.de>
created: 2004/01/03 17:45:00
last update:$Date: 2005-05-28 10:19:15 $
$Revision: 1.18 $