Gypsy Documentation


I wrote Gypsy to help me in my travels. I wanted an easier way of manipulating waypoint databases than using the Garmin multi-purpose button, and did't want to schlepp a Mac Powerbook into the wilds when I went travelling. Gypsy is also my first stab at a Palm application, so it has a few rough edges.

Obviously, to up-and download, you'll need a serial cable from your Palm to the GPS. My GPS II+ is usually mounted in my Land Rover, with a Garmin power cable. I have connected the Tx and Rx data conductors to a DB9 connector on the daskboard, and use a Palm modem cable to connect my Palm to the GPS while on the move. There are some pictures of this at <>.

The basic idea is that you can download waypoints from your Garmin GPS into a number of different databases on the Palm. These can then be manipulated (names edited, databases merged, waypoint deleted) and can be uploaded to the GPS when the time is right. While you can edit latitude and longitude on the Palm, I wouldn't recommend it, because I haven't written anything to cope with the different co-ordinate systems. You may just find yourself a long, long way from where you expect to be.

Gypsy can also download and buffer your routes and track log. This allows you to transfer this information between your GPS and PC without the two having to be directly linked. It can be useful if your GPS is permanently mounted in a vehicle and you haven't got a laptop (or prefer to carry the smaller Palm).

The program's name

This program was originally called "Gulliver" (after my cat, who is a great explorer and likes playing with my GPS). However, after submitting it to Palm Central, I discovered that Landware have a product called "Gulliver", so I have renamed this release to Gypsy. This is the name of Gulliver the cat's sister, and is almost a pun on GPS. Karen Nakamura has a fine GPS program for Apple Macintoshes called GPSy, which is a better pun.

There is no relationship between me and Karen, or between "Gypsy" and "GPSy" (other than the fact that I own a legal copy of GPSy which I use from time to time). Let me apologise in advance for any confusion that this may cause. If Karen hears about "Gypsy", I hope that she will take this as a compliment, as her program, is a fine piece of work, and does far, far more than "Gypsy" was ever intended to.

Operation: waypoints

When you first start Gypsy, it will create a new database called "GPS Waypoint DB". At this point, you will probably want to connect a hotsync cable to your Garmin data cable, and use the Xfer->Fetch menu to download the waypoints that you have stored in your GPS. Please make sure that your GPS is set to Garmin/Garmin communications protocol, or this will not work.

After a few seconds, you should see a list of the waypoints on your Palm. Each waypoint shows as four fields: a checkbox that you can use to flag the waypoint for selective transfer or delete; the waypoint number (meaningful only to the Palm application); the waypoint name, which you can edit in this list; and the description, which the GPS usually sets to the date and time the waypoint was dropped.

The buttons are fairly self-explanatory. "Edit" will let you edit the name, description, latitude and longitude. "New" will append a new waypoint to the current database and allow you to edit it. "Delete" will delete the currently selected waypoint, and "Sort" will sort the list alphabetically by name.

To scroll down the list of waypoints, just use the hardware buttons on the Palm. I know that I really should add a scroll-bar sometime. Maybe in another life, or in a few years. Meanwhile, just stick with the buttons (or write the code to do the scroller & send me some diffs).

Operation: waypoint edit

When editing a waypoint, the usual menu items (cut, paste, etc) work as they should. Two of the buttons ("Ok" and "Cancel") take you back to the waypoint list, eiter saving or discarding your changes. "Here" queries the GPS to find the current location, which it inserts into the latitude and longitude fields. "Delete" will delete the waypoint that you are editing and take you back to the waypoint list.

Latitude and longitude are displayed as HH:MM:SS.S. They can be input in any of the following formats: HH.HHHHH, HH:MM.MMM or HH:MM:SS.SS. There is no correction for the various grid systems. This is all just raw values, and I don't know enough about GPS technology to know how this will affect accuracy if you read values off a map and shove them into the Palm.

A number without any ‘:’ or ‘.’ characters will be assumed to be in Garmin native semicircles. For those who don't know, 23**31 semicircles = 180 degrees.

For ease of input (‘cos I find a ‘:’ tricky in grafitti), you can use a ‘,’, ‘I’, ‘ ’, ‘-’ or ‘!’ instead of a ‘:’ as a separator between degrees, minutes and seconds. If anyone wants any other separators, please let me know.

Operation: databases

Gypsy can cope with multiple waypoint databases. In the waypoint list view, the "File" menu includes options to create a new database ("New DB"), open an exiting database ("Open DB"), merge another database into the current database ("Merge DB"), and manipulate databases ("DB Utils").

These are all pretty self-explanatory. If you end up deleting the currently active database, you cannot go back to the waypoint list view without selecting or creating a new database. If you switch to another application and back to Gypsy without an active database, it will open the first database that it can find. If there is no waypoint database, it will create one called "GPS Waypoint DB" and activate that.

"DB Utils" will only let you manipulate as many databases as can fit on one screen. If you create more than 10 database, you’ll only be able to use the first 10 until you delete some. Sorry, but I didn’t think that it was worth writing the code necessary to handle a scrolling directory list.

Operation: Garmin IO

In the waypoint list view, you can use the "Xfer" menu to exchange waypoints with a Garmin GPS. I have only tested this with a Garmin II+, so it may not work with other Garmin units. When you fetch waypoints, the GPS will send all the waypoints in its memory. However, when you send waypoints, you can send either all the waypoints, or those that have been altered since downloading, or those that have been flagged.

I allow almost any user input in the edit phase, but mange it into the Garmin character set. I don’t check for duplicate names, and the GPS will happily overwrite existing waypoints.

