SourceForge Logo
GPS Library Documentation
Note that these Python modules implement the protocol described by Eagle/Lowrance on their software documentation page and updated by me based on my experience debugging communications sessions with my Eagle Explorer. I have no affiliation with Eagle Electronics except as a very satisfied customer. I bought my Explorer for $150 at a local Walmart and found it quite a sophisticated and useful piece of equipment. There may be inaccuracies in this document or the accompanying software source code, and if you use it, you're on you own. I assume no risk if you use it and something bad happens to you, like driving off a mountain. If it breaks, you get to keep both pieces.

Also, if you use a GPS in a moving vehicle, PLEASE be very careful. When I did my plot trails on the way to work, I just put the GPS in a mount on the handlebar and didn't attempt to mess with it until I stopped at work.
GPS_Serial module
This module implements low-level serial communications, and is meant to be as operating system and protocol independent as possible. When the major class "GPS" is instantiated, it initializes the serial port, then starts a separate thread that services the port by determining the protocol of the incoming information, and placing the messages in a queue for that protocol. It expects the name of the serial port (e.g. 'ttyS0' for Linux, or 'COM1' for Windows) and the data rate. The data rate should match the GPS unit's current setting for successful communications. This separate thread is shut down when the instance is destroyed, or close() is called.

For example:
port_obj=GPS_Serial.GPS('ttyS3', 19200)

It understands enough of the LSI-100 protocol to be able to decipher command headers and put responses into a queue as 3-tuples, consisting of command byte, data length count, and data string. If there is an error, then the length argument is negative and the data string is a description of the error.

It also understands enough of the NMEA protocol to put NMEA messages in another queue. If the checksum doesn't match, the sentence is dropped and an error counter is incremented.

In the future I hope to extend its capability by adding code to recognize the Garmin protocol.

It is the responsibility of other higher-level code to send properly formatted commands and deal with time-outs, loss of link, error conditions, etc.

Method Description Return Value
__init__(port, baud, parity='None', stopbits=1, databits=8) Create object, initialize port to the requested state, and start service thread. GPS_Serial.GPS object
baud(baud) Change port baud rate to new value. None
close() Release any OS resources for port, and halt service thread. None
write(str, cnt=None) Write data out the port. None
read(size=1) Block until the specified number of bytes is received from port. String of bytes read
readline() read() until a newline is received. String of bytes read

NMEA module
This module understands the protocol developed by the National Marine Electronics Association as a standard for communicating between various pieces of boating navigation hardware.

It is a receive-only protocol, where information flows only from the GPS unit to the PC.

sentence descriptions from Peter Bennett's NMEAFAQ.TXT v6.1 at ftp://sundae.triumf.ca/pub/peter/index.html
Eagle module
This module implements the proprietary Eagle/Lowrance protocol. Their LSI-100 document is rather rough, and I'll expand on it a little in the course of describing the library.

The GPS keeps position information internally as Mercator Meters, also known as Universal Transverse Mercator Meters, or more simply UTM Meters. These are coordinates in the UTM system. You may find more information at the Coordinate System Overview and a good reading list is at the GPS Resource Library. The routines merc2deg() and deg2merc() convert between the formats. They expect a latitude and longitude pair in one measurement and return the corresponding coordinate pair in the other measurement.

Note that in the following table, if a return value is specified with named elements, then those are the names of the attributes of a return-value object.

Also note that "send" or "write" denotes sending information from the PC to the GPS receiver, and "get" or "read" denotes sending information from the GPS receiver to the PC.

