Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

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

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


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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy