The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Device::NeurioTools - More complex methods and tools for accessing data collected by a Neurio sensor module.

VERSION

Version 0.07

SYNOPSIS

 This module allows access to more complex and detailed data derived from data 
 collected by a Neurio sensor.  This is done via an extended set of methods: 
   - new
   - connect
   - set_flat_rate
   - get_flat_rate
   - get_flat_cost
   - get_kwh
  
 Please note that in order to use this module you will require three parameters
 (key, secret, sensor_id) as well as an Energy Aware Neurio sensor installed in
 your house.

 The module is written entirely in Perl and has been developped on Raspbian Linux.

SAMPLE CODE

    use Device::Neurio;
    use Device::NeurioTools;

    $my_Neurio = Device::Neurio->new($key,$secret,$sensor_id);

    $my_Neurio->connect();

    $my_NeurioTools = Device::NeurioTools->new($my_Neurio,$debug);

    $my_NeurioTools->set_timezone();
    $my_NeurioTools->set_flat_rate(0.08);
    
    $start = "2014-06-24T00:00:00".$my_NeurioTools->get_timezone();
    $end   = "2014-06-24T23:59:59".$my_NeurioTools->get_timezone();
    $kwh   = $my_NeurioTools->get_kwh($start,"minutes",$end,"5");

    undef $my_NeurioTools;
    undef $my_Neurio;

EXPORT

All by default.

###################################################################################################

new - the constructor for a NeurioTools object

 Creates a new instance of NeurioTools which will be able to fetch data from 
 a unique Neurio sensor.

 my $Neurio = Device::NeurioTools->new($neurio, $debug);

   This method accepts the following parameters:
     - $neurio : a valid CONNECTED Neurio object
     - $debug  : enable or disable debug messages (disabled by default - optional)

 Returns 1 on success
 Returns 0 on failure
 

DESTROY - the destructor for a NeurioTools object

 Destroys a previously created NeuriTools object.
 

set_flat_rate - set the rate charged by your electicity provider

 Defines the rate charged by your electricity provider.

   $NeurioTools->set_flat_rate($rate);
 
   This method accepts the following parameters:
     - $rate      : rate charged per kwh - Required
 
 Returns 1 on success 
 Returns 0 on failure
 

set_TwoTier_rate - set the two tier rates charged by your electicity provider

 Defines the two tier rates charged by your electricity provider.
 The two tiers are defined according to the power consumed.
 
 For example:
   - $0.05 for the first 20 kWh per day
   - $0.08 for the remaining kWh per day

   $NeurioTools->set_TwoTier_rate($rate1,$cutoff,$rate2);
 
   This method accepts the following parameters:
     - $rate1     : rate charged per kwh for usage up to the cutoff - Required
     - $cutoff    : power consumtion point in kWh at which the rate changes - Required
     - $rate2     : rate charged per kwh for usage abpve the cutoff - Required
 
 Returns 1 on success 
 Returns 0 on failure
 

get_flat_rate - return the flat rate charged by your electicity provider

 Returns the value for the flat rate set using 'set_flat_rate()'

   $NeurioTools->get_flat_rate();
 
   This method accepts no parameters
 
 Returns rate 
 

get_TwoTier_rate - return the cutoff and two tier rates charged by your electicity provider

 Returns the value for the cutoff and two tier rates set using 'set_TwoTier_rate()'

   $NeurioTools->get_TwoTier_rate();
 
   This method accepts no parameters
 
 Returns list containing cutoff and rates 
 

set_ISO8601_timezone - set the timezone offset for ISO8601

 Sets the timezone offset in ISO8601 format.  If no parameter is specified it 
 sets the system defined timezone offset.

   $NeurioTools->set_ISO8601_timezone($offset);
 
   This method accepts the following parameters:
     - $offset      : specified timezone offset in minutes - Optional
 
 Returns 1 on success 
 Returns 0 on failure
 

get_flat_cost - calculate the cost of consumed power for the specified period

 Calculates the cost of consumed power over the period specified.

   $NeurioTools->get_flat_cost($start,$granularity,$end,$frequency);
   
   This method requires that a 'flat rate' be set using the set_flat_rate() method
 
   This method accepts the following parameters:
     - $start       : yyyy-mm-ddThh:mm:ssZ - Required
     - $granularity : seconds|minutes|hours|days - Required
     - $end         : yyyy-mm-ddThh:mm:ssZ - Optional
     - $frequency   : an integer - Optional
 
 Returns the cost on success 
 Returns 0 on failure
 

get_TwoTier_cost - calculate the cost of consumed power for the specified period

 Calculates the cost of consumed power over the period specified.

   $NeurioTools->get_TwoTier_cost($start,$granularity,$end,$frequency);
   
   This method requires that a 'TwoTier rate' be set using the set_TwoTier_rate() method
 
   This method accepts the following parameters:
     - $start       : yyyy-mm-ddThh:mm:ssZ - Required
     - $granularity : seconds|minutes|hours|days - Required
     - $end         : yyyy-mm-ddThh:mm:ssZ - Optional
     - $frequency   : an integer - Optional
 
 Returns the cost on success 
 Returns 0 on failure
 

get_kwh_consumed - kwh of consumed power for the specified period

 Calculates the total kwh of consumed power over the period specified.

   $NeurioTools->get_kwh_consumed($start,$granularity,$end,$frequency);
 
   This method accepts the following parameters:
     - $start       : yyyy-mm-ddThh:mm:ssZ - Required
                      specified using ISO8601 format
     - $granularity : seconds|minutes|hours|days - Required
     - $end         : yyyy-mm-ddThh:mm:ssZ - Optional
                      specified using ISO8601 format
     - $frequency   : an integer - Optional
 
 Returns the kwh on success 
 Returns 0 on failure
 

