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:

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.

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.

format

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

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

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>