App::RPi::EnvUI::API - Core API abstraction class for the App::RPi::EnvUI web app
my $api = App::RPi::EnvUI::API->new; ... #FIXME: add a real example
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.
Instantiates a new core API object. Send any/all parameters in within hash format (eg: testing =\ 1)).
testing =\
Parameters:
config
Optional, String. Name of the configuration file to use. Very rarely required.
Default: config/envui.json
config/envui.json
testing
Optional, Bool. Send in 1 to enable testing, 0 to disable it.
1
0
Default: 0
test_mock
This 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_level
Optional, Integer. Send in a level of 0-7 to enable logging.
0-7
Default: -1 (logging disabled)
-1
log_file
Optional, 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.
STDOUT
Default: undef
undef
debug_sensor
Optional, Bool. Enable/disable debug print output from the RPi::DHT11 sensor code. Send in 1 to enable, and 0 to disable.
Default: 0 (off)
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.
$aux_id
Mandatory, String. The string name representation of the humidity auxillary. By default, this will be aux2.
aux2
$humidity
Mandatory: Integer. The integer value of the current humidity (typically supplied by the RPi::DHT11 hygrometer sensor.
RPi::DHT11
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):
%args
Optional (use for testing only!). Pass in a hash with the desired configuration parameters as found in the configuration file for light configuration.
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.
Mandatory, String. The string name representation of the temperature auxillary. By default, this will be aux1.
aux1
Checks whether a user is supplying the correct password.
$user
Mandatory, String. The user name to validate the password for.
$pw
Mandatory, String. The plain text password to verify.
Return: True (1) if successful, undef otherwise.
Retrieves from the database a hash reference that contains the details of a specific auxillary channel, and returns it.
Mandatory, String. The string name representation of the auxillary channel to retrieve (eg: aux1).
Returns: Hash reference with the auxillary channel details.
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.
Extracts the name/ID of a specific auxillary channel.
$aux
Mandatory, href. A hash reference as returned from a call to aux().
aux()
Return: String. The name/ID of the specified auxillary channel.
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.
Mandatory, String. The string name of an auxillary channel (eg: aux1).
$state
Optional, 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.
Associates a GPIO pin to a specific auxillary channel.
$pin
Optional, 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.
Sets/gets the state (ie. on/off) value of a specific auxillary channel's GPIO pin.
Optional, Bool. 0 to turn the pin off (LOW), or 1 to turn it on (HIGH).
LOW
HIGH
Return: Bool. Returns the current state of the aux pin.
Sets/gets the length of time an auxillary channel's GPIO pin has been HIGH (on). Mainly used to determine timers.
$time
Optional, output from time(). If sent in, we'll set the start time of a pin on event to this.
time()
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).
Sets/gets the currently loaded configuration file.
$conf_file
Optional, String. The name of a configuration file. This is only useful on instantiation of a new object.
Returns the currently loaded configuration file name.
Sets/gets the internal App::RPi::EnvUI::DB object. This method allows you to swap DB objects (and thereby DB handles) within separate processes.
$db_object
Optional, App::RPi::EnvUI::DB object instance.
Returns: The currently loaded DB object instance.
Enable/disable RPi::DHT11 sensor's debug print output.
$bool
Optional, Bool. 1 to enable debugging, 0 to disable.
Return: Bool. The current state of the sensor's debug state.
Default: False (0)
Sets/gets the current temperature and humidity pair.
All parameters are optional, but if one is sent in, both must be sent in.
$temp
Optional, Integer. The current temperature.
Optional, Integer. The current humidity .
Return: A hash reference in the format {temp = Int, humidity => Int}>
{temp =
Returns the string name of the humidity auxillary channel (default: aux2). Takes no parameters.
Returns the string name of the temperature auxillary channel (default: aux1). Takes no parameters.
Returns the string name of the light auxillary channel (default: aux3). Takes no parameters.
aux3
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.
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.
temp
humidity
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.
Returns as an integer, the current humidity level.
Returns as an integer, the current temperature level.
Sets in the database the values for lights-on and lights-off time.
Takes no parameters, there is no return.
Returns a pre-configured Logging::Simple object, ready to be cloned with its child() method.
child()
Sets/gets the log file for the internal logger.
$filename
Optional, 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.
Sets/gets the current debug logging level.
$level
Optional, Integer. Sets the logging level between 0-7.
Return: Integer, the current level.
Generates an SHA-1 hashed password.
Mandatory, String. A plain text string (the password).
Return: SHA-1 hashed password string.
Retrieves and returns the current temperature and humidity within an array of two integers.
Sets/gets the current hygrometer sensor object. This method is here so that for testing, we can send in mocked sensor objects.
$sensor
Optional, RPi::DHT11 object instance.
Return: The sensor object.
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().
action_light()
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.
Mandatory, String. The string name of the auxillary channel to have it's GPIO pin switched (eg: aux1).
Return: none
Used primarily internally, sets/gets whether we're in testing mode or not.
Optional, Bool. 0 for production mode, and 1 for testing mode.
Return: Bool, whether we're in testing mode or not.
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.
Event
Optional, Bool. 0 to disable, 1 to enable.
Default: 1, enabled (the API will mock in test mode)
Fetches a user's details.
Mandatory, String. The username of the user to fetch details for.
Return: href, the hash reference containing user details per the 'user' database table.
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.
<$SIG{__WARN__}
Implemented in <API.pm>.
<API.pm
Steve Bertrand, <steveb@cpan.org<gt>
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.
To install App::RPi::EnvUI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::RPi::EnvUI
CPAN shell
perl -MCPAN -e shell install App::RPi::EnvUI
For more information on module installation, please visit the detailed CPAN module installation guide.