/ 
Device-Neurio-0.15
River stage one • 1 direct dependent • 1 total dependent
/ Device::Neurio

NAME

Device::Neurio - Methods for wrapping the Neurio API calls so that they are accessible via Perl

VERSION

Version 0.15

SYNOPSIS

This module provides a Perl interface to a Neurio sensor via the following 
methods:
  - new
  - connect
  - fetch_Samples
  - fetch_Samples_Full
  - fetch_Samples_Last_Live
  - fetch_Samples_Recent_Live
  - fetch_Stats_Energy
  - fetch_Appliances
  - fetch_Appliances_Events
  - fetch_Appliances_Specific
  - fetch_Appliances_Stats

Please note that in order to use the 'Samples' methods in this module you will 
require three parameters (key, secret, sensor_id) as well as an Energy Aware 
Neurio sensor installed in your house.  In order to use the 'Appliances'
methods, you will also require another parameter (location_id).  This information
can be obtained from the Neurio developpers website.

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

All date/time values are specified using ISO8601 format (yyyy-mm-ddThh:mm:ssZ)

SAMPLE CODE

  use Device::Neurio;

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

  $my_Neurio->connect();

  $data = $my_Neurio->fetch_Samples_Last_Live();
  print $data->{'consumptionPower'}

  $data = $my_Neurio->fetch_Samples_Recent_Live("2014-06-18T19:20:21Z");
  print $data->[0]->{'consumptionPower'}

  undef $my_Neurio;

EXPORT

All by default.

SUBROUTINES/METHODS

new - the constructor for a Neurio object

Creates a new instance which will be able to fetch data from a unique Neurio 
sensor.  All three parameters are required and can be obtained from the
Neurio developpers website.

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

  This method accepts the following parameters:
    - $key       : unique key for the account - Required 
    - $secret    : secret key for the account - Required 
    - $sensor_id : sensor ID connected to the account - Required 
    - $debug     : turn on debug messages - Optional

Returns a Neurio object if successful.
Returns 0 on failure

connect - open a secure connection to the Neurio server

Opens a secure connection via HTTPS to the Neurio server which provides
access to a set of API commands to access the sensor data.

An optional location ID can be given.  This is only required if calls
will be made to the 'Appliance' methods.  Calls to the 'Samples'
methods do not require that a location ID be set.  If a location_id is not
specified at connection, then it must be specified when using the 'Appliance'
methods.

A location ID can be acquired from the Neurio developpers web site

  $Neurio->connect($location_id);

  This method accepts the following parameter:
    - $location_id : unique location id - Optional 

Returns 1 on success 
Returns 0 on failure

fetch_Samples_Recent_Live - Fetch recent sensor samples

Retrieves recent sensor readings from the Neurio server.
The values represent the sum of all phases.

  $Neurio->fetch_Samples_Recent_Live($last);

  This method accepts the following parameters:
     $last - time of last sample received specified using ISO8601 
             format (yyyy-mm-ddThh:mm:ssZ)  - Optional
     
     If no value is specified for $last, a default of 2 minutes is used.

Returns an array of Perl data structures on success
$VAR1 = [
         {
           'generationEnergy' => 3716166644,
           'timestamp' => '2014-06-24T11:08:00.000Z',
           'consumptionEnergy' => 6762651207,
           'generationPower' => 564,
           'consumptionPower' => 821
         },
         ...
        ]
Returns 0 on failure

fetch_Samples_Last_Live - Fetch the last live sensor sample

Retrieves the last live sensor reading from the Neurio server.
The values represent the sum of all phases.

  $Neurio->fetch_Samples_Last_Live();

  This method accepts no parameters

Returns a Perl data structure on success:
$VAR1 = {
         'generationEnergy' => 3716027450,
         'timestamp' => '2014-06-24T11:03:43.000Z',
         'consumptionEnergy' => 6762445671,
         'generationPower' => 542,
         'consumptionPower' => 800
       };
Returns 0 on failure

