Gypsy Documentation Introduction 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 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. Ths 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 GS 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. 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 n/s/e/w. They can be input in any of the following formats: HH.HHHHH, HH:MM.MMM or HH:MM:SS.SS. With no hints, they are taken as being North and West. They can be preceded by a Ô-Ô to indicate South and East, or can be followed by N/S/W/E to spell this out in a more normal manner. **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 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. This is quite crude, and a transfer from GPS or host will wipe out all previous information. There are separate buffers for route and track information, so you can transfer both at the same time. 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. 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 (thingslike 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. PLEASE SEND ANY CHANGES, BUG FIXES, REQUESTS OR BUGS TO ME. I WILL DO WHAT I CAN TO INCORPORATE THEM IN LATER RELEASES (BUT NO PROMISES) 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 Onderstepoort 0110 SOUTH AFRICA 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: 5) 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) 6) Added the first rudimentary host mode. 7) Added the Òsend positionÓ protocol support for the ÒhereÓ button 8) Tidied things up generally.