Device/Chip/Sensor.pm

filter: Statementstmt 97.9% 94 / 96 Branchbran 71.4% 10 / 14 Conditioncond 90.9% 10 / 11 MC/DCmcdc 60.0% 3 / 5 Subroutinesub 92.3% 24 / 26 Podpod 77.7% 7 / 9 totaltotal 91.9% 148 / 161 CC 12 SCAR 8.1
CC
12
Cov
94%
read
6.0
declare_into
3.0
__ANON__
2.5
CRAP 2.2
« Device/Chip.pm ↑ Summary Device/Chip/ProtocolBase/SPI.pm »
1 # You may distribute under the terms of either the GNU General Public License
2 # or the Artistic License (the same terms as Perl itself)
3 #
4 # (C) Paul Evans, 2020-2026 -- leonerd@leonerd.org.uk
5  
6 2 ▶use v5.26;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 2 ▶use Object::Pad 0.800 ':experimental(mop adjust_params)';
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 package Device::Chip::Sensor 0.27;
11  
12 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 2 ▶use meta;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 2 ▶use experimental 'signatures';
Subroutine BEGIN: called CC=1 SCAR=0.0
17 2 ▶no warnings 'meta::experimental';
Subroutine BEGIN: called CC=1 SCAR=0.0
18  
19 2 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
20  
21 =head1 NAME
22  
23 C<Device::Chip::Sensor> - declarations of sensor readings for C<Device::Chip>
24  
25 =head1 SYNOPSIS
26  
27 =for highlighter language=perl
28  
29 class Device::Chip::MySensorChip
30 :isa(Device::Chip);
31  
32 use Device::Chip::Sensor -declare;
33  
34 ...
35  
36 declare_sensor voltage =>
37 units => "volts",
38 precision => 3;
39  
40 async method read_voltage () {
41 ...
42 }
43  
44 =head1 DESCRIPTION
45  
46 This package provides some helper methods for describing metadata on
47 L<Device::Chip> drivers that provide sensor values. The resulting metadata
48 helps to describe the quantities that the sensor chip can measure, and
49 provides a consistent API for accessing them.
50  
51 =cut
52  
53 2 my %SENSORS_FOR_CLASS;
54  
55 =head1 CHIP METHODS
56  
57 When imported into a C<Device::Chip> driver class using the C<-declare> option
58 the following methods are added to it.
59  
60 =cut
61  
62 =head2 list_sensors
63  
64 @sensors = $chip->list_sensors;
65  
66 Returns a list of individual sensor objects. Each object represents a single
67 sensor reading that can be measured.
68  
69 I<Since version 0.27> sensors are inherited from superclasses, with sensors
70 declared by base classes listed first, before sensors added in subclasses.
71  
72 =head1 OPTIONAL CHIP METHODS
73  
74 The following methods may also be provided by the chip driver class if
75 required. Callers should check they are implemented (e.g. with C<can>) before
76 attempting to call them.
77  
78 =head2 initialize_sensors
79  
80 await $chip->initialize_sensors;
81  
82 If the chip requires any special configuration changes, initial calibrations,
83 startup delay, or other operations before the sensors are available then this
84 method should perform it. It can presume that the application wishes to
85 interact with the chip primarily via the sensors API, and thus if required it
86 can presume particular settings to make this happen.
87  
88 =head1 SENSOR DECLARATIONS
89  
90 Sensor metadata is provided by the following function.
91  
92 =head2 declare_sensor
93  
94 declare_sensor $name => %params;
95  
96 Declares a new sensor object with the given name and parameters.
97  
98 The following named parameters are recognised:
99  
100 =over 4
101  
102 =item type => STRING
103  
104 Optional. A string specifying what overall type of data is being returned.
105 Normally this is C<gauge> to indicate a quantity that is measured on every
106 observation. A type of C<counter> instead indicates that the value will be an
107 integer giving the total number of times some event has happened - typically
108 used to count interrupt events from chips.
109  
110 A convenience function L</declare_sensor_counter> exists for making counters.
111  
112 =item units => STRING
113  
114 A string describing the units in which the value is returned. This should be
115 an empty string for purely abstract counting sensors, or else describe the
116 measured quantities in physical units (such as C<volts>, C<seconds>,
117 C<metres>, C<Hz>, ...)
118  
119 =item precision => INT
120  
121 The number of decimal places of floating-point accuracy that values should
122 be printed with. This should be 0 for integer readings.
123  
124 =item method => STRING or CODE
125  
126 Optional string or code reference giving the method on the main chip object to
127 call to obtain a new reading of this sensor's current value. If not provided a
128 default will be created by prefixing C<"read_"> onto the sensor name.
129  
130 =item sanity_bounds => ARRAY[ 2 * NUM ]
131  
132 I<Since version 0.23.>
133  
134 Optional bounding values to sanity-test reported readings. If a reading is
135 obtained that is lower than the first value or higher than the second, it is
136 declared to be out of bounds by the L</read> method. Either bound may be set
137 to C<undef> to ignore that setting. For example, setting just a lower bound of
138 zero ensures that any negative values that are obtained are considered out of
139 the valid range.
140  
141 =back
142  
143 =head2 declare_sensor_counter
144  
145 declare_sensor_counter $name => %params;
146  
147 Declares a sensor of the C<counter> type. This will pass C<undef> for the
148 units and 0 for precision.
149  
150 =cut
151  
152 3 ▶sub import ( @opts )
Subroutine import: called CC=2 SCAR=7.1
153 {
154 3 my $caller = caller;
155 3 ▶ declare_into( $caller ) if grep { $_ eq "-declare" } @opts;
Branch: 1 branch
BranchTrueFalseTotal
if grep {$_ eq "-declare";} @opts 3 0 3
156 }
157  
158 0 ▶sub unimport ( @opts )
Subroutine unimport: not called CC=1 SCAR=6.9
159 {
160 0 croak "This module cannot be unimported";
161 }
162  
163 3 ▶sub declare_into ( $caller )
Subroutine declare_into: called CC=3 SCAR=11.1
Pod undocumented
164 {
165 3 my $classmeta = Object::Pad::MOP::Class->for_class( $caller );
166  
167 3 ▶ my $sensors = $SENSORS_FOR_CLASS{$classmeta->name} //= [];
Condition50%1/2
$SENSORS_FOR_CLASS{$classmeta->name} //= []
l!l
03
MC/DC0%0/1
$SENSORS_FOR_CLASS{$classmeta->name} //= []
$SENSORS_FOR_CLASS{$classmeta->name}
Truth table50%1/2
A
A= $SENSORS_FOR_CLASS{$classmeta->name}
Aresult
11
00
168  
169 3 my $superclass = ( map { $_->name } $classmeta->superclasses )[0];
170 3 ▶ undef $superclass unless exists $SENSORS_FOR_CLASS{$superclass};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $SENSORS_FOR_CLASS{$superclass} 2 1 3
171  
172 0 ▶ $classmeta->add_method( _list_metasensors => sub ( $self ) {
Subroutine __ANON__: not called CC=2 SCAR=9.2
Subroutine _list_metasensors: called CC=2 SCAR=9.2
173 0 ▶ return ( $superclass ? $superclass->_list_metasensors : () ),
Branch: 2 branches
BranchTrueFalseTotal
$superclass ? : 0 0 0
$superclass ? : 1 2 3
174 $sensors->@*;
175 3 } );
176  
177 2 ▶ $classmeta->add_method( list_sensors => sub ( $self ) {
Subroutine __ANON__: called CC=1 SCAR=0.0
178 2 return map { $_->bind( $self ) } $self->_list_metasensors;
179 3 } );
180  
181 7 ▶ my $declare = sub ( $name, %params ) {
Subroutine __ANON__: called CC=1 SCAR=0.0
182 7 push $sensors->@*, Device::Chip::Sensor->new(
183 name => $name,
184 %params,
185 );
186 3 };
187  
188 3 my $metapkg = meta::package->get( $caller );
189  
190 3 $metapkg->add_named_sub( declare_sensor => $declare );
191 1 ▶ $metapkg->add_named_sub( declare_sensor_counter => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
192 1 $declare->( @_, type => "counter", units => undef, precision => 0 );
193 3 } );
194 }
195  
196 class Device::Chip::Sensor;
197  
198 2 ▶use Future::AsyncAwait 0.38;
Subroutine BEGIN: called CC=1 SCAR=0.0
199  
200 =head1 SENSOR METHODS
201  
202 Each returned sensor object provides the following methods.
203  
204 =head2 name
205  
206 =head2 units
207  
208 =head2 precision
209  
210 $name = $sensor->name;
211  
212 $units = $sensor->units;
213  
214 $prec = $sensor->precision;
215  
216 Metadata fields from the sensor's declaration.
217  
218 =head2 chip
219  
220 $chip = $sensor->chip;
221  
222 The L<Device::Chip> instance this sensor is a part of.
223  
224 =cut
225  
226 2 my %TYPES = (
227 gauge => 1,
228 counter => 1,
229 );
230  
231 2 field $_type :reader :param = "gauge";
232 4 ▶field $_name :reader :param;
Subroutine name: called CC=1 SCAR=0.0
Subroutine type: called CC=1 SCAR=0.0
Pod documented
Pod documented
233 field $_units :reader :param = undef;
234 1 ▶field $_precision :reader :param = 0;
Subroutine units: called CC=1 SCAR=0.0
Pod documented
235  
236 1 ▶field $_lbound;
Subroutine precision: called CC=1 SCAR=0.0
Pod documented
237 2 field $_ubound;
238  
239 field $_method :param = undef;
240  
241 2 field $_chip :reader :param = undef;
242  
243 1 ▶ADJUST
Subroutine chip: called CC=1 SCAR=0.0
Pod documented
244 {
245 $TYPES{$_type} or
246 croak "Unrecognised sensor type '$_type'";
247  
248 $_method //= "read_$_name";
249 }
250  
251 2 ADJUST :params ( :$sanity_bounds = [] )
252 {
253 ( $_lbound, $_ubound ) = $sanity_bounds->@*;
254 }
255  
256 7 ▶method bind ( $chip )
Subroutine bind: called CC=1 SCAR=0.0
Pod undocumented
257 {
258 7 return Device::Chip::Sensor->new(
259 chip => $chip,
260  
261 type => $_type,
262 name => $_name,
263 units => $_units,
264 precision => $_precision,
265 method => $_method,
266 sanity_bounds => [ $_lbound, $_ubound ],
267 );
268 2 }
269  
270 =head2 read
271  
272 $value = await $sensor->read;
273  
274 Performs an actual read operation on the sensor chip to return the currently
275 measured value.
276  
277 This method always returns a single scalar value, even if the underlying
278 method on the sensor chip returned more than one.
279  
280 If the value obtained from the sensor is outside of the sanity-check bounds
281 then an exception is thrown instead.
282  
283 =cut
284  
285 6 ▶async method read ()
Subroutine read: called CC=6 SCAR=17.9
Pod documented
286 6 {
287 6 ▶ defined( my $value = scalar await $_chip->$_method() )
Branch: 1 branch
BranchTrueFalseTotal
defined(my $value = scalar <custom op await>) or return undef 6 0 6
288 or return undef;
289  
290 6 ▶ if( defined $_lbound and $value < $_lbound or
Branch: 1 branch
BranchTrueFalseTotal
if (defined $_lbound and $value < $_lbound or defined $_ubound and $value > $_ubound) 2 4 6
Condition100%9/9
defined $_lbound and $value < $_lbound or defined $_ubound and $value > $_ubound
l!l&&r!l&&!r
114
defined $_lbound and $value < $_lbound
!ll&&!rl&&r
231
defined $_ubound and $value > $_ubound
!ll&&!rl&&r
221
MC/DC75%3/4
defined $_lbound and $value < $_lbound or defined $_ubound and $value > $_ubound
defined $_lbound $value < $_lbound defined $_ubound $value > $_ubound
Truth table57%4/7
A and B or C and D
A= defined $_lboundB= $value < $_lboundC= defined $_uboundD= $value > $_ubound
ABCDresult
11XX1
0X111
10111
0X0X0
0X100
100X0
10100
291 defined $_ubound and $value > $_ubound ) {
292 2 die sprintf "Reading %s is out of range\n", $self->format( $value );
293 }
294  
295 4 return $value;
296 2 }
297  
298 =head2 format
299  
300 $string = $sensor->format( $value );
301  
302 Returns a string by formatting an observed value to the required precision.
303  
304 =cut
305  
306 4 ▶method format ( $value )
Subroutine format: called CC=2 SCAR=6.9
Pod documented
307 {
308 4 ▶ return undef if !defined $value;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $value 1 3 4
309 3 return sprintf "%.*f", $_precision, $value;
310 2 }
311  
312 =head1 AUTHOR
313  
314 Paul Evans <leonerd@leonerd.org.uk>
315  
316 =cut
317  
318 2 0x55AA;
« Device/Chip.pm ↑ Summary Device/Chip/ProtocolBase/SPI.pm »