get_kwh_generated - kwh of generated power for the specified period

 Calculates the total kwh of generated power over the period specified.

   $NeurioTools->get_kwh_generated($start,$granularity,$end,$frequency);
 
   This method accepts the following parameters:
     - $start       : yyyy-mm-ddThh:mm:ssZ - Required
                      specified using ISO8601 format
     - $granularity : seconds|minutes|hours|days - Required
     - $end         : yyyy-mm-ddThh:mm:ssZ - Optional
                      specified using ISO8601 format
     - $frequency   : an integer - Optional
 
 Returns the kwh on success 
 Returns 0 on failure
 

get_energy_consumed - energy consumed for the specified period

 Calculates the total energy consumed over the period specified.

   $NeurioTools->get_energy_consumed($start,$granularity,$end,$frequency);
 
   This method accepts the following parameters:
     - $start       : yyyy-mm-ddThh:mm:ssZ - Required
                      specified using ISO8601 format
     - $granularity : seconds|minutes|hours|days - Required
     - $end         : yyyy-mm-ddThh:mm:ssZ - Optional
                      specified using ISO8601 format
     - $frequency   : an integer - Optional
 
 Returns the energy on success 
 Returns 0 on failure
 

get_number_of_appliances - return the number of appliances

 Returns the number of appliances defined in the system.

   $NeurioTools->get_appliance_ID();
 
   This method accepts no parameters:
 
 Returns the number of appliances on success 
 Returns 0 on failure
 

get_appliance_ID - return the id for the appliance specified

 Returns the appliance ID for the name and label specified.

   $NeurioTools->get_appliance_ID($name,$label);
 
   This method accepts the following parameters:
     - $name  : textual name of appliance - Required
     - $label : textual label of appliance - Optional
 
 Returns the appliance ID on success 
 Returns 0 on failure
 

get_cycle_ID - return the id for the most recent cycle

 Returns the ID for the most recent cycle.

   $NeurioTools->get_cycle_ID();
 
   This method accepts no parameters
 
 Returns the cycle ID on success 
 Returns 0 on failure
 

get_cycle_group_ID - return the id for the most recent cycle group

 Returns the ID for the most recent cycle group.

   $NeurioTools->get_cycle_group_ID();
 
   This method accepts no parameters
 
 Returns the cycle group ID on success 
 Returns 0 on failure
 

get_edges_ID - return an edges id

 Returns and edges ID.

   $NeurioTools->get_edges_ID();
 
   This method accepts no parameters
 
 Returns the edges ID on success 
 Returns 0 on failure
 

get_power_consumed - power consumed for the specified period

 Calculates the total power  consumed over the period specified.

   $NeurioTools->get_energy_consumed($start,$granularity,$end,$frequency);
 
   This method accepts the following parameters:
     - $start       : yyyy-mm-ddThh:mm:ssZ - Required
                      specified using ISO8601 format
     - $granularity : seconds|minutes|hours|days - Required
     - $end         : yyyy-mm-ddThh:mm:ssZ - Optional
                      specified using ISO8601 format
     - $frequency   : an integer - Optional
 
 Returns the energy on success 
 Returns 0 on failure
 

get_ISO8601_time - convert linux time to the time part of ISO8601

 Returns the time part in ISO8601 format of the specified linux time.

   $NeurioTools->get_ISO8601_time($time);
 
   This method accepts the following parameters:
     - $time       : linux time - Required
 
 Returns time part of ISO8601 format on success 
 Returns 0 on failure
 

get_ISO8601_date - convert linux time to the date part of ISO8601

 Returns the date part in ISO8601 fomrat of the specified linux time.

   $NeurioTools->get_ISO8601_date($time);
 
   This method accepts the following parameters:
     - $time       : linux time - Required
 
 Returns date part of ISO8601 format on success 
 Returns 0 on failure
 

get_ISO8601_timezone - return the ISOS8601 timezone offset

 Returns the timezone part in ISO8601 format for the current location
 from the value specified with set_ISO8601_timezone

   $NeurioTools->get_ISO8601_timezone();
 
   This method accepts no parameters
 
 Returns timezone offset 
 

get_ISO8601 - return the entire ISOS8601 formatted date/time/timezone

 Returns the entire ISO8601 formatted date/time/timezone based on the time
 parameter passed

   $NeurioTools->get_ISO8601($time);
 
   This method accepts the following parameters:
     - $time       : linux time - Required
 
 Returns entire ISO8601 string on success 
 Returns 0 on failure
 

AUTHOR

Kedar Warriner, kedar at cpan.org

BUGS

 Please report any bugs or feature requests to C<bug-device-NeurioTools at rt.cpan.org>
 or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Device-NeurioTools
 I will be notified, and then you'll automatically be notified of progress on 
 your bug as I make changes.

SUPPORT

 You can find documentation for this module with the perldoc command.

  perldoc Device::NeurioTools


 You can also look for information at:

ACKNOWLEDGEMENTS

 Many thanks to:
  The guys at Energy Aware Technologies for creating the Neurio sensor and 
      developping the API.
  Everyone involved with CPAN.

LICENSE AND COPYRIGHT

 Copyright 2014 Kedar Warriner <kedar at cpan.org>.

 This program is free software; you can redistribute it and/or modify it
 under the terms of either: the GNU General Public License as published
 by the Free Software Foundation; or the Artistic License.

 See http://dev.perl.org/licenses/ for more information.