                                    GxPS v2.0
                                    ---------


Size:  7108.5 bytes
Checksum:  # 118Ch

GxPS is a library of programs to upload/download waypoints, routes, and tracks
from a Garmin GPS.  It works with the Garmin and NMEA-0183 protocols, and can
query the GPS for position, altitude, speed, time/date, and version
information.  GxPS also provides commands that simplify lower level work with
both protocols and are intended for use in other GPS applications.


Terms of Use & Disclaimer
-------------------------

Copyright (C) 1998  Jason Grant

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.  See the included file COPYING for more details.

I've tried to test GxPS as thoroughly as possible, but I'd recommend backing
up your calculator just in case.  I've tested it with a 48 GX version R and a
GPS III v2.05.


Important
---------

o GxPS works on the G/GX only.


Setup
-----

o Download GxPS20.lib and install it in any port (covered ports are fine).
o Connect the GPS and HP with a special cable or by joining the
  standard data cables for both units with a null modem adapter.  For more
  information, see my cables page: http://www.chat.ru/~dadima/cables.html
o Set the GPS for GARMIN protocol, host mode, or NMEA protocol, 4800 baud.
o You need to have the Universal Font Library installed for the Ver command to
  work.


Commands
--------

General notes:
  o Unless marked as requiring a certain protocol, commands will detect the
    current protocol and do the right thing.  Any differences arising from
    using one protocol or the other are described.
  o If your GPS is in Garmin mode, all positions are given in reference to the
    WGS 84 datum.  If it's in NMEA mode, the currently selected datum on the
    GPS will be used.
  o To monitor the progress of any transmission using the Garmin protocol, go
    to the I/O setup page of your GPS.

Setup - (  -->  )
  configures GxPS (position format, track log format, and UTC offset).

WPv - (  --> { waypoints } )                     Requires protocol: Garmin
  downloads waypoints from the GPS.

  If your GPS is one of the following: GPS 38, 40, 45(XL), 48, 55, 65, 75, 95,
  120(XL), 125, 126,128, II(+), 12(XL) (version 3.01 and later), or III, the
  waypoints will be converted to a viewable format.  If your GPS isn't listed
  here, the waypoint records will be left in their original, unformatted guise
  (a bunch of strange looking strings).  You can't view them, but you can at
  least upload them back to the GPS.  Let me know if you would like to see
  support added for a certain model; it's not hard.

  Viewable format:
    {
      "/* waypoint type */"   (leave this alone)
      {
        "wpname"
        % latitude
        % longitude
        "comment"
        % icon_number	   ( not all waypoint formats 
        % display_status          include these fields )
      }
      { ... } ...
      "WP"     (leave this alone, too)
      % position_format   (0 = dd.dddd, 1 = dd.mmss)
    }

  See the Official Garmin Protocol Specification for more on icon numbers.
  For % display_status, 0 = display symbol by itself, 1 = display symbol with
  waypoint name, 2 = display symbol with comment.

RTEv - (  --> { routes } )                       Requires protocol: Garmin
  downloads routes from the GPS.  Format:
    {
      "/* waypoint type */"			(leave this alone)
      {
        % route_number
        "route name"
      }
      { waypoint }  { waypoint } ...
      ...
      "RTE"     (leave this alone, too)
      % position_format   (0 = dd.dddd, 1 = dd.mmss)
    }

  Routes are supported for all models except the GPS 55 and 55 AVL.

TRXv - ( --> { track_log } or "compact_track_data" )  Requires protocol: Garmin

  Viewable format:
    {
      {
        % latitude
        % longitude
        % date
        % time
        ( a 1 here indicates the beginning of a track segment )
      }
      { ... }  ...
      "TRX"    (leave this alone)
      % position_format   (0 = dd.dddd, 1 = dd.mmss)
    }

  GxPS can download tracks in two different formats:
    compact - faster to transfer and much smaller
    viewable - these can be examined, modified, etc.
  See the Setup command.

  The Garmin protocol is rather limited for models that support saved track
  logs.  When you download track data, all the saved logs are lumped together
  with the active log.  The only indication you get of where one track ends
  and another begins is that "1" some records have.  No track names are sent.
  The saved track logs all have a bogus time stamp (2058 a.d.).  Any track
  data previously uploaded to the GPS will have a time stamp of Dec. 31, 1989.

