NAME

Device::LaCrosse::WS23xx - read data from La Crosse weather station

SYNOPSIS

  use Device::LaCrosse::WS23xx;

  my $serial = "/dev/ttyUSB0";
  my $ws = Device::LaCrosse::WS23xx->new($serial)
      or die "Cannot communicate with $serial: $!\n";

  for my $field qw(Indoor_Temp Pressure_Rel Outdoor_Humidity) {
      printf "%-15s = %s\n", $field, $ws->get($field);
  }

DESCRIPTION

Device::LaCrosse::WS23xx provides a simple interface for reading data from La Crosse Technology WS-2300 series weather stations. It is based on the Open2300 project, but differs in several respects:

• Simplicity: the interface is simple and intuitive. For hackers, the Tied interface makes it easy to visualize the address space. And you don't have to do any of the nybble shifting or masking: it's all done for you.

• Versatility: read the values you want, in the units you want. Write a script that logs only the values you're interested in.

• Caching: to minimize communication errors, Device::LaCrosse::WS23xx reads large blocks and caches them for a few seconds.

• Debugging: the La Crosse units don't always communicate too reliably. Use the trace option to log serial I/O and track down problems.

CONSTRUCTOR

new( PATH [,OPTIONS] )

Establishes a connection to the weather station. PATH is the serial line hooked up to the weather station. Typical values are /dev/ttyS0, /dev/ttyUSB0.

Available options are:

cache_expire => SECONDS

How long to keep cached data. If your WS-23xx uses a cabled connection, you probably want to set this to 8 seconds or less. If you use a wireless connection, you might want to go as far as 128 seconds. To disable caching entirely, set to 0.

cache_readahead => NYBBLES

How much data to cache (max 30).

trace => PATH

Log all serial I/O to PATH. If PATH is just '1', a filename is autogenerated of the form .trace.YYYY-MM-DD_hhmmss.

METHODS

get( FIELD [, UNITS] )

Retrieves a reading from the weather station, optionally converting it to UNITS.

For a list of the available FIELDs and their default units, see Device::LaCrosse::WS23xx::MemoryMap

Example:

    $h = $ws->get('Humidity_Indoor');             # e.g. '37'
    $p = $ws->get('Absolute_Pressure', 'inHg');   # e.g. '23.20'

Only a few reasonable UNIT conversions are available:

     From       To
     ----       --
     C          F
     hPa        inHh, mmHg
     m/s        kph, mph, kt
     mm         in

It's trivial to add your own: see the module source. (If you do add conversions you think might be useful to others, please send them to the module author).

Tied Array Interface

The WS-2300 memory map can be visualized as a simple sequence of addresses, each of which contains one data nybble. In other words, a perl array:

    my $serial = '/dev/ttyUSB0';
    tie my @ws, 'Device::LaCrosse::WS23xx', $serial
      or die "Cannot tie to $serial: $!\n";

Or, if you already have a $ws object, it's even simpler:

    tie my @ws, $ws;

Then access any WS-2300 memory cells as if the unit were directly mapped to the array:

    print "backlight = $ws[0x16]\n";

    my @temp_in = @ws[0x346..0x349];
    print "@temp_in\n";         # e.g. '0 8 9 4'

Note that each value is a nybble: a value between 0 and 0xF.

This is not really useful for actual weather station monitoring. It is intended for hackers who want direct access to the device, either for learning purposes or because Device::LaCrosse::WS23xx is missing some important mappings.

The Tied interface is read-only. If you have a need for read/write, contact the author.

AUTHOR

Eduardo Santiago <esm@cpan.org>

ACKNOWLEDGMENTS

I am indebted to Kenneth Lavrsen, author of Open2300, for his excellent code and documentation. Thanks also to Claude Ocquidant for very helpful notes on the WS-23xx protocol.

BUGS

No support for writing values to the device. To reset the rain counters or perform other write operations, use the Open2300 tools.

Please report any bugs or feature requests to bug-device-lacrosse-ws23xx at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Device-LaCrosse-WS23xx. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SEE ALSO

Open2300: http://www.lavrsen.dk/twiki/bin/view/Open2300/WebHome

Claude Ocquidant: http://perso.orange.fr/claude.ocquidant/autrespages/leprotocol/protocol-eng.htm

cpanm Device::LaCrosse::WS23xx

perl -MCPAN -e shell
install Device::LaCrosse::WS23xx