/ 
Ham-Resources-Propagation-0.04
River stage zero No dependents
/ Ham::Resources::Propagation

NAME

Ham::Resources::Propagation - Get Solar and propagation data from web that's useful for Amateur Radio applications.

VERSION

Version 0.04

SYNOPSIS

  use Ham::Propagation;

  my $propagation = new Ham::resources::Propagation;
  die $propagation->error_message if $propagation->is_error;

  # access to all data: Solar, HF, VHF and extended

  foreach (sort @{$propagation->all_item_names})
  {
     print "$_ = ".$propagation->get($_)."\n";
  }

  # Access data by category

  my $category = "vhf"; # categories may be solar, hf, vhf and extended
  foreach (sort keys %{$propagation->{$category}})
  {
	 print $_.": ".$propagation->{$category}->{$_}."\n";
  } 

  # Access to unique data item
	# for direct access to Solar data
  print "Update: ".$propagation->{solar_data}->{updated}."\n"; 
	
	# or access to data using get method if you don't know the category of an item
  print "80-40m at night: ".$propagation->get('80-40m_night');

DESCRIPTION

The Ham::Resources::Propagation module provides a simple and easy to use interface to obtain and explain data from N0NBH's solar resource website that's useful for Radio Amateur applications.

This module provides not only the same values from the website but it makes a categorization based on a simplified scale.

Also, this module offers you an interpretation of some values, like solar or electron flux.

This module don't use a static data structure to create the data object, if not, when it creates the hash with the XML data using the names of the labels to create their own structure. This means that if the original XML is modified by a new value, the resulting object displays the new value without changing the internal structure of the module.

The original data structure has 3 groups of information: solar, HF and VHF propagation. But this module adds a new group (call extended) interpreting some values, like band openings, electron alert, radio blackouts and solar radiation, and his impact on HF.

This module is based on XML::Reader to obtain a hash from the original XML website resource. So you can call not only all data but a specific group of data or an specific item too.

For example:

$propagation->{solar_data}->{aindex}, returns the A-Index value from the Solar group

$propagation->get(aindex), returns the A-Index value without need to add the group

$propagation->get(vhf), returns all data that this group.

There are 4 groups to call: solar, hf, vhf and extended.

You can use the all_item_names method for obtain a list of all item names of data and to pass to get method, for example:

foreach (@{$propagation->all_item_names}) 
{
	  print "$_ = ".$propagation->get($_)."\n";
}

It is highly recommended don't use 'sort' in this foreach.

CONSTRUCTOR

new()

 Usage    : my $propagation = Ham::Resources::Propagation->new();
 Function : creates a new Ham::Propagation object
 Returns  : a Ham::Propagation object
 Args     : a hash:
            key       required?   value
            -------   ---------   -----
            timeout   no          an integer of seconds to wait for
                                  the timeout of the web site
                                  default = 10                               

	  description no	  an string 'numeric', return only 
	  			  numeric data, 'text' returns
				  values with text index,
				  Default value is 'text'

METHODS

get()

Usage    : my $sunspots = $propagation->get( sunspots );
Function : gets a single item of solar data
Returns  : a Ham::Propagation object
Args     : a single item from the list of data items below

get_groups

Usage    : my $sunspots = $propagation->get_groups;
Function : gets an array of existing groups of data
Returns  : an array reference
Args     : n/a

all_item_names

Usage    : $propagation->all_item_names
Function : get an array reference of all solar and propagation data items available
           from the object   
Returns  : an array reference
Args     : n/a

is_error()

Usage    : $propagation->is_error()
Function : test for an error if one was returned from the call to the resource site
Returns  : a string, the error message
Args     : n/a

error_message()

Usage    : $propagation->error_message()
Function : if there was an error message when trying to call the resource site, this is it
Returns  : a string, the error message
Args     : n/a

DATA ITEMS

The following items are available from the object. Use them with the get() method.

There are four groups of data items: Solar, Hf, VHF and Extended.

SOLAR DATA

The current list of items for solar data are like as follows, but it will be increased (or decreased) depends from XML data source:

aindex
aurora
electonflux
heliumline
kindex
kindexnt
latdegree
magneticfield
normalization
protonflux
solarflux
solarwind
sunspots
updated
xray
geomagfield
signalnoise
fof2

HF PROPAGATION DATA

The category 'hf' show  the state of propagation in decametric bands, separated by the day and night. 

Possible values are: Good, Fair and Poor.
12-10m_day

Propagation condition at the day from 10 to 12 meters band.

12-10m_night

Propagation condition at the night from 10 to 12 meters band.

17-15m_day

Propagation condition at the day from 15 to 17 meters band.

17-15m_night

Propagation condition at the night from 15 to 17 meters band.

30-20m_day

Propagation condition at the day from 20 to 30 meters band.

30-20m_night

Propagation condition at the night from 20 to 30 meters band.

80-40m_day

Propagation condition at the day from 40 to 80 meters band.

80-40m_night

Propagation condition at the night from 40 to 80 meters band.

VHF PROPAGATION DATA

The category 'vhf' show  the state of some atmospheric phenomena which may be involved in the propagation on metric bands. Each item show open or closed band.
europe E-Skip

Possibility of use skips through ionospheric 'E' layer in Europe.

europe_4m E-Skip

Possibility of use skips on 4 meters band through ionospheric 'E' layer in Europe.

europe_6m E-Skip

Possibility of use skips on 6 meters band through ionospheric 'E' layer in Europe.

north_america E-Skip

Possibility of use skips through ionospheric 'E' layer in North America.

northern_hemi vhf-aurora

How it affects the aurora in DX-type communications in the northern hemisphere.

EXTENDED DATA

The category "extended" shows a human explanation interpreting some of the solar data.

radioblackouts

This item calculated a category index of the Solar X-Ray and his iteraction over HF transmisions.

solarradiation

This item calculated a category index of the severity of solar proton events and his impact on polar regions.

bandopenings

This item calculated a category index of band opening based on the Solar flux index.

electronalert

This item warn you when the electron flux will be dangerous for propagation.

TODO

  • Add more data items or new sources for more information.

  • Improve more error checking.

  • Add option to add the unit of measurement from any values when description argument is 'text'.

ACKNOWLEDGEMENTS

This module gets its data from N0NBH's Propagation Resource Page at http://www.hamqsl.com.

Thanks to Paul L Herrman N0NBH!

AUTHOR

Carlos Juan Diaz, EA3HMB <ea3hmb at gmail.com>

COPYRIGHT AND LICENSE

Ham::Resources::Propagation is Copyright (C) 2011-2012 Carlos Juan Diaz, EA3HMB.

This module is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. For details, see the full text of the license in the file LICENSE.

This program is distributed in the hope that it will be useful, but it is provided "as is" and without any express or implied warranties. For details, see the full text of the license in the file LICENSE.