^ (up arrow) - ( { waypoints }  or  { routes }  or  { track log }  -->  )
  uploads waypoint, route, and track data to GPS.

  Use ONLY numerals and uppercase letters in names and comments.  Sticking
  other characters in there may cause unwanted results on the GPS.

  When editing downloaded data or adding new records, be sure to follow the
  formats given above.  GxPS does some limited checking to make sure there
  are the correct number of objects in a record, but it doesn't type check
  each one, so you will get unpredictable results if you, say, have a number
  where a string is expected and so on.

  If you upload a waypoint with an empty comment string, the GPS (the III, at
  least) will give it the default "CRTD time/date" comment.

  When uploading a track log,  saved tracks (on units that support them) are
  left intact (i.e. not overwritten).  All the uploaded points are appended
  to the active log.
  
  *NOTE*  Uploading a track seems to turn off track logging on most Garmins.
    Any tracks you upload will not be displayed until you turn track logging
    back on.

Off - (  -->  )                                  Requires protocol: Garmin
  turns GPS off.

Pos - (  --> %latitude %longitude )
  returns latitude and longitude to the stack.
  Garmin: the position is returned with a bit more precision.
  NMEA: a check is made before returning anything to be sure the GPS has a fix.
    Requires sentence: RMC

Time - (  --> %date %time )
  returns date and time to the stack.  If flag -42 is set, the date format
  will be dd.mmyyyy, otherwise mm.ddyyyy.
  NMEA: Requires sentence: RMC

SyncTime - (  -->  )
  syncs the HP's clock with the GPS's.
  NMEA: Requires sentence: RMC

Alti - (  --> %altitude_m )                      Requires protocol: NMEA
  returns altitude tagged with the appropriate unit.
  Requires sentence: GGA

Speed - (  --> %speed_knot )                     Requires protocol: NMEA
  returns current speed in knots.  The number is automatically tagged as a unit
  so you can easily convert it to kph or mph.  Let me know if you find this
  especially useful or annoying.
  Requires sentence: RMC

Ver - ( --> )
  displays an about screen.  If the GPS is connected, information about it
  will be displayed, depending on what mode it's in.
  Garmin: GPS version info will be displayed.  Only the first line is intended
    by Garmin for users to see, but some GPS models report other information as
    well (though it may or may not be understandable), so the program goes
    ahead and displays it all.
  NMEA: A list of senteces being sent by the GPS will be displayed.  Only one
    packet is examined (otherwise you might have to wait an unreasonable amount
    of time), so RTE is missed sometimes.

NDATA -                                            Requires protocol: NMEA
  This is the primary command for handling NMEA input, so I've tried to make
  it as versatile as possible.  The syntax is rather involved, so I'll
  provide a few examples:

  5:           "GSV"
  4:             { }
  3:           "GSA"
  2:     { 2 16 17 }
  1:               2

  In level one is the number of requests we are making, in this case 2.  Each
  request consists of a sentence name (string) and a list describing what
  information we want.  If the sentence is a standard NMEA sentence, its name
  will be three characters long (omit the leading `$' and two character
  talker ID).  If the sentence is a proprietary one, its name will be four
  characters long (omit the leading `$' and `P', ex: "GRMZ").
  Each NMEA sentence consists of a number of comma-separated fields.  The
  list following the sentence name specifies which particular fields to
  return.  In the example, we ask for fields 2, 16, and 17 (type of fix,
  horizontal DOP, and vertical DOP respectively) from the GSA
  sentence.  Numbering begins with the sentence name (field 0) and proceeds
  to the right.  If you don't specify any fields (like we did for GSV), then
  the whole sentence is returned (minus any checksum), along with a count.
  The count is useful since some sentences consists of several parts.  Look
  at what NDATA returns:

  7:  "$GPGSV,3,1,12,04,...                        part 1
  6:  "$GPGSV,3,2,12,09,...         GSV sentences  part 2
  5:  "$GPGSV,3,3,12,18,...                        part 3
  4:                      3         returned 3 parts
  3:                  "3.0"         vertical DOP (field 17)
  2:                  "2.0"         horizontal DOP (field 16)
  1:                    "3"         3d fix (field 2)

  Notice the order in which things are returned and also that everything is
  returned as a string.
  You can specify not only which fields you want, but also which parts you
  want the fields to come from if the sentence is a multi-part one.  See the
  "18" in the third GSV sentence in the example?  You would specify it with
  4.3 (field 4, part 3).  2 would be the same thing as 2.0 or 2.1, namely the
  second field from the first part, which would return "1" in this case.
  If you specify a part that is out of range (too large), the last valid part
  will be returned instead.  For example, if you wanted field two from the
  last part of GSV (the number of parts in GSV varies between 1 and 3), you
  could get it with 2.4.  However, since the number of fields in a part
  doesn't vary, requesting an out of range field will result in a "No such
  field" error.
  If you request multiple sentences, as we did in the last example, they will
  all come from the same data packet.
  However, you can request only one sentence, like this:

  3:        "GRMM"          proprietary Garmin sentence
  2:         { 1 }          field 1 is the currently active datum
  1:             1

  Making one request is generally a bit faster and it is the only reliable
  way of getting a sentence such as "RTE", which isn't always sent in every
  packet.  But be careful not to ask for a non-existent sentence since the
  program will look for quite some time before deciding the sentence just
  isn't there.  It will give up much faster if you've made multiple requests,
  since only one data packet is examined.

