                                   NMEA48 v1.1
                                   -----------


Size:  2635 bytes
Checksum:  # 6863h

NMEA48 is a library of programs for handling NMEA-0183 output from a variety
of devices (GPSs, depth sounders, Lorans, etc.) on the HP48.  Some of the
commands provide a versatile facility for getting NMEA data packets,
individual sentences, and specific parts of sentences, and are intended for
use in applications such as track loggers, flight computers and such.
Additional commands are provided to return position, altitude, time, and speed.


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 NMEA48 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 NMEA48 should run on a 48S/SX, but I doubt it will _work_ due to the
  slower processor.  Some things in the program are timing dependent.
o For a description of some NMEA sentences, see the NMEA faq and related
  documents at ftp://sundae.triumf.ca/pub/peter/index.html


Setup
-----

o Download nmea4811.lib and install it in any port (covered ports are fine).
o Connect the NMEA device and the 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 device for NMEA protocol, 4800 baud.
o You need to have the Universal Font Library installed for the Ver command to
  work.


Commands
--------

Pos - (  --> %latitude %longitude )
  returns current position.  Latitude and longitude are returned in dd.mmss
  format.
  Requires sentence: RMC

Time - (  --> %date %time )
  returns current time.  By default -- UTC, but if you put a variable 'UTCO'
  containing the UTC offset in hours (negative or positive real number) in
  a place where nmea48 can find it, the time/date will be adjusted accordingly.
  If flag -42 is set, the date format will be dd.mmyyyy, otherwise mm.ddyyyy.
  Requires sentence: RMC

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

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

Speed - (  --> %speed_knot )
  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 version information.  If a device is connected to the HP, Ver will
  report which sentences it's receiving.  Only one packet is examined
  (otherwise you might have to wait an unreasonable amount of time), so RTE
  is missed sometimes.

NDATA -
  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 - ( % --> $ )
  returns a string containing % consecutive NMEA packets.


Error messages
--------------

"No fix" - Pos 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.

"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 device isn't connected or isn't set to use the NMEA
  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 Garmin GPS 45) for
  figuring out all this!

  It could also be that the program just isn't waiting long enough.  Given
  the variation in NMEA devices and HP48 processor speeds, this is a
  possibility.


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

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

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