NAME

Device::Chip::Sensor - declarations of sensor readings for Device::Chip

SYNOPSIS

   class Device::Chip::MySensorChip
      extends Device::Chip;

   use Device::Chip::Sensor -declare;

   ...

   declare_sensor voltage =>
      units     => "volts",
      precision => 3;

   async method read_voltage () {
      ...
   }

DESCRIPTION

This package provides some helper methods for describing metadata on Device::Chip drivers that provide sensor values. The resulting metadata helps to describe the quantities that the sensor chip can measure, and provides a consistent API for accessing them.

CHIP METHODS

When imported into a Device::Chip driver class using the -declare option the following methods are added to it.

list_sensors

   @sensors = $chip->list_sensors;

Returns a list of individual sensor objects. Each object represents a single sensor reading that can be measured.

OPTIONAL CHIP METHODS

The following methods may also be provided by the chip driver class if required. Callers should check they are implemented (e.g. with can) before attempting to call them.

initialize_sensors

   await $chip->initialize_sensors;

If the chip requires any special configuration changes, initial calibrations, startup delay, or other operations before the sensors are available then this method should perform it. It can presume that the application wishes to interact with the chip primarily via the sensors API, and thus if required it can presume particular settings to make this happen.

SENSOR DECLARATIONS

Sensor metadata is provided by the following function.

declare_sensor

   declare_sensor $name => %params;

Declares a new sensor object with the given name and parameters.

The following named parameters are recognised:

type => STRING

Optional. A string specifying what overall type of data is being returned. Normally this is gauge to indicate a quantity that is measured on every observation. A type of counter instead indicates that the value will be an integer giving the total number of times some event has happened - typically used to count interrupt events from chips.

A convenience function "declare_sensor_counter" exists for making counters.

units => STRING

A string describing the units in which the value is returned. This should be an empty string for purely abstract counting sensors, or else describe the measured quantities in physical units (such as volts, seconds, metres, Hz, ...)

precision => INT

The number of decimal places of floating-point accuracy that values should be printed with. This should be 0 for integer readings.

method => STRING or CODE

Optional string or code reference giving the method on the main chip object to call to obtain a new reading of this sensor's current value. If not provided a default will be created by prefixing "read_" onto the sensor name.

sanity_bounds => ARRAY[ 2 * NUM ]

Since version 0.23.

Optional bounding values to sanity-test reported readings. If a reading is obtained that is lower than the first value or higher than the second, it is declared to be out of bounds by the "read" method. Either bound may be set to undef to ignore that setting. For example, setting just a lower bound of zero ensures that any negative values that are obtained are considered out of the valid range.

declare_sensor_counter

   declare_sensor_counter $name => %params;

Declares a sensor of the counter type. This will pass undef for the units and 0 for precision.

SENSOR METHODS

Each returned sensor object provides the following methods.

name

units

precision

   $name = $sensor->name;

   $units = $sensor->units;

   $prec = $sensor->precision;

Metadata fields from the sensor's declaration.

chip

   $chip = $sensor->chip;

The Device::Chip instance this sensor is a part of.

read

   $value = await $sensor->read;

Performs an actual read operation on the sensor chip to return the currently measured value.

This method always returns a single scalar value, even if the underlying method on the sensor chip returned more than one.

If the value obtained from the sensor is outside of the sanity-check bounds then an exception is thrown instead.

format

   $string = $sensor->format( $value );

Returns a string by formatting an observed value to the required precision.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Device::Chip

perl -MCPAN -e shell
install Device::Chip