NAME
App::RPi::EnvUI::API - Core API abstraction class for the App::RPi::EnvUI web app
SYNOPSIS
my $api = App::RPi::EnvUI::API->new;
... #FIXME: add a real exampleDESCRIPTION
This class can be used outside of the App::RPi::EnvUI web application to update settings, read statuses, perform analysis and generate reports.
It's primary purpose is to act as an intermediary between the web app itself, the asynchronous events that run within their own processes, the environment sensors, and the application database.
METHODS
new(%args)
Instantiates a new core API object. Send any/all parameters in within hash format (eg: testing =\ 1)).
Parameters:
configOptional, String. Name of the configuration file to use. Very rarely required.
Default: config/envui.json
testingOptional, Bool. Send in 1 to enable testing, 0 to disable it.
Default: 0
test_mockThis flag is only useful when testing param is set to true, and should only be used when writing unit tests for the App::RPi::EnvUI::Event class. Due to the way the system works, the API has to avoid mocking out items in test mode, and the mocks have to be set within the test file itself. Do not use this flag unless you are writing unit tests.
debug_levelOptional, Integer. Send in a level of 0-7 to enable logging.
Default: -1 (logging disabled)
log_fileOptional, String. Name of file to log to. We log to STDOUT by default. The debug_level parameter must be changed from default for this parameter to have any effect.
Default: undef
debug_sensorOptional, Bool. Enable/disable debug print output from the RPi::DHT11 sensor code. Send in 1 to enable, and 0 to disable.
Default: 0 (off)
action_humidity($aux_id, $humidity)
Performs the check of the current humidity against the configured set limit, and enables/disables any devices attached to the humidity auxillary GPIO pin, if set.
Parameters:
$aux_idMandatory, String. The string name representation of the humidity auxillary. By default, this will be aux2.
$humidityMandatory: Integer. The integer value of the current humidity (typically supplied by the RPi::DHT11 hygrometer sensor.
action_light($dt)
Performs the time calculations on the configured light on/off event settings, and turns the GPIO pin associated with the light auxillary channel on and off as required.
Parameters (only used for testing):
%argsOptional (use for testing only!). Pass in a hash with the desired configuration parameters as found in the configuration file for light configuration.
action_temp($aux_id, $temperature)
Performs the check of the current temperature against the configured set limit, and enables/disables any devices attached to the temp auxillary GPIO pin, if set.
Parameters:
$aux_idMandatory, String. The string name representation of the temperature auxillary. By default, this will be aux1.
auth($user, $pw)
Checks whether a user is supplying the correct password.
Parameters:
$userMandatory, String. The user name to validate the password for.
$pwMandatory, String. The plain text password to verify.
Return: True (1) if successful, undef otherwise.
aux($aux_id)
Retrieves from the database a hash reference that contains the details of a specific auxillary channel, and returns it.
Parameters:
$aux_idMandatory, String. The string name representation of the auxillary channel to retrieve (eg: aux1).
Returns: Hash reference with the auxillary channel details.
auxs
Fetches the details of all the auxillary channels from the database. Takes no parameters.
Return: A hash reference of hash references, where each auxillary channel name is a key, and the value is a hash reference containing that auxillary channel's details.
aux_id($aux)
Extracts the name/ID of a specific auxillary channel.
Parameters:
$auxMandatory, href. A hash reference as returned from a call to aux().
Return: String. The name/ID of the specified auxillary channel.
aux_override($aux_id, $override)
Sets/gets the override status of a specific aux channel.
The override functionality is a flag in the database that informs the system that automated triggering of an auxillary GPIO pin should be bypassed due to user override.
Parameters:
$aux_idMandatory, String. The string name of an auxillary channel (eg: aux1).
$stateOptional, Bool. 0 to disable an aux pin override, 1 to enable it.
Return: Bool. Returns the current status of the aux channel's override flag.
aux_pin($aux_id, $pin)
Associates a GPIO pin to a specific auxillary channel.
Parameters:
$aux_idMandatory, String. The string name of an auxillary channel (eg: aux1).
$pinOptional, Integer. The GPIO pin number that you want associated with the specified auxillary channel.
Return: The GPIO pin number associated with the auxillary channel specified.
aux_state($aux_id, $state)
Sets/gets the state (ie. on/off) value of a specific auxillary channel's GPIO pin.
Parameters:
$aux_idMandatory, String. The string name of an auxillary channel (eg: aux1).
$stateOptional, Bool. 0 to turn the pin off (LOW), or 1 to turn it on (HIGH).
Return: Bool. Returns the current state of the aux pin.
aux_time($aux_id, $time)
Sets/gets the length of time an auxillary channel's GPIO pin has been HIGH (on). Mainly used to determine timers.
Parameters:
$aux_idMandatory, String. The string name of an auxillary channel (eg: aux1).
$timeOptional, output from time(). If sent in, we'll set the start time of a pin on event to this.
Return, Integer (seconds). Returns the elapsed time in seconds since the last timestamp was sent in with the $time parameter, after being subtracted with a current time() call. If $time has not been sent in, or an internal timer has reset this value, the return will be zero (0).
config($conf_file)
Sets/gets the currently loaded configuration file.
Parameters:
$conf_fileOptional, String. The name of a configuration file. This is only useful on instantiation of a new object.
Default: config/envui.json
Returns the currently loaded configuration file name.
db($db_object)
Sets/gets the internal App::RPi::EnvUI::DB object. This method allows you to swap DB objects (and thereby DB handles) within separate processes.
Parameters:
$db_objectOptional, App::RPi::EnvUI::DB object instance.
Returns: The currently loaded DB object instance.
debug_sensor($bool)
Enable/disable RPi::DHT11 sensor's debug print output.
Parameters:
$boolOptional, Bool. 1 to enable debugging, 0 to disable.
Return: Bool. The current state of the sensor's debug state.
Default: False (0)
env($temp, $humidity)
Sets/gets the current temperature and humidity pair.
Parameters:
All parameters are optional, but if one is sent in, both must be sent in.
$tempOptional, Integer. The current temperature.
$humidityOptional, Integer. The current humidity .
Return: A hash reference in the format {temp = Int, humidity => Int}>
env_humidity_aux
Returns the string name of the humidity auxillary channel (default: aux2). Takes no parameters.
env_temp_aux
Returns the string name of the temperature auxillary channel (default: aux1). Takes no parameters.
env_light_aux
Returns the string name of the light auxillary channel (default: aux3). Takes no parameters.
events
Initializes and starts the asynchronous timed events that operate in their own processes, performing actions outside of the main thread.
Takes no parameters, has no return.
graph_data
Returns a hash reference with keys temp and humidity, where the values of each are an array reference of array references with the inner arefs containing the element number and the temp/humidity value.
It attempts to fetch data for 24 hours, sampling approximately every minute. If no data is found far enough back, the temp/humidity will be set to 0.
humidity
Returns as an integer, the current humidity level.
temp
Returns as an integer, the current temperature level.
set_light_time
Sets in the database the values for lights-on and lights-off time.
Takes no parameters, there is no return.
log
Returns a pre-configured Logging::Simple object, ready to be cloned with its child() method.
log_file($filename)
Sets/gets the log file for the internal logger.
Parameters:
$filenameOptional, String. The name of the log file to use. Note that this won't have any effect when used in user space, and is mainly a convenience method. It's used when instantiating a new object.
Return: The string name of the currently in-use log file, if set.
debug_level($level)
Sets/gets the current debug logging level.
Parameters:
$levelOptional, Integer. Sets the logging level between 0-7.
Return: Integer, the current level.
Default: -1 (logging disabled)
passwd($pw)
Generates an SHA-1 hashed password.
Parameters:
$pwMandatory, String. A plain text string (the password).
Return: SHA-1 hashed password string.
read_sensor
Retrieves and returns the current temperature and humidity within an array of two integers.
sensor($sensor)
Sets/gets the current hygrometer sensor object. This method is here so that for testing, we can send in mocked sensor objects.
Parameters:
$sensorOptional, RPi::DHT11 object instance.
Return: The sensor object.
set_light_times
Internal method that sets the light on-off times in the database, once on webapp initial startup, then at the end of the lights-off trigger in action_light().
switch($aux_id)
Enables/disables the GPIO pin associated with the specified auxillary channel, based on what the current state of the pin is. If it's currently off, it'll be turned on, and vice-versa.
Parameters:
$aux_idMandatory, String. The string name of the auxillary channel to have it's GPIO pin switched (eg: aux1).
Return: none
testing($bool)
Used primarily internally, sets/gets whether we're in testing mode or not.
Parameters:
$boolOptional, Bool. 0 for production mode, and 1 for testing mode.
Return: Bool, whether we're in testing mode or not.
test_mock($bool)
This is for use internally when testing the App::RPi::EnvUI::Event module. Normally, the API mocks out items for testing, but in Event's case, the test file itself has to do the mocking.
Parameters:
$boolOptional, Bool. 0 to disable, 1 to enable.
Default: 1, enabled (the API will mock in test mode)
user($user)
Fetches a user's details.
Parameters:
$userMandatory, String. The username of the user to fetch details for.
Return: href, the hash reference containing user details per the 'user' database table.
ENVIRONMENT VARIABLES
SUPPRESS_WARN
Set this variable to a true value to suppress all warnings via a <$SIG{__WARN__}> handler. This is handy when running tests, when you don't need to know specific details about core workings.
Implemented in <API.pm>.
AUTHOR
Steve Bertrand, <steveb@cpan.org<gt>
LICENSE AND COPYRIGHT
Copyright 2017 Steve Bertrand.
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.