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 $status         = $ws->batchRetrieveArchives($x, $filename);
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 $inside_temp                        = $ws->getInsideTemp;
my $dewpoint                           = $ws->getDewPoint;
my $wind_speed			 = $ws->getWindSpeed;
my $wind_dir				 = $ws->getWindDir;
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 $bp_float		       = $ws->getBarometricPressure;
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();
my $status   = $ws->setArchivePeriod($time_in_minutes);
my $time_in_minutes  = $ws->getArchivePeriod();
my $status   = $ws->setLastArcTime($time_in_minutes);
my $time_in_minutes  = $ws->getLastArcTime();

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.

If you want to change to archive period, use &setArchivePeriod and &getArchivePeriod. Just remember that if you screw up the values, you station's archive will behave strangely until you fix it.

Use &getLastArcTime and &setLastArcTime to establish the time at which the archives are captured into the weather station's archive memory.

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 &batchRetrieveArchives 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. Us is at follows:

$ws->batchRetrieveArchives($number, $filename);

where $number is the number of archives to retrieve starting with the most recent and counting back. And $filename is the string for the file to write all the archive to.

The function &updateArchiveFromPtr is a low-level function that retrieves archives from an initial pointer value. &batchRetrieveArchives is a user-friendly front-end for this funtion. In most all cases &batchRetrieveArchives should be used. Just in case, you can use &updateArchiveFromPtr 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.03 - added getInsideTemp, getWindSpeed, getWindDir, and getBarometricPressure functions. Fixed barometer calibration bug.

Version 1.02 - added barometer calibration and bug fix in batchRetrieveArchives.

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.

ACKNOWLEDGEMENTS

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

Chris Snell added the getInsideTemp, getWindSpeed, and getWindDir functions.

Wayne Hahn fixed a bug in a pack call that popped up in Perl 5.8. He also added a sleep 1 to getSensorImage command to get it to run smoothly.

COPYRIGHT

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

To install Device::WxM2, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Device::WxM2

CPAN shell

perl -MCPAN -e shell
install Device::WxM2

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSYS

Constructor

Destructor

Archive Retrieval and Logging Functions

Individual Access Functions

Configuration Functions

DESCRIPTION

Installation

Setup

Individual Access Functions

Archive Retrieval and Logging Functions

KNOWN LIMITATIONS AND BUGS

HISTORY / CHANGES

AUTHOR

NOTE

SEE ALSO

ACKNOWLEDGEMENTS

COPYRIGHT

Module Install Instructions