NAME
Device::VantagePro - Perl module to request data in real-time or archive and configure a Davis Vantage Pro Weather Station that is equiped with a WeatherLink datalogger/serial port.
SYNOPSIS
use Device::VantagePro;
use Data::Dumper;
my %arg_hsh;
$arg_hsh{baudrate} = 19200;
$arg_hsh{port} = "/dev/ttyr08";
my $vp_obj = new Device::VantagePro(\%arg_hsh);
$vp_obj->wake_up();
# Start loop for 2 times and read loop data
$vp_obj->start_loop(2);
for my $i (1..2)
{
my $hsh_ref = $vp_obj->read_loop();
print Dumper $hsh_ref; # Print out data hash
sleep 2;
}Or perhaps better yet
for my $i (1..2)
{
my $hsh_ref = $vp_obj->get_one_loop();
print Dumper $hsh_ref; # Print out data hash
sleep 2; # Sleep arbitary number of seconds no less than 1 sec.
}To retrieve archive data first requires a date/time stamp and then a call to do_dmpaft
# Create date/time stamp for April 17 2010 at 0805
my ($dstamp,$tstamp) = $vp_obj->make_date_time_stamp(2010,4,17,8,5);
my $data_ref = $vp_obj->do_dmpaft($dstamp,$tstamp);
foreach my $ref ( @{$data_ref} )
{
# Do something with the data hash reference
print Dumper $ref; # data hash of archive record.
}DESCRIPTION
A module to provide direct access to many of the features of the Davis VantagePro Weather family of weather stations.
This module was developed and tested on a Linux operating system and relies upon the Unix specific Device::SerialPort module. A port to Windows could be accomplished using the Win32::SerialPort module which uses the same calls. See code for more details.
Some things to note: The Archive data packet and the Loop data packet provide different data values. For example, the Loop data packet has a value for the 10-Minute ave wind speed while the Archive data packet has only the wind speed average for the archive period. The Archive data packet only gives the instantaneous maximum wind speed over the archive period and not a true wind gust measurement as defined by NOAA as a maximum sustained wind speed over a 3 second period, therefore wind gusts tend to be high.
METHODS
new
Object Constructor which expects an argument with a hash or reference to a hash providing the communication parameters.
$vp_obj = Device::VantagePro->new(%arg_hsh); Available arguements: baudrate, parity, databits, stopbits, port
Defaults for these argument parameters are as follows:
$arg_hsh{'port'} = "/dev/ttyS0";
$arg_hsh{baudrate} = 19200;
$arg_hsh{parity} = "none";
$arg_hsh{databits} = 8;
$arg_hsh{stopbits} = 1;wake_up
The device sleeps in order to conserve power after 2 minutes of inactivity. A wake up call is provided which conforms to Section IV Waking up the Console
$vp_obj->wake_up();Sending a command when the console is sleeping might not wake up the device fast enough to read the first character correctly. Because of this, you should always perform a wakeup call before sending commands. Many of the calls such as start_loop, read_loop, get_one_loop, etc send a wake_up() command implicitly so there is no need to send one.
get_archive_period
Retrieves the archive period for the device. The archive period is the time period between each archived data record.
my $arc_period = $vp_obj->get_archive_period();
my $arc_sec = $arc_period * 60;
print ">Archive Period is currently: $arc_period minutes\n";set_archive_period
Sets the archive period. Acceptable values are 1, 5, 10, 15, 30, 60, 120 minutes. See Davis documentation.
$vp_obj->set_archive_period(5) || warn "Archive Period not set" ;According to the documentation this call clears the archive data.
gettime
Retrieve the current device time
my $ref = $vp_obj->gettime(); Returns a reference to a list ordered as
# hour : min : sec month / day / year
print "$ref->[2]:$ref->[1]:$ref->[0] $ref->[4]/$ref->[3]/$ref->[5]\n";
The values are returned in the same order as provided in the Davis documentation.
settime
Set the device time using a reference to a list compatible with the gettime returned reference.
The order is similar to the array returned by the perl localtime function. Here is an example setting the device time to the server time.
my $s_time = [ localtime() ];
$s_time->[4] += 1;
$vp_obj->settime($s_time); get_timezone
Returns the timezone of the device as a DateTime::TimeZone object.
The VantagePro does not deal with timezones particularly well. The time field contained in a record is the local time, with no information as to its timezone. This is problematic when the local time reverts from daylight saving time, as for the duration of that hour there will be multiple records containing the same time value, with no way of differentiating them other than the order that they have been recorded. In much the same way, if the timezone of the unit is changed, no record of this will be attached to each of the downloaded records.
For the above reasons, it is recommended that the device is configured for a named timezone, rather than offset from GMT, as it is easier to compensate for daylight saving changes.
start_loop
Begins a loop data acquisition sequence. Input is the number of loops to request. If no value is provided a loop of 1 is assumed. The function returns and expects a read_loop call to service the data which is delivered every 2-seconds per the documenation. I have found problems with higher numbered loops (>40 loops) and recommend the integrated get_one_loop() call instead and read a loop data packet at whatever rate you wish.
$vp_obj->start_loop(10);read_loop
Reads the LOOP data format as identified in Section IX Data Formats in the documentation. Note this only reads the later revision B loop format that is found in Vantage Pro devices after April 2002.
The data is returned via a reference to a hash.
$vp_obj->start_loop();
my $hsh_ref = $vp_obj->read_loop();
# print out hash reference
print Dumper $hsh_ref; get_one_loop
Combines a start_loop and a read_loop and returns a data hash.
my $hsh_ref = $vp_obj->get_one_loop();I have not tested to see how fast this function can be called before the device chokes. It will run at a 2-second rep rate without a problem.
The Loop data packet has a value for the Next_Record. This can be monitored in a loop and used to trigger an event to read the archive via do_dmpaft.
make_date_time_stamp
Function to create a date and time stamp suitable for using in the dmpaft command. The function expects a list in the following order ($year, $mon, $mday, $hour, $min) and returns a date stamp and time stamp.
my ($dstamp,$tstamp) = $vp_obj->make_date_time_stamp(2010,4,17,19,15);do_dmpaft
Function to retrieve the archive data after a provided date and time stamp. Refer to the Davis documentation Section IX. Data Formats for the sub-section concerning DMP and DMPAFT data format.
Functions requires a date stamp and time stamp as detailed in the documenation or provided in the make_date_time_stamp function above.
The date/time stamp is returned in the archive record and you can save the last returned date/time stamp values to use in the next call to return archive data after that date/time stamp. Note the date/time stamp must match a date/time stamp in the archive memory or the whole 513 records will be returned. Also if no date/time stamp is provided the complete archive will be returned.
The returned value is a reference to a list of hashes, one hash for each archive record.
my $ref = $vp_obj->do_dmpaft($dstamp,$tstamp);
unless ( @{$ref} ) { return 0 }
foreach my $arc_ref ( @{$ref} )
{
# Do something with the hash reference....
print Dumper $arc_ref;
} get_eeprom
Retrieve specific EEPROM configuration settings. Currently the following parameters are supported:
ARCHIVE_PERIOD
TIME_ZONE
MANUAL_OR_AUTO
DAYLIGHT_SAVINGS
GMT_OFFSET
GMT_OR_ZONE
SETUP_BITSThe return value is the raw hex value from the unit, so needs to be decoded:
my $rst = $self->get_eeprom('archive_period');
my $archive_period = hex($rst->[0]);get_setup_bits
Retrieve the setup of the device. Returns a hashref with the following keys:
TimeMode
IsAM
MonthDayFormat
WindCupSize
RainCollectorSize
Latitude
LongitudeSEE ALSO
Refer to:
Vantage Pro and Vantage Pro2 Serial Communication Reference Manual Available at:
http://www.davisnet.com/support/weather/download/VantageSerialProtocolDocs_v230.pdf
Example of module being used at:
http://lpo.dt.navy.mil
Other related Perl modules that might be of interest....
Device::Davis - Low level read/write function vanprod - High-level integrated daemon package with lots of bells and whistles. However, no support for retrieving archive data or setting archive period.
PREREQUISITES
Device::SerialPort Time::HiRes use POSIX qw(:errno_h :fcntl_h strftime) use Time::Local
Except for Device::SerialPort the prerequisites should be loaded with a default install.
AUTHOR
Steve Troxel, troxel AT perlworks.com
COPYRIGHT AND LICENSE
Copyright (C) 2010 by Steve Troxel
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.8 or, at your option, any later version of Perl 5 you may have available.