I ave had reports of Gypsy 1.3 and later working with Garmin II, III, 12, 12XL and 45 units. I cannot confirm or test this, as I don’t have any of these (yet). In host mode, Gypsy will report itself as being a GPS II+ (pre 2.11).

Operation: Host mode

Since version 1.3, I now support a rudimentary host mode. This has only been tested with MacGPS Pro (a fine program, running on fine hardware). You can upload or download waypoints only. A request for routes, tracks, or anything else will transfer the contents of the relevant buffer. You can upload routes or a track log into the buffer while in host mode. Be aware that, unlike waypoints, this will remove the previous buffer entries.

Operation: Track/route buffer

This is a new feature with version 1.4, and was inspired by GPS2P2PC. It allows you to transfer routes and track logs between your GPS and Palm Pilot, or between your Palm Pilot and host. There is a single route buffer, so that each upload into the Palm will erase previous route information. The track buffer, however, is cumulative, so that multiple downloads from the GPS will be concatenated. There is a menu option to clear the track buffer.

You cannot access the buffer files other than from an external device. A tool like "Insider" will allow you to explore them, but they are simply the raw packets as received from the sending device.

The track buffer format is incompatible with previous versions. Please download tracks to your PC and delete the buffer before you install version 1.6. This is because of a new buffer format from Jaques-Yves Andre which reduces track storage requirements by about 80%!

Reporting bugs

As I said above, this is my first stab at a Palm application, and is probably riddled with bugs and with inconsistencies. I am quite happy to try to fix these if there is a demand and if you let me know what bothers you about Gypsy. Please let me know by email at <>. Please include the version information in the "About" screen. Without this, I may end up having to bounce between multiple versions.

This software has only been tested with a Garmin II+. It should work on a II, III, 12, 12xl, III+, etc, but this is not guaranteed. If it doesn’t I am quite happy to make it sense what sort of unit it is talking to and to talk in the correct manner for that unit, but then I need one of them to play with (hint, hint).

Further development:

There is still a lot on my TODO list, which I may or may not get around to, depending on my own needs and whether anyone asks for any of them:

Some things that I want to implement and/or change:

  1. Make the "Cancel" button work during merges and waypoint transfers.
  2. Make host mode understand several other Garmin commands.
  3. Routes. Don't quite know what to do about this yet, but it'd make sense (even if just a load/store/xfer type of operation).
  4. Copy/Paste Special to copy/paste the entire waypoint. Put all the info in a formatted fashion into the clipboard, plus store it in a local data structure for the paste.
  5. A more robust Garmin comms protocol. This will probably need to be totally rewritten as a couple of state machines, implementing progress screens from (1) and (2). Cope with timeouts, garbled packets, etc.
  6. Query the GPS and allow for different types. There is so much Garmin-specific junk scattered around (things like allowable character sets, field sizes, etc) that it'd probably be impractical to deal with other makes, but I should at least do some sanity checking about what model I'm talking to. Currently everything is specific to the GPS II+ (but should work with the II, III, III+, 12, etc)
  7. Tidy up the internal code. As this was my first stab at writing anything for the Palm platform, things are mostly done in a sub-optimal manner :-).
  8. Provide some help functions.
  9. Document everything: how to use this program; how to talk to a Garmin GPS; how to write crude Palm programs.
  10. Add some labels to forms like the "edit"/"new" form
  11. Try to make the Palm work from my Land Rover's electrical system, so that I can leave it on and not chew up AAA batteries.
  12. Add scrolling capabilities to the waypoint DB list screen, and add a track log selection screen.
  13. Add scrollers to the waypoint list screen.


Send everything to "Paul Nash" <>


Source Code

If anyone want the source code, please email me at <>. Gypsy was written on a FreeBSD box, using the 0.5 release of the GNU toolchain. However, it shouldn’t be too much work to convert it to work with CodeWarrior. Once again, I’m happy to do the conversion if someone will give me a copy of CodeWarrior for the Mac (yet another hint).

I’ve put the source on <>. However, I still request that you let me know if you have taken a copy, and let me know of any changes that you make, so that I can roll them in to newer versions.

If you really like it

Gypsy is freeware, but if you really like it and find it useful, you can send me postcards of some of the exotic places where you’ve used it. If you like it even more than that, I’m quite happy to receive other Garmin GPS units, money, shares in publicly traded companies, more money, a new Land Rover Td5, even more money …

My postal address (just in case someone does want to send me a card) is:

PO Box 12845

Changes since version 1.5

  1. Merged changes from <>) to allow a single executable to work with both PalmOS3 & PalmOS2 (Palm Pro). His changes also reduce the storage requirements for the track buffer quite dramatically.

Changes since version 1.4

  1. Cumulative track log, after quite a few requests.
  2. Tidied up edit display, and added NS and EW lists.
  3. Fixed a few bugs in the documentation.

Changes since version 1.3

  1. Source code now compiles under PalmOS 2 (thanks to <>). This leaves out progress boxes.
  2. Fixed a display bug in progress reports (total modulo 256).
  3. Added buffer capability for routes and tracks (see above).
  4. Fixed a potentially nasty bug in the Garmin protocol that deleted successive 0x10 (DLE) characters in the data stream.

Changes since version 1.0

Versions 1.1 and 1.2 were internal test versions. Since version 1.0 (called "Gulliver"), I have done the following:

  1. Fixed a potentially nasty bug in the routine that converts D:M:S into semicircles (thanks to the Palm Emulator’s gremlins for finding this)
  2. Added the first rudimentary host mode.
  3. Added the "send position" protocol support for the "here" button
  4. Tidied things up generally.