/ 
GPS-Lowrance-LSI-0.23
/ GPS::Lowrance::LSI

NAME

GPS::Lowrance::LSI - Lowrance Serial Interface Protocol module in Perl

REQUIREMENTS

The following modules are required to use this module:

Carp::Assert
Parse::Binary::FixedFormat
Win32::SerialPort or Device::SerialPort

This module should work with Perl 5.6.x. It has been tested on Perl 5.8.2.

Installation

Installation is standard:

perl Makefile.PL
make
make test
make install

For Windows playforms, you may need to use nmake instead.

SYNOPSIS

use Win32::SerialPort;                # or Device::SerialPort (?)
use GPS::Lowrance::LSI 'lsi_query';

my $port = new Win32::SerialPort( 'com1' );

my $data = lsi_query( $port, 0x30e, "", 0 );

DESCRIPTION

This module provides very low-level support for the LSI (Lowrance Serial Interface) 100 protocol used to communicate with Lowrance and Eagle GPS devices.

(Higher-level functions and wrappers for specific commands will be provided in other modules. This module is intentionally kept simple.)

Functions

lsi_query
  $data_out = lsi_query( $port, $cmd, $data_in, $id, $debug,
			 $timeout, $retry );

This method submits an LSI query sentence (with the command and input data) to a GPS connected to the device specified by serial port at $port. (See the LSI specification on the Lowrance or Eagle web sites for the specific command codes.)

It then waits $timeout seconds (defaults to 5) for a response. If there is no response, it returns undef.

Otherwise, it verifies that the response is well-formed and returns the data. If $retry is greater than zero, then it will retry the query $retry times if there is a bad checksum or if there is a timeout. (If the checksum keeps failing or responses time out, it will return undef.)

A value of -1 for $retry causes bad checksums to be ignored.

The $id value is "reserved" and should be set to 0.

The first 8-bytes of the returned data is the response header.

The format of the rest of the data depends on the command.

If $debug is true, then debugging information is shown.

verify_checksum
if (verify_checksum( $data )) { ... }

Used to verify the checksum in the data. The last byte of data returned is the checksum of the data.

Note that "lsi_query" returns the initial 8-byte acknowledgement header along with any data. So to verify data returned by that function:

if (verify_checksum( substr( $data, 8 ) )) { ... }

The query function already verifies data returned by the query. So there is usually no need to re-check the data.

lsi_checksum
$chksum = lsi_checksum( $data );

Used to calculate 8-bit checksums in data. This is generally an internal routine, but since "lsi_query" makes raw data available, this is useful.

EXAMPLES

An example of using this module to query product information is below:

use GPS::Lowrance::LSI;
use Parse::Binary::FixedFormat;

$InfoRec = new Parse::Binary::FixedFormat [
 qw( Reserved:C ProductID:v ProtocolVersion:v
     ScreenType:v ScreenWidth:v ScreenHeight:v
     NumOfWaypoints:v NumOfIcons:v NumOfRoutes:v
     NumOfWaypointsPerRoute:v
     NumOfPlotTrails:C NumOfIconSym:C ScreenRotateAngle:C
     RunTime:V Checksum:C )];

# We assume that $Port is already initialized to a serial port using
# Win32::SerialPort or Device::SerialPort

$Buff = lsi_query($Port, 0x30e);

$Info = $InfoRec->unformat( substr($Buff, 8) );

A working implementation of this example can be found in the file eg/getinfo.pl included with this distrubtion.

TODO

A separate GPS::Lowrance module will be written that will function as a wrapper for the various commands.

Add more test cases, where appropriate.

CAVEATS

This is an early release of the module, so likely there are bugs.

This module has not (yet) been tested with Device::SerialPort. Feedback on this would be appreciated.

Win32::SerialPort unfortunately has not been updated since 1999.

SEE ALSO

Win32::SerialPort and Device::SerialPort explain how to create serial port connection objects for use with this module.

Parse::Binary::FixedFormat is useful for flexible parsing binary structures used by this protocol.

The Lowrance Serial Interface (LSI) Protocol is described in a document available on the Lowrance or Eagle web sites, such as at http://www.lowrance.com/Software/CyberCom_LSI100/cybercom_lsi100.asp or http://www.eaglegps.com/Downloads/Software/CyberCom/default.htm. (Note that the specific URLs are subject to change.)

Other Implementations

There is a Python module by Gene Cash for handling the LSI 100 protocol at http://home.cfl.rr.com/genecash/eagle.html.

Other GPS Vendors

There are other Perl modules to communicate with different GPS brands:

GPS::Garmin
GPS::Magellan

AUTHOR

Robert Rothenberg <rrwo at cpan.org>

Suggestions and Bug Reporting

Feedback is always welcome. Please report any bugs using the CPAN Request Tracker at http://rt.cpan.org.

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Robert Rothenberg <rrwo at cpan.org>.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.