NAME
App::Device::Chip::sensor - Base class to build
Device::Chip::Sensor-based applications on
SYNOPSIS
#!/usr/bin/perl
use v5.26;
use Object::Pad;
use Future::AsyncAwait;
class App extends App::Device::Chip::sensor
{
method output_readings ( $now, $sensors, $values )
{
print "At time $now, we have some sensor values...\n";
}
}
await App->new->parse_argv->run;
DESCRIPTION
This module provides a base class to assist in writing applications
that process data periodically from one or more Device::Chip-based
sensors, via the Device::Chip::Sensor interface. A typical program
using this module would derive a subclass from it, provide the
remaining methods as necessary, and eventually call the "run" method to
start the application.
COMMANDLINE OPTIONS
The following commandline options are recognised by the base class and
may be used in addition to any defined by the actual application logic.
* --blib, -b
Uses the blib module to add additional paths into @INC to search for
more Perl modules. May be useful when testing chip drivers under
development without needing to install them.
* --interval, -i TIME
Specifies the time, in seconds, between every round of collecting
sensor readings and invoking the "output_readings" method.
Defaults to 10 seconds.
* --adapter, -A STR
Adapter configuration string to pass to "new_from_description" in
Device::Chip::Adapter to construct the chip adapter used for
communication with the actual chip hardware.
* --filter, -F STR
Specifies the kind of filtering to apply to gauge values. See
"FILTERING" for more detail.
* --mid3, -m
Enable "middle-of-3" filtering of gauge values, to reduce sensor
noise from unreliable sensors. This is equivalent to setting -F mid3.
* --best-effort, -B
Enables best-effort mode, which causes failures of sensor readings to
be ignored, reporting undef instead. In this mode, the on_sensor_fail
method may be invoked for failures; it can further refine what the
behaviour should be.
PROVIDED METHODS
The following methods are provided on the base class, intended for
subclasses or applications to invoke.
parse_argv
$app->parse_argv();
$app->parse_argv( \@argv );
Provides a list of commandline arguments for parsing, either from a
given array reference or defaulting to the process @ARGV if not
supplied.
This uses "OPTSPEC" to collect the defined arguments, whose references
should handle the results.
add_chip
$app->add_chip( %config );
Since version 0.05.
Adds a new chip to the stored configuration, as if it had been given as
a commandline argument. Takes the following named arguments:
type => STR
Required string that gives the name of the chip class.
adapter => Device::Chip::Adapter
Required Device::Chip::Adapter instance.
mountopts => HASH
Optional HASH reference containing extra mount parameters.
config => HASH
Optional HASH reference containing extra chip configuration to set up
using the configure method once mounted.
chips
@chips = await $app->chips;
An asynchronous memoized lazy accessor for the list of Device::Chip
instances, whose class names are taken from the remaining commandline
arguments after the options are parsed.
sensors
@sensors = await $app->sensors;
An asynchronous memoized lazy accessor for the list of
Device::Chip::Sensor instances of each of the configured chips (from
the "chips" method).
run
await $app->run;
An asynchronous method which performs the actual run loop of the sensor
application. This implements the main application logic, of regular
collection of values from all of the sensor instances and reporting
them to the "output_readings" method.
In normal circumstances the Future instance returned by this method
would remain pending for the lifetime of the program, and not complete.
For an application that has nothing else to perform concurrently it can
simply await this future to run the logic. If it has other logic to
perform as well it could combine this with other futures using a
Future->needs_all or similar techniques.
print_readings
$app->print_readings( $sensors, $values );
Prints the sensor names and current readings in a human-readable format
to the currently-selected output handle (usually STDOUT).
REQUIRED METHODS
This base class itself is incomplete, requiring the following methods
to be provided by an implementing subclass to contain the actual
application logic.
output_readings
$app->output_readings( $now, $sensors, $values );
This method is invoked regularly by the "run" method, to provide the
application with the latest round of sensor readings. It is passed the
current UNIX epoch timestamp as $now, an array reference containing the
individual Device::Chip::Sensor instances as $sensors, and a congruent
array reference containing the most recent readings taken from them, as
plain numbers.
The application should put the bulk of its processing logic in here,
for example writing the values to some sort of file or database,
displaying them in some form, or whatever else the application is
supposed to do.
OVERRIDABLE METHODS
The base class provides the following methods, but it is expected that
applications may wish to override them to customise the logic contained
in them.
If using Object::Pad to do so, don't forget to provide the :override
method attribute.
OPTSPEC
%optspec = $app->OPTSPEC;
This method is invoked by the "parse_argv" method to construct a
definition of the commandline options understood by the program. These
are returned in a key/value list to be processed by Getopt::Long. If
the application wishes to parse additional arguments it should override
this method, call the superclass version, and append any extra argument
specifications it requires.
As this is invoked as a regular instance method, a convenient way to
store the parsed values is to pass references to instance slot
variables created by the Object::Pad field keyword:
field $_title;
field $_bgcol = "#cccccc";
method OPTSPEC :override
{
return ( $self->SUPER::OPTSPEC,
'title=s' => \$_title,
'background-color=s' => \$_bgcol,
);
}
after_sensors
await $app->after_sensors( @sensors );
This method is invoked once on startup by the "run" method, after it
has configured the chip adapter and chips and obtained their individual
sensor instances. The application may wish to perform one-time startup
tasks in here, such as creating database files with knowledge of the
specific sensor data types, or other such behaviours.
on_sensor_ok
$app->on_sensor_ok( $sensor );
This method is invoked in --best-effort mode after a successful reading
from sensor; typically this is used to clear a failure state.
The default implementation does nothing.
on_sensor_fail
$app->on_sensor_fail( $sensor, $failure );
This method is invoked in --best-effort mode after a failure of the
given sensor. The caught exception is passed as $failure.
The default implementation prints this as a warning using the core
warn() function.
FILTERING
The --filter setting accepts the following filter names
null
No filtering is applied. Each sensor reading is reported as it stands.
midn
The most recent n values are sorted, and the middle of these is
reported. To be well-behaved, n should be an odd number. (mid3, mid5,
mid7, etc...)
ravgn
Recursive average with weighting of 2 ** -n.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>