Steve Troxel > Device-VantagePro-0.23 > Device::VantagePro

Download:
Device-VantagePro-0.23.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.23   Source   Latest Release: Device-VantagePro-0.25

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;
  
  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

Retreive 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 documentatoin.

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); 

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 documenation. 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 $rst = $vp_obj->do_dmpaft($dstamp,$tstamp); 
   unless ( @{$ref} ) { return 0 }
 
   my $data_ref; 
   foreach my $arc_ref ( @{$ref} ) 
   {
      # Do something with the hash reference.... 
          print Dumper $arc_ref; 
   } 

SEE 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.

syntax highlighting: