Sensor class

The "Sensor" class is used for all sensor-level operations - waking, sleeping, and taking measurements.

A sensor is some sort of device that is capable of taking one or more measurements using some sort of method. Most often we can think of these as probes or other instruments that can give back information about the world around them. Sensors can usually be given power or have that power cut. They may be awoken or activated and then returned to a sleeping/low power use state. The may need to be asked to begin a single reading or they may continuously return data. They must be capable of returning the value of their readings to a logger of some type.

Derived classes

class AOSongAM2315: The Sensor sub-class for the AOSong AM2315.
class AOSongDHT: The Sensor sub-class for the AOSong digital-output relative humidity and temperature sensor modules.
class AlphasenseCO2: The Sensor sub-class for the [Alphasense IRC-A1 CO2](Alphasense IRC-A1 CO2) sensor.
class AnalogElecConductivity: Class for the analog [Electrical Conductivity monitor](Conductivity via Analog Electrical Resistance)
class ApogeeSQ212: The Sensor sub-class for the Apogee SQ-212 sensor.
class AtlasParent: A parent class for Atlas EZO circuits and sensors.
class BoschBME280: The Sensor sub-class for the Bosch BME280.
class BoschBMP3xx: The Sensor sub-class for the Bosch BMP3xx.
class CampbellOBS3: The Sensor sub-class for the Campbell OBS3 analog turbidity sensor.
class EverlightALSPT19: The Sensor sub-class for the Everlight ALS-PT19.
class FreescaleMPL115A2: The Sensor sub-class for the Freescale Semiconductor MPL115A2 sensor.
class GroPointParent: The Sensor sub-class for all the GroPoint sensors.
class KellerParent: The Sensor sub-class for all Keller water level sensors.
class MaxBotixSonar: The Sensor sub-class for the MaxBotix ultrasonic range finders.
class MaximDS18: The Sensor sub-class for the DS18 one-wire temperature sensors.
class MaximDS3231: The Sensor sub-class for the Maxim DS3231 when used as a low-accuracy temperature sensor.
class MeaSpecMS5803: The Sensor sub-class for the Measurement Specialties MS5803 sensor.
class PaleoTerraRedox: The Sensor sub-class for the PaleoTerra redox sensor.
class ProcessorStats: The main class to use the main processor (MCU) as a sensor.
class RainCounterI2C: The Sensor sub-class for the Arduino-based external tipping bucket counter.
class SDI12Sensors: The main class for SDI-12 Sensors.
class SensirionSHT4x: The Sensor sub-class for the Sensirion SHT4x.
class TIADS1x15: The Sensor sub-class for the external votlage as measured by TI ADS1115 or ADS1015.
class TIINA219: The Sensor sub-class for the TexasInstruments INA219 sensor.
class TallyCounterI2C: The Sensor sub-class for the Tally Counter I2C.
class TurnerCyclops: The Sensor sub-class for the Turner Cyclops-7F submersible fluorometer.
class TurnerTurbidityPlus: The Sensor sub-class for the Turner Turbidity Plus turbiditysensor".
class YosemitechParent: The Sensor sub-class for all the Yosemitech sensors.

Constructors, destructors, conversion operators

Sensor(const char* sensorName = "Unknown", const uint8_t totalReturnedValues = 1, uint32_t warmUpTime_ms = 0, uint32_t stabilizationTime_ms = 0, uint32_t measurementTime_ms = 0, int8_t powerPin = -1, int8_t dataPin = -1, uint8_t measurementsToAverage = 1, uint8_t incCalcValues = 0): Construct a new Sensor object.
Sensor(const Sensor& copy_from_me) deleted: Dis-allowed constructor for a new Sensor object from a copy of another Sensor object - the deleted copy constructor.
~Sensor() virtual: Destroy the Sensor object - no action taken.

Public functions

Sensor& operator=(const Sensor& copy_from_me) -> Sensor& deleted: Dis-allowed assignment of one Sensor object to another - the deleted assignment operator.
String getSensorLocation(void) -> String virtual: Get the pin or connection location between the mcu and the sensor.
String getSensorName(void) -> String virtual: Get the name of the sensor.
String getSensorNameAndLocation(void) -> String: Concatentate and returns the name and location of the sensor.
int8_t getPowerPin(void) -> int8_t virtual: Get the pin number controlling sensor power.
void setNumberMeasurementsToAverage(uint8_t nReadings): Set the number measurements to average.
uint8_t getNumberMeasurementsToAverage(void) -> uint8_t: Get the number of measurements to average.
uint8_t getStatus(void) -> uint8_t: Get the 8-bit code for the current status of the sensor.
bool setup(void) -> bool virtual: Do any one-time preparations needed before the sensor will be able to take readings.
bool update(void) -> bool virtual: Update the sensor's values.
void powerUp(void) virtual: Turn on the sensor power, if applicable.
void powerDown(void) virtual: Turn off the sensor power, if applicable.
bool wake(void) -> bool virtual: Wake the sensor up, if necessary. Do whatever it takes to get a sensor in the proper state to begin a measurement.
bool sleep(void) -> bool virtual: Puts the sensor to sleep, if necessary.
bool startSingleMeasurement(void) -> bool virtual: Tell the sensor to start a single measurement, if needed.
bool addSingleMeasurementResult(void) -> bool pure virtual: Get the results from a single measurement.
void clearValues(): Clear the values array - that is, sets all values to -9999.
void verifyAndAddMeasurementResult(uint8_t resultNumber, float resultValue): Verify that a measurement is OK (ie, not -9999) before adding it to the result array.
void verifyAndAddMeasurementResult(uint8_t resultNumber, int16_t resultValue): Verify that a measurement is OK (ie, not -9999) before adding it to the result array.
void verifyAndAddMeasurementResult(uint8_t resultNumber, int32_t resultValue): Average the results of all measurements by dividing the sum of all measurements by the number of measurements taken.
void averageMeasurements(void): Average the results of all measurements by dividing the sum of all measurements by the number of measurements taken.
void registerVariable(int sensorVarNum, Variable* var): Register a variable object to a sensor.
void notifyVariables(void): Notify attached variables of new values.
bool checkPowerOn(bool debug = false) -> bool: Check if the _powerPin is currently high.
bool isWarmedUp(bool debug = false) -> bool virtual: Check whether or not enough time has passed between the sensor receiving power and being ready to respond to logger commands.
void waitForWarmUp(void): Hold all further program execution until this sensor is ready to receive commands.
bool isStable(bool debug = false) -> bool virtual: Check whether or not enough time has passed between the sensor being awoken/activated and being ready to output stable values.
void waitForStability(void): Hold all further program execution until this sensor is reporting stable values.
bool isMeasurementComplete(bool debug = false) -> bool virtual: Check whether or not enough time has passed between when the sensor was asked to take a single measurement and when that measurement is expected to be complete.
void waitForMeasurementCompletion(void): Hold all further program execution until this sensor is has finished the current measurement.

Public variables

float sensorValues: The array of result values for each sensor.

Protected variables

int8_t _dataPin: Digital pin number on the mcu receiving sensor data.
int8_t _powerPin: Digital pin number on the mcu controlling sensor power.
const char* _sensorName: The sensor name.
const uint8_t _numReturnedValues: The number of values the sensor is capable of reporting.
uint8_t _measurementsToAverage: The number of measurements from the sensor to average.
uint8_t _incCalcValues: The number of included calculated variables from the sensor, if any.
uint8_t numberGoodMeasurementsMade: Array with the number of valid measurement values taken by the sensor in the current update cycle.
uint32_t _warmUpTime_ms: The time needed from the when a sensor has power until it's ready to talk.
uint32_t _millisPowerOn: The processor elapsed time when the power was turned on for the sensor.
uint32_t _stabilizationTime_ms: The time needed from the when a sensor is activated until the readings are stable.
uint32_t _millisSensorActivated: The processor elapsed time when the sensor was activiated - ie, when the wake() function was run.
uint32_t _measurementTime_ms: The time needed from the when a sensor is told to take a single reading until that reading is expected to be complete.
uint32_t _millisMeasurementRequested: The processor elapsed time when a measuremnt was started - ie, when the startSingleMeasurement() function was run.
uint8_t _sensorStatus: An 8-bit code for the sensor status.
Variable* variables: An array for each sensor containing pointers to the variable objects tied to that sensor. The MAX_NUMBER_VARS cannot be determined on a per-sensor basis, because of the way memory is used on an Arduino. It must be defined once for the whole class.

Function documentation

Sensor::Sensor(const char* sensorName = "Unknown", const uint8_t totalReturnedValues = 1, uint32_t warmUpTime_ms = 0, uint32_t stabilizationTime_ms = 0, uint32_t measurementTime_ms = 0, int8_t powerPin = -1, int8_t dataPin = -1, uint8_t measurementsToAverage = 1, uint8_t incCalcValues = 0)

Construct a new Sensor object.

Parameters
sensorName	The name of the sensor. Defaults to "Unknown".
totalReturnedValues	The total number of value results (raw or calculated internally) returned by the sensor. Defaults to 1.
warmUpTime_ms	The time in ms between when the sensor is powered on and when it is ready to receive a wake command. Defaults to 0.
stabilizationTime_ms	The time in ms between when the sensor receives a wake command and when it is able to return stable values. Defaults to 0.
measurementTime_ms	The time in ms between when a measurement is started and when the result value is available. Defaults to 0.
powerPin	The pin on the mcu controlling power to the sensor Use -1 if it is continuously powered.
dataPin	The pin on the mcu receiving data from the sensor. Defaults to -1.
measurementsToAverage	The number of measurements to take and average before giving a "final" result from the sensor; optional with a default value of 1.
incCalcValues	The number of included calculated variables from the sensor, if any. These are used for values that we would always calculate for a sensor and depend only on the raw results of that single sensor; optional with a default value of 0.

Sensor::Sensor(const Sensor& copy_from_me) deleted

Dis-allowed constructor for a new Sensor object from a copy of another Sensor object - the deleted copy constructor.

Parameters
copy_from_me	The Sensor object to copy.

The copy constructor is explicitly deleted. Sensor objects should not (and here cannot) be copied to avoid confusion over which sensor object specific variables are tied to.

Sensor& Sensor::operator=(const Sensor& copy_from_me) deleted

Dis-allowed assignment of one Sensor object to another - the deleted assignment operator.

The assignment operator is explicitly deleted. Sensor objects should not (and here cannot) be assigned to each other to avoid confusion over which sensor object specific variables are tied to.

String Sensor::getSensorLocation(void) virtual

Get the pin or connection location between the mcu and the sensor.

Returns	String Text describing how the sensor is attached to the mcu.

String Sensor::getSensorName(void) virtual

Get the name of the sensor.

Returns	String The sensor name as given in the constructor.

String Sensor::getSensorNameAndLocation(void)

Concatentate and returns the name and location of the sensor.

Returns	String A concatenation of the sensor name and its "location" how it is connected to the mcu.

Returns

String

A concatenation of the sensor name and its "location"

how it is connected to the mcu.

int8_t Sensor::getPowerPin(void) virtual

Get the pin number controlling sensor power.

Returns	int8_t The pin on the mcu controlling power to the sensor.

void Sensor::setNumberMeasurementsToAverage(uint8_t nReadings)

Set the number measurements to average.

Parameters
nReadings	The number of readings to take and average to create a result from the sensor. Overrides any value given in the constructor.

