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 AnalogElecConductivity: Class for the analog Electrical Conductivity monitor.
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 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 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) deleted: Dis-allowed assignment of one Sensor object to another - the deleted assignment operator.
String getSensorLocation(void ) virtual: Get the pin or connection location between the mcu and the sensor.
String getSensorName(void ) virtual: Get the name of the sensor.
String getSensorNameAndLocation(void ): Concatentate and returns the name and location of the sensor.
int8_t getPowerPin(void ) virtual: Get the pin number controlling sensor power.
void setNumberMeasurementsToAverage(uint8_t nReadings): Set the number measurements to average.
uint8_t getNumberMeasurementsToAverage(void ): Get the number of measurements to average.
uint8_t getStatus(void ): Get the 8-bit code for the current status of the sensor.
bool setup(void ) virtual: Do any one-time preparations needed before the sensor will be able to take readings.
bool update(void ) 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 ) 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 ) virtual: Puts the sensor to sleep, if necessary.
bool startSingleMeasurement(void ) virtual: Tell the sensor to start a single measurement, if needed.
bool addSingleMeasurementResult(void ) 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): Check if the _powerPin is currently high.
bool 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.
void waitForWarmUp(void ): Hold all further program execution until this sensor is ready to receive commands.
bool 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.
void waitForStability(void ): Hold all further program execution until this sensor is reporting stable values.
bool 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.
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 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(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(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& 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 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 getSensorName(void ) virtual

Get the name of the sensor.

Returns	String The sensor name as given in the constructor.

String 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 getPowerPin(void ) virtual

Get the pin number controlling sensor power.

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

void 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 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 getStatus(void )

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

Returns	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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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.