fetch_Samples - Fetch sensor samples from the Neurio server

Retrieves sensor readings within the parameters specified.
The values represent the sum of all phases.

$Neurio->fetch_Samples($start,$granularity,$end,$frequency,$perPage,$page);

  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   : if the granularity is specified as 'minutes', then the 
                     frequency must be a multiple of 5 - Optional
    - $perPage     : number of results per page - Optional
    - $page        : page number to return - Optional

Returns an array of Perl data structures on success
    $VAR1 = [
             {
               'generationEnergy' => 3568948578,
               'timestamp' => '2014-06-21T19:00:00.000Z',
               'consumptionEnergy' => 6487889194,
               'generationPower' => 98,
               'consumptionPower' => 240
             },
            ...
            ]
Returns 0 on failure

fetch_Samples_Full - Fetches full samples for all phases

Retrieves full sensor readings including data for each individual phase within 
the parameters specified.

$Neurio->fetch_Samples_Full($start,$granularity,$end,$frequency,$perPage,$page);

  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
    - $perPage     : number of results per page - Optional
    - $page        : page number to return - Optional

Returns an array of Perl data structures on success
[
 {
   'timestamp' => '2014-06-16T19:20:21.000Z',
   'channelSamples' => [
                         {
                           'voltage' => '123.19',
                           'power' => 129,
                           'name' => '1',
                           'energyExported' => 27,
                           'channelType' => 'phase_a',
                           'energyImported' => 2682910899,
                           'reactivePower' => 41
                         },
                         {
                           'voltage' => '123.94',
                           'power' => 199,
                           'name' => '2',
                           'energyExported' => 6,
                           'channelType' => 'phase_b',
                           'energyImported' => 3296564362,
                           'reactivePower' => -45
                         },
                         {
                           'voltage' => '123.57',
                           'power' => 327,
                           'name' => '3',
                           'energyExported' => 10,
                           'channelType' => 'consumption',
                           'energyImported' => 5979475235,
                           'reactivePower' => -4
                         }
                       ]
 },
 ...
]
Returns 0 on failure

fetch_Stats_Energy - Fetches energy statistics

Retrieves energy statistics within the parameters specified.
The values represent the sum of all phases.

  $Neurio->fetch_Stats_Energy($start,$granularity,$end,$frequency,$perPage,$page);

  This method accepts the following parameters:
    - $start       : yyyy-mm-ddThh:mm:ssZ - Required
                     specified using ISO8601 format
    - $granularity : minutes|hours|days|months - Required
    - $end         : yyyy-mm-ddThh:mm:ssZ - Optional
                     specified using ISO8601 format
    - $frequency   : if the granularity is specified as 'minutes', then the 
                     frequency must be a multiple of 5 - Optional
    - $perPage     : number of results per page - Optional
    - $page        : page number to return - Optional

Returns a Perl data structure containing all the raw data
Returns 0 on failure

fetch_Appliances - Fetch the appliances for a specific location

Retrieves the appliances added for a specific location.  

The location_id is an optional parameter because it can be specified when 
connecting.  If it is specified below, then this will over-ride the location 
ID set when connecting, but for this function call only.

  $Neurio->fetch_Appliances($location_id);

  This method accepts the following parameters:
    - $location_id  : id of a location - Optional

Returns an array of Perl data structures on success
$VAR1 = [
         {
           'locationId' => 'xxxxxxxxxxxxxxx',
           'name' => 'lighting_appliance',
           'id' => 'yyyyyyyyyyyyyyyyy',
           'label' => 'Range Light on Medium',
           'tags' => []
         },
         {
           'locationId' => 'xxxxxxxxxxxxxxx-3',
           'name' => 'refrigerator',
           'id' => 'zzzzzzzzzzzzzzzz',
           'label' => '',
           'tags' => []
         },
         ....
        ]
Returns 0 on failure

fetch_Appliances_Specific - Fetch information about a specific appliance

Retrieves information about a specific appliance.  

