NAME
    WxM2 - Davis Weather Monitor II Station device driver

SYNOPSYS
      use Device::WxM2;

  Constructor
      my $ws = new Device::WxM2 ("/dev/ttyS0");

  Destructor
      undef $ws;

  Archive Retrieval and Logging Functions
      my @wxArchiveImage = $ws->getArcImg($archivePtr);
      my @currentWx      = $ws->getSensorImage;
      my $void           = $ws->archiveCurImage();
      my $status         = $ws->updateArchiveFromPtr($lastArchivedPtr, $file);
      my $void           = $ws->printRawLogHeader();
      my $ptr            = $ws->getNewPtr;
      my $ptr            = $ws->getLastPtr;
      my $ptr            = $ws->getOldPtr;
      my $status         = $ws->setLastArcTime($time_in_minutes_since_midnight);
      my $minutes_since_midnight = $ws->getLastArcTime;

  Individual Access Functions
      my $outside_temp                       = $ws->getOutsideTemp;
      my $dewpoint                           = $ws->getDewPoint;
      my ($windHi, $hour, $min, $mon, $day)  = $ws->getHiWind;
      my ($dewHi, $hour, $min, $mon, $day)   = $ws->getHiDewPoint;
      my ($dewLo, $hour, $min, $mon, $day)   = $ws->getLoDewPoint;
      my ($wndChLo, $hour, $min, $mon, $day) = $ws->getLoWindChill;
      my ($temp, $hour, $min, $mon, $day)    = $ws->getHiInsideTemp;
      my ($temp, $hour, $min, $mon, $day)    = $ws->getLoInsideTemp;
      my ($temp, $hour, $min, $mon, $day)    = $ws->getHiOutsideTemp;
      my ($temp, $hour, $min, $mon, $day)    = $ws->getLoOutsideTemp;
      my ($hum, $hour, $min, $mon, $day)     = $ws->getHiInsideHumidity;
      my ($hum, $hour, $min, $mon, $day)     = $ws->getLoInsideHumidity;
      my ($hum, $hour, $min, $mon, $day)     = $ws->getHiOutsideHumidity;
      my ($hum, $hour, $min, $mon, $day)     = $ws->getLoOutsideHumidity;

      my $rainfall_float           = $ws->getYearlyRain;
      my $rainfall_float           = $ws->getDailyRain;
      my $value                    = $ws->getBaroCal;
      my ($hour, $minute, $second) = $ws->getTime;
      my ($month, $day)            = $ws->getDate;

      my $status = $ws->setTime($hour_24_format, $min);
      my $status = $ws->clearHiWind;
      my $status = $ws->clearHiDewPoint;
      my $status = $ws->clearLoDewPoint;
      my $status = $ws->clearLoWindChill;
      my $status = $ws->clearHiLoOutTemp;
      my $status = $ws->clearHiLoInTemp;
      my $status = $ws->clearHiLoOutHum;
      my $status = $ws->clearHiLoInHum;
      my $status = $ws->clearDailyRain;
      my $status = $ws->clearYearlyRain;

  Configuration Functions
      my $void     = $ws->setArchiveLogFilename($filename);
      my $filename = $ws->getArchiveLogFilename();
      my $void     = $ws->setStationDescription("text");
      my $string   = $ws->getStationDescription();
      my $void     = $ws->setSerialPortReadTime($timeout_value_in_milliseconds);
      my $void     = $ws->configPort();
      my $timeout_value_in_milliseconds = $ws->getSerialPortReadTime();

