GPilotS

Version:

6.4

Date:

august 2004

Introduction

GPilotS is a waypoints, routes and tracks manager for PalmOS devices. It can upload and download them to numerous Garmin GPSes and act itself as a Garmin GPS to exchange datas with desktop software able to communicate with Garmin GPSes. It uses gpslib for that. It can also create and edit waypoints and routes and display them graphicaly as well as traces. Conversion between different Garmin formats is automatic.

Development environment

GPilotS is developped under Linux with prc-tools 2.3, pilrc and SDK 4. It's tested with POSE and gdb. gtalk.rcp contains ressources declarations compiled by pilrc.

Structure of GPilotS

GPilotS is highly modular : there is roughly one module (and associated include) by form or/and function.

The main module is gtalk.c, it's the entry point of GPilotS, it initializes and/or opens the data bases and the libraries and handles the main form. gtalk.rcp contains the user interface and translations.

Debugging

Debugging macros may be compiled in GPilotS's code via the DEBUG macro defined in the Makefile. At run time a debug level is set via a dedicated form called by writting a '.' in the main form. Debugging level may be set independently for 3 parts of the code : gpslib, utilities (gpsutil.c and objects.c) and the main part of the code. There are 3 common levels : "calls" to trace procedures calls, "unexp" to trace unexpected things and "infos" for other details. The debug outputs are written in a memo.

Objects management

Datas are stored as objects of type Object (except track points) defined in types.h. This is a container with a header part and a data part. The data part may be a waypoint, a route header, a track header,... The header identifies the type of datas contained and their size. GPilotS try to support as many different Garmin formats as possible but, to simplify conversion and editing code, it has it's own custom formats.

Waypoints : to allow storing and exchange without loss of information, even if some of them are not handled by GPilotS, waypoints are stored (in an Object structure) as they are received. To manipulate a waypoint, GPilotS converts it to the Custom_Wpt_Type type. So the displaying and editing code has to handle only one format.

Routes : a Custom_Rte_Hdr_Type header is created or derived from the original header if present. It's followed by waypoints stored as above.

Tracks : a Custom_Trk_Hdr_Type header is created followed by 2 possible formats of track points : Custom_Trk_Point_Type or Compact_Trk_Point_Type. Compact_Trk_Point_Type is a "light" format without date and altitude information to save memory and allow longer traces by record.

Databases management

GPilotS use standard PalmOS data bases to store GPS datas. They have the creator id 'GPil' and types 'Wpts', 'Trks' and 'Rtes'. Older versions used one dedicated data base by object type named "TrkDB-GPil", "RteDB-GPil" and "WptDB-GPil". Current ones allow their users to create as many data bases as they want with the names they like.

Waypoints : Each record contains an Object structure with a Garmin waypoint inside whose type is stored in header.type.

Routes : Each record contains a route composed of one or more Object structures : one for the route header and zero or more waypoints.

Tracks : Tracks DB are a special case : for efficiency raisons track points are not in an Object structure. Each record contains a track stored has follows :

• first an Object structure containing the track header (generally of type Custom_Trk_Hdr_Type)
• followed by track points (Custom_Trk_Point_Type or Compact_Trk_Point_Type).

Warning : the number of track points indicated in the track header may not be accurate. TrkptsInTrkDB is used to get a track's number of points.

---