The applicance_id parameter is determined by using the fetch_Appliance method 
which returns a list of appliances with their IDs

  $Neurio->fetch_Appliances_Specific($appliance_id);

  This method accepts the following parameters:
    - $appliance_id  : id of the appliance - Required

Returns a Perl data structure on success:
$VAR1 = {
         'locationId' => 'xxxxxxxxxxxxx,
         'name' => 'lighting_appliance',
         'id' => 'yyyyyyyyyyyyyyy',
         'label' => 'Range Light on Medium',
         'tags' => []
       };
Returns 0 on failure

fetch_Appliances_Stats - Fetch usage data for a given appliance

Retrieves usage data for a specific appliance at a specific location.  

The applicance_id parameter is determined by using the fetch_Appliance method 
which returns a list of appliances with their IDs

  $Neurio->fetch_Appliances_Stats($location_id,$appliance_id,$start,$granularity,$end,$frequency,$perPage,$page);

  This method accepts the following parameters:
     - $location_Id  : id of a location - Required
     - $appliance_id : id of the appliance - Required
     - $start         : yyyy-mm-ddThh:mm:ssZ - Required
                       specified using ISO8601 format
     - $granularity   : seconds|minutes|hours|days - Required
     - $end           : yyyy-mm-ddThh:mm:ssZ - Required
                       specified using ISO8601 format
     - $frequency     : an integer - Required
     - $perPage       : number of results per page - Optional
     - $page          : page number to return - Optional

Returns an array of Perl data structures on success
$VAR1 = [
         {
           'energy' => 152927,
           'averagePower' => '110',
           'timeOn' => 1398,
           'guesses' => {},
           'end' => '2014-09-05T14:00:00.000Z',
           'lastEvent' => {
                            'energy' => 74124,
                            'averagePower' => '109',
                            'guesses' => {},
                            'end' => '2014-09-05T13:50:44.055Z',
                            'groupIds' => [
                                            'aaaaaaaaaaaaaaaaa'
                                          ],
                            'id' => '5EGh7o8eQJuIvsdA4qMkEw',
                            'appliance' => {
                                             'locationId' => 'ccccccccccccccccc-3',
                                             'name' => 'refrigerator',
                                             'id' => 'bbbbbbbbbbbbbbbbb',
                                             'label' => '',
                                             'tags' => []
                                           },
                            'start' => '2014-09-05T13:39:20.115Z'
                          },
           'groupIds' => [
                           'aaaaaaaaaaaaaaaaa'
                         ],
           'eventCount' => 2,
           'usagePercentage' => '2.465231',
           'id' => 'ddddddddddddddd',
           'appliance' => {
                            'locationId' => 'ccccccccccccccccc-3',
                            'name' => 'refrigerator',
                            'id' => 'bbbbbbbbbbbbbbbbb',
                            'label' => '',
                            'tags' => []
                          },
           'start' => '2014-09-05T13:00:00.000Z'
         },
         ......
       ]
Returns 0 on failure

fetch_Appliances_Events_by_Location - Fetch events for a specific location

Retrieves events for a specific location.  An event is an interval when an 
appliance was in use.

The applicance_id parameter can be determined by using the fetch_Appliance method 
which returns a list of appliances with their IDs.

The function has the following 2 possibilities for parameters:

  $Neurio->fetch_Appliances_Events_by_Location($location_id, $start,$end,$perPage,$page);
  $Neurio->fetch_Appliances_Events_by_Location($location_id, $since,$perPage,$page);

  This method accepts the following parameters:
     - $location_Id  : id of a location - Required
     - $start        : yyyy-mm-ddThh:mm:ssZ - Required
                       specified using ISO8601 format
     - $end          : yyyy-mm-ddThh:mm:ssZ - Required
                       specified using ISO8601 format
     - $since        : yyyy-mm-ddThh:mm:ssZ - Required
                       specified using ISO8601 format
     - $perPage      : number of results per page - Optional
     - $page         : page number to return - Optional