Description Object Method Arguments Return Value Chk
Instantiate object and connect to serial port. __init__(gps) gps: GPS_Serial.GPS object Eagle.Eagle object Yes
Disconnect from GPS receiver and release resources close() None None Yes
Send LSI 100 command properly formatted with checksums, then wait for response with a 5-second time-out
Increments error counters as necessary.
SendCmd(cmd, info)
cmd: LSI-100 command byte
info: list of (type, data) pairs, where type is:
b: byte data
w: word (2 bytes)
l: long (4 bytes)
GPS receiver's response to command as a string of bytes Yes
Return generic ASCII description of unit software Undoc01() None String Yes
Read from a memory location ReadMemLoc(addr, cnt, cart)
addr: starting address of memory read
cnt: number of bytes to be read (maximum 256)
cart: cartridge slot
String of bytes read from memory No
Write to a memory location WriteMemLoc(addr, cnt, cart)
addr: starting address of memory read
cnt: number of bytes to be read (maximum 256)
cart: cartridge slot
Number of bytes written No
Determine successful communications with GPS receiver Login() None None No
Change NMEA baud rate ChangeBaudRate(rate)
rate: integer in the range 1-5 where:
0: 1200 baud
1: 2400 baud
2: 4800 baud
3: 9600 baud
4: 19200 baud
5: 38400 baud
Unknown No
Request screen pointer to download the current screen, and freeze screen RqstScrPtr() None
width: screen width in pixels
height: screen height in pixels
black_addr: memory address of black pixel plane
black_len: number of bytes in black pixel plane
grey_addr: memory address of grey pixel plane
grey_len: number of bytes in grey pixel plane
Yes
Unfreeze the screen after RqstScrPtr() call Unfreeze() None None Yes
Get a waypoint GetWaypoint(wyptno) wyptno: index of waypoint to retrieve
num: waypoint index
stat:
0: invalid
1: valid
symbol: icon symbol index
lat: waypoint latitude (Mercator Meters)
lon: waypoint longitude (Mercator Meters)
name: waypoint label (13 character maximum)
date: number of seconds since 00:00 01-JAN-1992
Yes
Send a waypoint SendWaypoint(wyptno, stat, symbol=None, lat=None, lon=None, name=None, date=None)
wyptno: waypoint index
stat:
0: invalid
1: valid
symbol: icon symbol index
lat: waypoint latitude (Mercator Meters)
lon: waypoint longitude (Mercator Meters)
name: waypoint label (13 character maximum)
date: number of seconds since 00:00 01-JAN-1992
Unknown No
Get a route GetRoute(routeno) routeno: route index
name: route label (13 character maximum)
wypts: list of waypoint indexes in route
Yes
Send a route SendRoute(routeno) routeno: route index Unknown No
Get plot trail pointer GetTrailPtr(trailno) trailno: trail index Unknown No
Get number of icons GetNoIcons() Unknown Unknown No
Get icon GetIcon(iconno) iconno: icon index Unknown No
Set number of icons SetNumIcons() iconcnt Unknown No
Send icon SendIcon() Unknown Unknown No
Get number of symbols GetNoSymbols() Unknown Unknown No
Get icon symbol GetIconSym() Unknown Unknown No
Get product information GetProductInfo() None
prod_id:
1: GlobalMap
2: AirMap
3: AccuMap
4: GlobalNav 310
5: Eagle View
6: Eagle Explorer
7: GlobalNav 200
8: Expedition II
9: GlobalNav 212
10: GlobalMap 12
12: AccuMap 12
proto_ver:
0: version 1.0
1: version 2.0
scr_type:
0: black plane only
1: black and grey planes
2: packed pixels
scr_x: width of screen in pixels
scr_y: height of screen in pixels
wypt_cnt: maximum number of waypoints
icon_cnt: maximum number of icons
route_cnt: maximum number of routes
wypts_route: maximum number of waypoints per route
trail_cnt: maximum number of plot trails
sym_cnt: maximum number of icon symbols
scr_angle:
0:
1: 90°
2: 180°
3: 270°
runtime: length of time unit has been running, in seconds
Yes
Get plot trail origin (protocol version 2.0 only) GetTrailOrigin() Unknown Unknown Yes
Get plot trail deltas (protocol version 2.0 only) GetTrailDeltas() Unknown Unknown Yes
Get entire plot trail GetTrail() Unknown Unknown Yes
Get all valid routes GetRoutes() Unknown Unknown Yes
Get all valid waypoints GetWayPoints() Unknown Unknown Yes
Get screen display bitmap GetScreen() Unknown Unknown Yes
Get icon symbol bitmap GetSymbol() Unknown Unknown No
Get large block of memory by performing multiple ReadMemLoc() calls GetBlock() Unknown Unknown No
Write large block of memory by performing multiple WriteMemLoc() calls WriteBlock() Unknown Unknown No

Undoc01 (LSI-100 command code 0x0004)
This command is not mentioned in the LSI-100 document. It was discovered during early testing using a serial protocol analyzer. It returns a string like "Handheld GPS 1.4"

Screen Bitmap Format
The most significant bit of the first byte of the bitmap contains the on/off state of the pixel at the top left corner of the LCD. The next most significant bit contains the next pixel to the right, and so on, until the first line is fully decoded. The second line is decoded in a similar fashion until the entire screen is finished.

Note that the LCD may be rotated, and GetProductInfo() will tell you how much, as well as indicate the presence of black and/or grey planes. If the unit does not have a black or a grey plane, then the corresponding "black_len" or "grey_len" will be zero.

Plot Trails
A plot trail provides a "bread crumb" style history of the GPS receiver's position. You can write to and read from a unit that supports plot trails by using the Set Plot Trail Origin, Set Plot Trail Deltas, Get Plot Trail Origin, and the Get Plot Trail Deltas commands. The Get Product Information command response will indicate if the version 2.0 plot trail upload/download features are supported by a particular unit. If it is not supported, you have to use the Get Plot Trail Pointer command in conjunction with the Read Memory Location commands to interrogate and decode the raw data structures stored in the unit's memory, and in that case, I believe sending a plot trail to the unit is not supported.

When getting a plot trail via the version 2.0 protocol, you use the Get Plot Trail Origin command which indicates the start position and the total number of points in the plot trail, then use the Get Plot Trail Deltas command repeatedly to receive "chunks" of points until the entire plot trail is processed. It is recommended to request only a maximum of 40 points per message to avoid overflowing internal buffers in the unit. When the number of deltas in the response is less than the number requested, then you've received the last block of the plot trail.
I'm not sure why you would want to send a plot trail to the unit, but the capability seems to exist. I don't plan to implement this functionality.

Higher-Level Commands
These are commands to perform common operations not directly supported by the LSI-100 protocol. They are implemented by calling lower-level commands, and are provided for programmer convenience.

GetTrail
Retrieves an entire plot trail and returns it as a list of latitude, longitude pairs.

GetRoutes
Retrieve all the valid routes from the unit.

GetWaypoints
Retrieve all the valid waypoints from the unit.

GetScreen
Download the current display, and return a tuple of (width, height, black plane bitmap, grey plane bitmap).

GetSymbol
Retrieves an entire plot trail and returns it as a list of latitude, longitude pairs.
Page last updated
Sat 21-Apr-2001