GPS::Lowrance::LSI - Lowrance Serial Interface Protocol module in Perl
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 is standard:
perl Makefile.PL make make test make install
For Windows playforms, you may need to use nmake instead.
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 );
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.)
$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.
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.
$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.
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.
A separate GPS::Lowrance module will be written that will function
as a wrapper for the various commands.
Add more test cases, where appropriate.
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.
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.)
There is a Python module by Gene Cash for handling the LSI 100 protocol at http://home.cfl.rr.com/genecash/eagle.html.
There are other Perl modules to communicate with different GPS brands:
GPS::Garmin GPS::Magellan
Robert Rothenberg <rrwo at cpan.org>
Feedback is always welcome. Please report any bugs using the CPAN Request Tracker at http://rt.cpan.org.
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.