Chip 2000 February/Chip_2000-02_cd.bin/sharewar/gypsyp/gypsy.txt

Text File | 1999-05-13 | 13KB | 279 lines

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
<http://users.iafrica.com/p/pn/pnash>.

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 <[e-mail]>.  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" <[e-mail]>


Source Code

If anyone want the source code, please email me at <[e-mail]>.
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 <http://users.iafrica.com/p/pn/pnash>.  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
<[e-mail]>).  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.