NPKTS - ( % --> $ )                                Requires protocol: NMEA
  returns a string containing % consecutive NMEA packets.

The following four commands are provided for anyone who wants lower level
access to the Garmin protocol.  For an idea of how to use them, get a
description of the Garmin protocol from
http://vancouver-webpages.com/peter/#garmin

GGET - ( % --> $ )                                 Requires protocol: Garmin
  returns one record in the receive buffer (minus leading DLE and trailing
  checksum and DLE ETX).  % = record type expected, example: 255 will be
  record type 0xFF.  GGET will ACK a properly received record.  If a timeout
  occurs or the record has a bad checksum, GGET will send a NAK and try again
  a couple times before giving up.

GSEND - ( $ -->  )                                 Requires protocol: Garmin
  sends a record to the GPS.  Adds checksum and frame (i.e. DLE ... DLE ETX).
  GSEND will retransmit a record if it doesn't get a proper ACK from the GPS.

GRECV - (  --> $ or % )                            Requires protocol: Garmin
  like GGET, but doesn't send an ACK and won't retry.  GRECV returns a 0 for
  timeout, or 1 for bad checksum.  If there are no errors, the record is
  returned.

GXMIT - ( $ -->  )                                 Requires protocol: Garmin
  like GSEND but doesn't look for an ACK and won't retry.

REMV - (  -->  )
  removes GxPS configuration info from the hidden directory.


Troubles
--------

Error messages:

"Data/GPS mismatch" - the GPS you are uploading to uses a different waypoint
  format than the GPS you downloaded from.  I may add conversion routines in
  the future if anyone thinks this would be useful.

"Invalid data" - the data you're trying to upload are not correctly formed
  in some way.

"No fix" - Pos (in NMEA mode) and Speed check to make sure you have a valid
  position fix.  You'll get this error if you don't.

"No such field" - One of the fields you requested with NDATA was out of range.

"Nothing to download" - There are no records of the requested type (i.e.
  waypoints, routes, or tracks) on the GPS to download.

"Receive buffer overrun" - I've tried to make the receive buffer big enough
  to handle any normal situation, but not any bigger.  If you get this
  message, please let me know.

"Receive error" - indicates a framing error or an input overrun.  You
  shouldn't get this error, so tell me if you do.

"Sentence not found" - running NDATA with multiple requests will return this
  error fairly quickly if one of the sentences isn't found.  However, it may
  miss something like the RTE sentence, which isn't necessarily sent in every
  packet.  Giving only one request to NDATA will result in a more exhaustive
  search, but one which may take some time to terminate.

"Timeout" - probably the GPS isn't connected or isn't set to use the necessary
  protocol.  If you're certain that all the software settings are right and
  that the units are correctly connected, but you still get only timeouts, you
  may have a signal leveling problem.  Unfortunately, this is a hardware
  problem, but there are a couple of fixes:

    o Connect a small 1.5 V battery in series with the transmit data line
      coming from the HP (positive polarity in the direction of the GPS).
      For a compact solution, you could probably even fit the battery inside
      the housing for the serial connector.

    o The battery may be replaced by a 1 kOhm resistor in series with a little
      diode (1N4148 or so) connected from the Garmin's data input line with
      anode to ground.

  Thanks to Detlef Rohde (who had this problem with a GPS 45) for figuring out
  all this!


Contacting the author
---------------------

The latest version of GxPS (plus a few links and other information) can be
found at: http://www.chat.ru/~dadima/hp48.html

I would really appreciate any comments, corrections, or other observations,
especially about how the program works with Garmin units other than the III.
Please send them to me, Jason Grant <dadima@chat.ru>.