DESCRIPTION
  Installation
    This driver depends on the Device::SerialPort Perl driver found on CPAN.
    You must install it somewhere on the @INC list, so that wxm2.pm can call
    it with 'use'. The standard CPAN install works fine.

    To install WxM2, use:

        perl Makefile.PL
        make
        make test
        make install

    For all the regression tests to pass, your Davis Weather Monitor II must
    be operating and connected to your computer's serial port. The test will
    query you for the name of the serial port. It will also ask if you
    weather station is operating and connected. If it is not, the regression
    test will skip 5 of the 8 tests. You can re-run the regression test at
    any time with either:

        make test

        OR

        perl -w test.pl

  Setup
    To use the WxM2 driver, simply create a class object with 'new', ie.

       $ws = new Device::WxM2("/dev/ttyS0");

    The only parameter to &new is the port to which your weather station is
    connected. The constructor initializes all the class variables and
    configures the Device::SerialPort parameters for the Davis Weather
    Station.

    Note: I found that I had to fiddle with a parameter in the SerialPort,
    called 'read_const_time', which is like a timeout value when waiting for
    read data. I found that the value needed to be increased significantly
    for the WxM2. I use 5000 (units are milliseconds) and this is the
    default setting in this package. Should you need to change it, use
    &setSerialPortReadTime(time_in_millseconds). Then call &configPort,
    which puts the new setting into effect.

  Individual Access Functions
    There are a bunch of individual functions that retrieve one weather
    value from the weather station, such as b<&getOutsideTemp>. These are
    fairly self-explanatory.

  Archive Retrieval and Logging Functions
    There are 2 primary archive retrieval functions:

      &getArcImg       - get Archive Image
      &getSensorImage  - get the "live" sensor data image

    &getArcImg retrieves the archive image at the address given to it as a
    parameter. To retrieve the most recent archived image, use this:

      my $lastPtr = $ws->getLastPtr;
      my @archiveData = $ws->getArcImg($lastPtr);

    &getArcImg takes the archive data, reformats it where necessary, stores
    the results in class variables, and returns an array of the data.

            @array= ($avgInsideTempInArchivePeriod, 
                     $averageOutsideTempInArchivePeriod, 
                     $outsideTempMaximumInPeriod, 
                     $outsideTempMinimumInPeriod, 
                     $barometricPressure,
                     $avgWindSpeedInPeriod, 
                     $avgWindDirInPeriod, 
                     $maxWindGustInPeriod, 
                     $rainInPeriod, 
                     $insideHumidity,
                     $outsideHumidity, 
                     $monthOfSample, 
                     $dayOfSample, 
                     $hourOfSample, 
                     $minuteOfSample, 
                     $outsideTempHumIndex, 
                     $outsideTempHumIndexMaximum,
                     $avgWindChill, 
                     $windChillMinimum);

    &getSensorImage enables a continuous streaming of "live" weather data
    from the Davis Wx Station. I've found this stream to be very easy to get
    out of sync, so this funcion reads a single block, stops the streaming,
    and flushes the serial receive buffer. The data returned by this
    function are the current values and not average values within a sample
    period, like &getArcImg returns. The array returned is as follows:

        @array = ($insideTemp, 
                  $outsideTemp, 
                  $windSpeed, 
                  $windDirection, 
                  $barometricPressure, 
                  $insideHumidity, 
                  $outsideHumidity, 
                  $totalRainfallToday); 

    There are 4 configuration functions for logging the archive data:

      &setArchiveLogFilename  - set the name of the log file to write
                                archive data
      &getArchiveLogFilename  - returns the name of the log file
      &setStationDescription  - sets the station description text (used by
                                &printRawLogHeader)
      &getStationDescription  - returns the station description string

    Use &setArchiveLogFilename to set the log file name. It is used by all
    logging function calls in the class.

    There are two logging functions:

      &archiveCurImage   - Writes the periodic data samples to a file
      &printRawLogHeader - Prints Header for the periodic samples log file

    &archiveCurImage writes the data samples held in the class variables to
    a filename passed in as its only parameter. For example,

      $ws->archiveCurImage();

    will write the data samples as 1 line of data in the file
    &getArchiveLogFilename.

    &printRawLogHeader writes a header for the data samples into the
    filename in &getArchiveLogFilename. The second line of the header for
    your weather station description. Set it with
    &setStationDescription("description"). Typically it contains the name
    and location of the weather station.

    The function &updateArchiveFromPtr is handy for retrieving multiple
    archived images from the WxM2's archive memory. I use it primarily after
    an extended power outage, but there are lots of other reasons to use it.
    Use it as follows:

      $ws->updateArchiveFromPtr($lastArchivePtr, $file);

    where $lastArchivePtr is the address of the last archive image that you
    read. &updateArchiveFromPtr will call &getArcImg and &archiveCurImage
    for each address between $lastArchivePtr and the currently active
    archive image. It will NOT return the image at $lastArchivePtr or the
    currently active image, only the ones in between. $file is a filename in
    which all the output will be written.

KNOWN LIMITATIONS AND BUGS
    This driver is primarily for archive retrieval, so things like alarm
    functions on the WxM2 are not implemented.

    &getSensorImage data tends to get out of sync or overflow the receive
    buffer, so it currently terminates the intended nearly infinite stream
    of data after 1 complete block.

HISTORY / CHANGES
    Version 1.00 is the first public version. I have been using it for about
    2 years, and it seems stable.

AUTHOR
    Mark Mabry: mmabry@cpan.org

  NOTE
    If you use, or even try out, this software, please drop me a short email
    at mmabry@cpan.org, to let me know that others are using it.

SEE ALSO
    Device::SerialPort

ACKNOWLEDGEMENTS
    Thanks to Davis Instruments for publishing the reference specifications
    needed to access the Weather Monitor II.

COPYRIGHT
    Copyright (C) 2003 Mark Mabry. All rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU public license.