This will become the number of readings actually taken by a sensor prior to data averaging. Any "bad" (-9999) values returned by the sensor will not be included in the final averaging. This means that the actual number of "good" values that are averaged may be less than what was requested.

uint8_t Sensor::getNumberMeasurementsToAverage(void)

Get the number of measurements to average.

Returns	uint8_t The number of readings to take and average to create a result from the sensor.

uint8_t Sensor::getStatus(void)

Get the 8-bit code for the current status of the sensor.

Returns	uint8_t The status as a uint8_t.

Bit 0

0 => Has NOT been successfully set up
1 => Has been setup

Bit 1

0 => No attempt made to power sensor
1 => Attempt made to power sensor

Bit 2

0 => Power up attampt failed
1 => Power up attempt succeeded
Use the isWarmedUp() function to check if enough time has passed to be ready for sensor communication.

Bit 3

0 => Activation/wake attempt made
1 => No activation/wake attempt made
check _millisSensorActivated or bit 4 to see if wake() attempt was successful
a failed activation attempt will give _millisSensorActivated = 0

Bit 4

0 => Wake/Activate failed
1 => Is awake/actively measuring
Use the isStable() function to check if enough time has passed to begin a measurement.

Bit 5

0 => Start measurement requested attempt made
1 => No measurements have been requested
check _millisMeasurementRequested or bit 6 to see if startSingleMeasurement() attempt was successful
a failed request attempt will give _millisMeasurementRequested = 0

Bit 6

0 => Measurement start failed
1 => Measurement attempt succeeded
Use the isMeasurementComplete() to check if enough time has passed for a measurement to have been completed.

Bit 7

0 => No known errors
1 => Some sort of error has occurred

bool Sensor::setup(void) virtual

Do any one-time preparations needed before the sensor will be able to take readings.

Returns	bool True if the setup was successful.

This sets the pin modes of the _powerPin and _dataPin, updates _sensorStatus, and returns true.

bool Sensor::update(void) virtual

Update the sensor's values.

Returns	bool True if all steps of the sensor update completed successfully.

For digital sensors with a single information return, this only needs to be called once for each sensor, even if there are multiple variable subclasses for the sensor.

In general, the update function clears the value results array, powers the sensor, wakes or activates it, tells it one or more times to a start measurement and get the result, averages all the values, notifies the attached variables that new values are available, puts the sensor back to sleep (if it had been asleep) and powers the sensor down (if it had been unpowered). All possible waits are included in this function. To get new results from a single sensor, this is the function that should be used. To work with many sensors together, use the VariableArray class which optimizes the timing and waits for many sensors working together.

void Sensor::powerUp(void) virtual

Turn on the sensor power, if applicable.

Generally this is done by setting the _powerPin HIGH. Also sets the _millisPowerOn timestamp and updates the _sensorStatus.

void Sensor::powerDown(void) virtual

Turn off the sensor power, if applicable.

Generally this is done by setting the _powerPin LOW. Also un-sets the _millisPowerOn timestamp (sets _millisPowerOn to 0) and updates the _sensorStatus.

bool Sensor::wake(void) virtual

Wake the sensor up, if necessary. Do whatever it takes to get a sensor in the proper state to begin a measurement.

Returns	bool True if the wake function completed successfully.

Verifies that the power is on and updates the _sensorStatus. This also sets the _millisSensorActivated timestamp.

bool Sensor::sleep(void) virtual

Puts the sensor to sleep, if necessary.

Returns	bool True if the sleep function completed successfully.

Does not take any action if not necessary.

bool Sensor::startSingleMeasurement(void) virtual

Tell the sensor to start a single measurement, if needed.

Returns	bool True if the start measurement function completed successfully.

This also sets the _millisMeasurementRequested timestamp and updates the _sensorStatus.

bool Sensor::addSingleMeasurementResult(void) pure virtual

Get the results from a single measurement.

