This is an application library, which is used usually as a project library for particular PlatformIO project. It encapsulates the functionality of DS18B20 temperature sensors. The encapsulation provides following advantages:
- Functionality is hidden from the main sketch.
- The library follows the principle
separation of concerns. - The library is reusable for various projects without need to code temperature measurement management.
- Update in library is valid for all involved projects.
- It specifies (inherits from) the parent application library
gbj__appcore. - It utilizes funcionality and error handling from the parent class.
- The library averages temperatures from all active and valid sensors on one-wire bus and statistically smooths the average temperature.
- Valid sensor is one which temperature value is whithin valid range of temperatures.
- gbj_appcore: Parent library for all application libraries loaded from the file
gbj_appcore.h. - gbj_appfilter: Library for filtering measured temperature values against a valid range loaded from the file
gbj_appfilter.h. - gbj_ds18b20: Library for processing temperature sensors
DS18B20loaded from the filegbj_ds18b20.h. - gbj_exponential: Library for statistical smoothing final average temperature loaded from the file
gbj_exponential.h. - gbj_serial_debug: Auxilliary library for debug serial output loaded from the file
gbj_serial_debug.h. It enables to exclude serial outputs from final compilation. - paulstoffregen/OneWire: Third party library for communication on one-wire bus.
- Arduino.h: Main include file for the Arduino SDK.
- inttypes.h: Integer type conversions. This header file includes the exact-width integer definitions and extends them with additional facilities provided by the implementation.
- gbj_appthermo_ds()
- run()
- getTemperatureRaw()
- getTemperatureRawRound()
- getTemperature()
- getTemperatureRound()
- getSensorPtr()
- getIdList()
- getIds()
- getTemperatureAvg()
- getTemperatureMin()
- getTemperatureMax()
- getTemperatureMinTime()
- getTemperatureMaxTime()
- reset()
The template or the signature of a callback function, which is called at particular event in the processing. It can be utilized for instant communicating with other modules of the application (project).
- A handler is just a bare function without any input parameters and returning nothing.
- A handler can be declared just as
voidtype.
typedef void Handler()
None
None
Structure of pointers to handlers each for particular event in processing.
- Individual or all handlers do not need to be defined in the main sketch, just those that are useful.
struct Handlers
{
Handler *onMeasureSuccess;
Handler *onMeasureFailure;
Handler *onMeasureResol;
Handler *onMeasureSensors;
}
- onMeasureSuccess: Pointer to a callback function, which is called after successful temperature measurement.
- onMeasureFailure: Pointer to a callback function, which is called after failed temperature measurement.
- onMeasureResol: Pointer to a callback function, which is called after changing the temperature measurement resolution.
- onMeasureSensors: Pointer to a callback function, which is called after changing the number of temperature sensors on the bus. Initially this number is set to zero, so that this handler is always called at least once at the very first measurement.
void onThermoSuccess()
{
...
}
void onThermoFailure()
{
...
}
void onThermoResol()
{
...
}
void onThermoSensors()
{
...
}
gbj_appthermo_ds::Handlers handlersThermo = {
.onMeasureSuccess = onThermoSuccess,
.onMeasureFailure = onThermoFailure,
.onMeasureResol = onThermoResol,
.onMeasureSensors = onThermoSensors,
};
gbj_appthermo_ds thermo = gbj_appthermo_ds(..., handlersThermo);Constructor creates the class instance object and initiates internal resources.
- It inputs operational parameters for temperature sensors.
- The input resolution is set to all sensors on the bus.
gbj_appthermo_ds(byte pinBus, float tempMax, float tempMin, float smoothingFactor, byte resolution, Handlers handlers)
-
pinBus: Number of GPIO pin of the microcontroller managing one-wire bus.
- Valid values: positive integers 0 ~ 255
- Default value: none
-
tempMax: Maximal temperature in centigrades (°C) of valid range.
- Valid values: rational number
- Default value: none
-
tempMin: Minimal temperature in centigrades (°C) of valid range.
- Valid values: rational number
- Default value: 0.0
-
smoothingFactor: Smoothing factor for exponential filtering.
- Valid values: real number 0.0 ~ 1.0
- Default value: 0.2
-
resolution: Number of bits for temperature measurement resolution.
- Valid values: positive integers 9 ~ 12
- Default value: 10
-
handlers: Pointer to a structure of callback functions. This structure as well as handlers should be defined in the main sketch.
- Data type: Handlers
- Default value: empty structure
Object performing temperature measurement.
The execution method should be called when the new temperature value is needed, usually in a timer or suitable handler.
- The method executes conversion for all sensors on the bus at once.
- An average (mean) temperature is calculated from temperature values measured by all successful and valid sensors.
- Successful sensor is one that communicates on the bus.
- Valid sensor is one which temperature value is whithin valid range of temperatures.
- The final temperature is obtained from statistical smoothing of the average temperature by exponential filtering.
- The handlers are called at every run, if they are declared in the constructor and corresponding conditions have been met.
The methods return the recently known averaged temperature from all active and valid sensors with successful recent conversion either with full precision or rounded value.
- The temperature is only filter on valid range without any statistical smoothing.
- In case of entirelly failed conversion at all sensors on the bus the average temperature is
0. - The precision of the averaged temperature value, but not precision of the measurement itself, depends on the measurement resolution (number of used fraction digits) of sensors set by constructor.
float getTemperatureRaw()
float getTemperatureRawRound(byte precision)
- precision: Number of decimal places for rounding temperature value.
- Valid values: positive integers 0 ~ 255
- Default value: 2
The averaged current temperature in degrees of Celsius (°C) or rounded to provided decimal places.
The methods return the recently known averaged and statistically smoothed temperature from all active and valid sensors with successful recent conversion either with full precision or rounded value.
- In fact, this method statistically smoothes the temperature gained by respective method from getTemperatureRaw(), getTemperatureRawRound().
- In case of entirelly failed conversion at all sensors on the bus the average temperature is
0. - The precision of the averaged temperature value, but not precision of the measurement itself, depends on the measurement resolution (number of used fraction digits) of sensors set by constructor.
float getTemperature()
float getTemperatureRound(byte precision)
- precision: Number of decimal places for rounding temperature value.
- Valid values: positive integers 0 ~ 255
- Default value: 2
The averaged statistically smoothed temperature in degrees of Celsius (°C) or rounded to provided decimal places.
The method returns the pointer to the internal object controlling the DS18B20 temperature sensor itself.
- It allows to utilize entire interface of the corresponding library
gbj_ds18b20without wrapping or mirroring it. - The methods of this internal object are valid for currently selected sensor on the bus.
gbj_ds18b20 *getSensorPtr()
None
Pointer to the control object of the DS18B20 temperature sensor hardware.
gbj_appthermo_ds thermo = gbj_appthermo_ds(...);
void setup()
{
thermo.getSensorPtr()->getSensors();
}The method returns comma separated list of identifiers of valid temperature sensors.
- As a valid temperature sensor is consider a sensor, which measured temperature is within valid range of temperatures.
- The identifier is the CRC code of the temperature sensor's ROM from its last byte.
String getIdList()
None
Comma separated list of valid temperature sensors' identifiers.
The method returns number of valid temperature sensors.
- As a valid temperature sensor is consider a sensor, which measured temperature is within valid range of temperatures.
byte getIds()
None
Number of valid temperature sensors.
The particular method returns respective statistical value, average, minimum, or maximum of the smoothed temperature whithin an observation period.
- Observation period is the time period since MCU start or recent reset of statistics by method reset() for which aforementioned statistical values are calculated.
float getTemperatureAvg()
float getTemperatureMin()
float getTemperatureMax()
None
The respective statistical value of the temperature in degrees of Celsius (°C).
The particular method returns MCU uptime in milliseconds when the respective statistical value, minimum or maximum, has been reached the very first time within an observation period.
- Observation period is the time period since MCU start or recent reset of statistics by method reset() for which aforementioned statistical values are calculated.
unsigned long getTemperatureMinTime()
unsigned long getTemperatureMaxTime()
None
The respective statistical value of the temperature in degrees of Celsius (°C).
The method resets all statistical measures and starts new observation period.
void reset()
None
None