ModularSensors > Classes > Sensor
ModularSensors > Modules > Primary Object Classes > Sensor


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 CampbellOBS3
The Sensor sub-class for the Campbell OBS3 analog turbidity sensor.
class ExternalVoltage
The Sensor sub-class for the external votlage as measured by TI ADS1115 or ADS1015.
class KellerParent
The Sensor sub-class for all Keller water level sensors.
class MPL115A2
The Sensor sub-class for the Freescale Semiconductor MPL115A2 sensor.
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 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 numReturnedVars = 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)
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(int 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 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 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 numReturnedVars = 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)

Construct a new Sensor object.

Parameters
sensorName The name of the sensor. Defaults to "Unknown".
numReturnedVars The number of variable results 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.

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.


StringgetSensorLocation(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.

StringgetSensorName(void ) virtual

Get the name of the sensor.

Returns String The sensor name as given in the constructor.

StringgetSensorNameAndLocation(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.

int8_tgetPowerPin(void ) virtual

Get the pin number controlling sensor power.

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

voidsetNumberMeasurementsToAverage(int 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_tgetNumberMeasurementsToAverage(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.

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_tgetStatus(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

boolsetup(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.


boolupdate(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.


voidpowerUp(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.


voidpowerDown(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.


boolwake(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.


boolsleep(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.


boolstartSingleMeasurement(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.


booladdSingleMeasurementResult(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.


voidverifyAndAddMeasurementResult(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.

voidverifyAndAddMeasurementResult(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.

voidregisterVariable(int sensorVarNum, Variable* var)

Register a variable object to a sensor.

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

boolcheckPowerOn(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.

boolisWarmedUp(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.

boolisStable(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.

boolisMeasurementComplete(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.


uint8_t Sensor::_measurementsToAverage protected

The number of measurements from the sensor to average.

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.


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.