Returns an array of Perl data structures on success
 [
   {
       "id" : "1cRsH7KQTeONMzjSuRJ2aw",
       "createdAt" : "2014-04-21T22:28:32Z",
       "updatedAt" : "2014-04-21T22:45:32Z",
       "appliance" : {
           "id" : "2SMROBfiTA6huhV7Drrm1g",
           "name" : "television",
           "label" : "upstairs TV",
           "tags" : ["bedroom_television", "42 inch LED"],
           "locationId" : "0qX7nB-8Ry2bxIMTK0EmXw"
       },
       "start" : "2014-04-21T05:26:10.785Z",
       "end" : "2014-04-21T05:36:00.547Z",
       "guesses" : {"dryer1" : 0.78, "dishwasher_2014" : 0.12},
       "energy" : 247896,
       "averagePower" : 122,
       "groupIds" : [ "2pMROafiTA6huhV7Drrm1g", "4SmROBfiTA6huhV7Drrm1h" ],
       "cycleCount" : 5,
       "isRunning" : false
   },
   ...
]
 Returns 0 on failure

fetch_Appliances_Events_by_Appliance - Fetch events for a specific appliance

Retrieves events for a specific appliance.  An event is an interval when an 
appliance was in use.

The applicance_id parameter can be determined by using the fetch_Appliance method 
which returns a list of appliances with their IDs.

  $Neurio->fetch_Appliances_Events_by_Appliance($appliance_id,$start,$end,$perPage,$page);

  This method accepts the following parameters:
     - $appliance_id : id of the appliance - Required
     - $start        : yyyy-mm-ddThh:mm:ssZ - Required
                       specified using ISO8601 format
     - $end          : yyyy-mm-ddThh:mm:ssZ - Required
                       specified using ISO8601 format
     - $since        : yyyy-mm-ddThh:mm:ssZ - Required
                       specified using ISO8601 format
     - $perPage      : number of results per page - Optional
     - $page         : page number to return - Optional

Returns an array of Perl data structures on success
[
   {
       "id" : "1cRsH7KQTeONMzjSuRJ2aw",
       "createdAt" : "2014-04-21T22:28:32Z",
       "updatedAt" : "2014-04-21T22:45:32Z",
       "appliance" : {
           "id" : "2SMROBfiTA6huhV7Drrm1g",
           "name" : "television",
           "label" : "upstairs TV",
           "tags" : ["bedroom_television", "42 inch LED"],
           "locationId" : "0qX7nB-8Ry2bxIMTK0EmXw"
       },
       "start" : "2014-04-21T05:26:10.785Z",
       "end" : "2014-04-21T05:36:00.547Z",
       "guesses" : {"dryer1" : 0.78, "dishwasher_2014" : 0.12},
       "energy" : 247896,
       "averagePower" : 122,
       "groupIds" : [ "2pMROafiTA6huhV7Drrm1g", "4SmROBfiTA6huhV7Drrm1h" ],
       "cycleCount" : 5,
       "isRunning" : false
   },
   ...
]
Returns 0 on failure

dump_Object - shows the contents of the local Neurio object

shows the contents of the local Neurio object in human readable form

  $Neurio->dump_Object();

  This method accepts no parameters

Returns nothing

get_last_reason - returns the text generated by the most recent fetch

Returns the HTTP Header reason for the most recent fetch command

  $Neurio->get_last_reason();

  This method accepts no parameters

Returns the textual reason

get_last_code - returns the code generated by the most recent fetch

Returns the HTTP Header code for the most recent fetch command

  $Neurio->get_last_code();

  This method accepts no parameters

Returns the numeric code

get_last_exec_time - returns the execution time for the last fetch

Returns the number of milliseconds it took for the last fetch call

  $Neurio->get_last_exec_time();

  This method accepts no parameters

Returns the number of milliseconds

AUTHOR

Kedar Warriner, kedar at cpan.org

BUGS

Please report any bugs or feature requests to C<bug-device-Neurio at rt.cpan.org>
or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Device-Neurio
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::Neurio

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.