Returns	bool True if the function completed successfully.

This asks the sensor for a new result, verifies that it passes sanity range checks, and then adds the value to the result array.

This also un-sets the _millisMeasurementRequested timestamp (sets _millisMeasurementRequested to 0) and updates the _sensorStatus.

void Sensor::verifyAndAddMeasurementResult(uint8_t resultNumber, float resultValue)

Verify that a measurement is OK (ie, not -9999) before adding it to the result array.

Parameters
resultNumber	The position of the result within the result array.
resultValue	The value of the result.

void Sensor::verifyAndAddMeasurementResult(uint8_t resultNumber, int16_t resultValue)

Verify that a measurement is OK (ie, not -9999) before adding it to the result array.

Parameters
resultNumber	The position of the result within the result array.
resultValue	The value of the result.

void Sensor::verifyAndAddMeasurementResult(uint8_t resultNumber, int32_t resultValue)

Average the results of all measurements by dividing the sum of all measurements by the number of measurements taken.

Parameters
resultNumber	The position of the result within the result array.
resultValue	The value of the result.

void Sensor::registerVariable(int sensorVarNum, Variable* var)

Parameters
sensorVarNum	The position the variable result holds in the variable result array.
var	A ponter to the Variable object.

bool Sensor::checkPowerOn(bool debug = false)

Check if the _powerPin is currently high.

Parameters
debug	True to output the result to the debugging Serial
Returns	bool True indicates the _powerPin is currently `HIGH`.

bool Sensor::isWarmedUp(bool debug = false) virtual

Check whether or not enough time has passed between the sensor receiving power and being ready to respond to logger commands.

Parameters
debug	True to output the result to the debugging Serial
Returns	bool True indicates that enough time has passed that the sensor should be ready to respond to commands.

bool Sensor::isStable(bool debug = false) virtual

Check whether or not enough time has passed between the sensor being awoken/activated and being ready to output stable values.

Parameters
debug	True to output the result to the debugging Serial
Returns	bool True indicates that enough time has passed that the sensor should have stabilized.

bool Sensor::isMeasurementComplete(bool debug = false) virtual

Check whether or not enough time has passed between when the sensor was asked to take a single measurement and when that measurement is expected to be complete.

Parameters
debug	True to output the result to the debugging Serial
Returns	bool True indicates that enough time has passed the measurement should have completed

Variable documentation

int8_t Sensor::_dataPin protected

Digital pin number on the mcu receiving sensor data.

int8_t Sensor::_powerPin protected

Digital pin number on the mcu controlling sensor power.

const uint8_t Sensor::_numReturnedValues protected

The number of values the sensor is capable of reporting.

This includes raw values from the sensor and any values that are always calculated within the library for the sensor. The _incCalcValues are included in this total.

uint8_t Sensor::_measurementsToAverage protected

The number of measurements from the sensor to average.

uint8_t Sensor::_incCalcValues protected

The number of included calculated variables from the sensor, if any.

These are used for values that we would always calculate for a sensor and depend only on the raw results of that single sensor. This is separate from any calculated variables that are created on-the-fly and depend on multiple other sensors.

uint32_t Sensor::_millisPowerOn protected

The processor elapsed time when the power was turned on for the sensor.

The _millisPowerOn value is set in the powerUp() function. It is un-set in the powerDown() function.

uint32_t Sensor::_millisSensorActivated protected

The processor elapsed time when the sensor was activiated - ie, when the wake() function was run.

The _millisSensorActivated value is usually set in the wake() function, but may also be set in the startSingleMeasurement() function. It is generally un-set in the sleep() function.

uint32_t Sensor::_millisMeasurementRequested protected

The processor elapsed time when a measuremnt was started - ie, when the startSingleMeasurement() function was run.

The _millisMeasurementRequested value is set in the startSingleMeasurement() function. It may be unset in the addSingleMeasurementResult() function.