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:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Device-NeurioTools
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Device-NeurioTools
CPAN Ratings

http://cpanratings.perl.org/d/Device-NeurioTools
Search CPAN

http://search.cpan.org/dist/Device-NeurioTools/

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.

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

cpanm

cpanm Device::NeurioTools

CPAN shell

perl -MCPAN -e shell
install Device::NeurioTools

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)