Library for Dallas Semiconductor DS18B20 one-wire temperature sensors.
- Library utilizes a detailed error handling.
- Library does not have conversion to imperial temperature units (degrees of Fahrenheit). The conversion should be provided in a sketch code or in a separate library in order to avoid code duplicities in sketches using multiple libraries with the same conversion functionalities.
- Library provides a device identifier taken from last byte (CRC) of a device's hardware ROM.
- Values for low and alarm conditions are stored in sensor's EEPROM, so that they can be used as a two-byte persistent memory.
- Library is primarily aimed for working with all sensors on the one-wire bus in a loop, so that they need not to be identified by an address in advance. Thus, all getters and setters are valid for currently selected sensor in a loop.
- The loop aproach is useful even if there is just one temperature sensor on the one-wire bus. It enables to replace a sensor without any change in a program code even during operation in a running application if properly programmed.
- OneWire: Library for communication on one-wire library #1 in PlatformIO Library Manager available at https://platformio.org/lib/show/1/OneWire.
- Particle.h: Includes alternative (C++) data type definitions.
- Arduino.h: Main include file for the Espressif platform.
- Arduino.h: Main include file for the Arduino SDK version greater or equal to 100.
- inttypes.h: Integer type conversions. This header file includes the exact-width integer definitions and extends them with additional facilities provided by the implementation.
The subfolder tests in the folder extras, i.e., gbj_ds18b20/extras/test, contains testing files, usually just one, with unit tests of library gbj_DS18B20 executable by Unity test runner. Each testing file should be placed in an individual test folder of a particular project, usually in the structure test/<testname>/<testfile>.
- ds18b20.cpp: Test suite providing test cases for all relevant public methods with connected real temperature sensor. Its ROM address should be set in the code of the test file directly.
- FAMILY_CODE (
Params::FAMILY_CODE): Implicit family code of the temperature sensor 0x28 (40). - ADDRESS_LEN (
Params::ADDRESS_LEN): Number of bytes in the sensor's ROM. - SERNUM_LEN (
Params::SERNUM_LEN): Number of bytes in the sensor's serial number. - SCRATCHPAD_LEN (
Params::SCRATCHPAD_LEN): Number of bytes in the sensor's data buffer.
- SUCCESS (
ResultCodes::SUCCESS): Successful processing of the recent function. - END_OF_LIST (
ResultCodes::END_OF_LIST): Last sensor on the bus has been processed. - ERROR_NO_DEVICE (
ResultCodes::ERROR_NO_DEVICE): No device on the one-wire bus detected, not only temperature ones. - ERROR_NO_SENSOR (
ResultCodes::ERROR_NO_SENSOR): No temperature sensor on the one-wire bus detected. - ERROR_CRC_ADDRESS (
ResultCodes::ERROR_CRC_ADDRESS): Bad hardware address of a sensor. - ERROR_CRC_SCRATCHPAD (
ResultCodes::ERROR_CRC_SCRATCHPAD): Reading of a sensor's data buffer has failed. - ERROR_NO_ALARM (
ResultCodes::ERROR_NO_ALARM): No temperature alarm detected. - ERROR_ALARM_LOW (
ResultCodes::ERROR_ALARM_LOW): Low temperature alarm has been detected. - ERROR_ALARM_HIGH (
ResultCodes::ERROR_ALARM_HIGH): High temperature alarm has been detected. - ERROR_CONVERSION (
ResultCodes::ERROR_CONVERSION): Conversion has started but cannot be finnished.
- It is possible to use functions from the parent library OneWire, which is extended by the gbj_DS18B20.
- The methods in bold return result or error codes.
- The getters in italic are static and can be called directly from the library without need of their instantiation.
- getAlarmHigh()
- getAlarmLow()
- isAlarm()
- isAlarmHigh()
- isAlarmLow()
- cacheAlarmHigh()
- cacheAlarmLow()
- cacheAlarmReset()
- setCache()
- cpyAddress()
- cpyScratchpad()
- cpySernum()
- getAddressRef()
- getAlarmHigh()
- getAlarmHighIni()
- getAlarmLow()
- getAlarmLowIni()
- getCache()
- getConvMillis()
- getDevices()
- getFamilyCode()
- getId()
- getLastResult()
- getPin()
- getResolution()
- getResolutionBits()
- getResolutionTemp()
- getScratchpadRef()
- getSensors()
- getTemperature()
- getTemperatureIni()
- getTemperatureMax()
- getTemperatureMin()
- isAlarm()
- isAlarmHigh()
- isAlarmLow()
- isError()
- isPowerExternal()
- isPowerParasite()
- isSuccess()
Custom data type determining the byte array for sensor hardware address (ROM).
- The size of the address text is determined by the constant ADDRESS_LEN.
gbj_ds18b20::Address address
gbj_ds18b20::Address address = {0x28, 0xC2, 0x51, 0x6F, 0x06, 0x00, 0x00, 0x6C};Custom data type determining the template for alarm handler procedures.
void gbj_ds18b20::Handler()
None
None
void alarmHandlerLow()
{
Serial.println("Low Alarm Handler");
}
gbj_ds18b20 ds = gbj_ds18b20(4, alarmHandlerLow);Custom data type determining the byte array for sensor data buffer.
- The size of the address text is determined by the constant SCRATCHPAD_LEN.
gbj_ds18b20::Scratchpad scratchpad
Custom data type determining the byte array for sensor hardware serial number.
- It is an inner part of the sensor ROM without the first family code byte and the last CRC byte.
- The size of the address text is determined by the constant SERNUM_LEN.
- The sensor's serial number might be considered as a MAC address of it.
gbj_ds18b20::Sernum sernum
Constructor creates the class instance object and alternatively sets alarm handlers.
- Constructor resets the one-wire bus.
- Constructor detects whether some of sensors on the bus is powered in parasitic mode.
- Constructor counts all devices as well as DS18B20 temperature sensors on the bus.
- The results are available by respective getters getDevices(), getSensors().
gbj_ds18b20(uint8_t pinBus, gbj_ds18b20::Handler *alarmHandlerLow, gbj_ds18b20::Handler *alarmHandlerHigh)
- pinBus: Number of GPIO pin of the microcontroller managing one-wire bus.
- Valid values: non-negative integer 0 to 255
- Default value: none
- alarmHandlerLow: Pointer to a procedure that is called than the measured temperature reaches the low alarms temperature or sinks bellow it.
- Valid values: within address space of the microcontroller by custom type Handler().
- Default value: 0 (not used any alarm handler)
- alarmHandlerHigh: Pointer to a procedure that is called than measured temperature reaches the high alarms temperature or is above it.
- Valid values: within address space of the microcontroller by custom type Handler().
- Default value: 0 (not used any alarm handler)
Object preforming the temperature measurement.
The constructor has the argument for alarm handlers defaulted.
gbj_ds18b20 ds = gbj_ds18b20(4); // Without alarm handlers
gbj_ds18b20 ds = gbj_ds18b20(4, alarmHandlerLow, alarmHandlerHigh);The method selects DS18B20 sensors active on the one-wire bus one by one, which are in the state of alarm signalling and for each of them reads scratchpad memory for further processing by getters and setters.
- The method conversion() for parallel temperature measurement should be called right before cycling the alarms.
- The method returns an error code for low or high alarm until there is a sensor with active alarm on the bus.
- The type of an alarm or just its instance can be detected by corresponding getter.
- After selecting the last alarm the method resets searching process.
gbj_ds18b20::ResultCodes alarms()
None
Error code about low or high alarm from Result and error codes of recently selected sensor with active alarm on the bus.
gbj_ds18b20 ds = gbj_ds18b20(4);
void setup()
{
ds.conversion();
while (ds.isAlarm(ds.alarms()))
{
...
}
}isAlarm(), isAlarmLow(), isAlarmHigh()
The method initiates measurement conversion of all sensors on the one-wire bus at once (parallelly). Then it is possible to read temperature from all sensors without subsequent conversion.
gbj_ds18b20::ResultCodes conversion()
None
Result code from Result and error codes.
The method counts all active devices on the one-wire bus, counts temperature sensors from them, and calculates maximal resolution of them.
- Results are available by corresponding getters.
gbj_ds18b20::ResultCodes devices()
None
Result code about detecting recent sensor on the bus defined by one of Result and error codes.
The method initiates measurement conversion of the particular sensor with provided address on the one-wire bus and reads its scratchpad right after it.
- The result is available by the getter getTemperature().
gbj_ds18b20::ResultCodes measureTemperature(gbj_ds18b20::Address address)
- address: Array variable with a device ROM identifying a sensor.
- Valid values: array of non-negative integers 0 to 255 with length defined by the constant ADDRESS_LEN
- Default value: none
Result code from Result and error codes.
- If there is no device on the one-wire bus, the method returns the error code ERROR_NO_DEVICE.
- If there is a device or more devices on the one-wire bus, but none with input ROM, the method returns the error code ERROR_CRC_SCRATCHPAD.
The method selects devices with DS18B20 family code and are active on the one-wire bus one by one and for each of them reads scratchpad memory for further processing by getters and setters.
- The method returns success result code until there is an active sensor on the bus.
- After selecting the last sensor the method resets searching process.
- At the end of searching process the methods update number of sensors of the bus for getter getSensors().
gbj_ds18b20::ResultCodes sensors()
None
Result code about selecting recent sensor on the bus defined by one of Result and error codes.
gbj_ds18b20 ds = gbj_ds18b20(4);
void setup()
{
while (ds.isSuccess(ds.sensors()))
{
...
}
}Corresponding method checks if selected device meets condition for low or high alarm or some of them detected right before.
- Before calling corresponding method the method alarms() should be called in order to detect alarm conditions. Usually it is called as an input parameter.
- A method without input parameter evaluates result of recent operation, which should be the method alarms().
bool isAlarmLow()
bool isAlarmLow(gbj_ds18b20::ResultCodes result)
bool isAlarmHigh()
bool isAlarmHigh(gbj_ds18b20::ResultCodes result)
bool isAlarm()
bool isAlarm(gbj_ds18b20::ResultCodes result)
- result: Result code of the recent operation detecting alarm conditions.
- Valid values: Some of ERROR_ALARM_LOW, ERROR_ALARM_HIGH.
- Default value: SUCCESS
Flag about signalling alarm condition.
ds.conversion();
while (ds.isAlarm(ds.alarms()))
{
if (ds.isAlarmLow()) Serial.println("Low alarm");
if (ds.isAlarmHigh()) Serial.println("High alarm");
}ds.conversion();
while (ds.isAlarmLow(ds.alarms()))
{
Serial.println("Low alarm");
}Corresponding method returns currently set corresponding alarm temperature of selected device in centigrades.
- If alarm signalling capability is not used, alarm condition values can be utilized as a general-purpose memory or 2-byte EEPROM respectively and these methods read stored signed bytes from EEPROM and the scratchpad.
int8_t getAlarmLow()
int8_t getAlarmHigh()
None
Temperature in centigrades currently set as a low or high alarm condition respectively.
cacheAlarmLow(), cacheAlarmHigh(), cacheAlarmsReset()
Corresponding method returns factory initial setting of an alarm conditions (in EEPROM) for the DS18B20 sensors.
- Method getAlarmLowIni() returns low factory alarm condition 70 centigrade.
- Method getAlarmHighIni() returns high factory alarm condition 75 centigrade.
- Those factory alarm conditions can be set by the method cacheAlarmReset() and writing to the EEPROM with the method setCache().
int8_t getAlarmLowIni()
int8_t getAlarmHighIni()
None
Factory temperature in centigrades as a low or high initial alarm condition respectively.
Corresponding method writes alarm condition to internal buffer representing scratchpad.
- Alarm temperatures are in integer centigrades.
- The method cacheAlarmsReset() sets factory default alarm conditions 70 and 75 centigrades.
- If alarm signalling capability is not used, alarm condition values can be utilized as a general-purpose memory or 2-byte EEPROM respectively and these methods write signed bytes to the scratchpad and EEPROM.
void cacheAlarmLow(int8_t alarmValue)
void cacheAlarmHigh(int8_t alarmValue)
void cacheAlarmsReset()
- alarmValue: Temperature in integer centigrades for appropriate alarm condition.
- Valid values: integer -55 ~ +125 defined by methods getTemperatureMin(), getTemperatureMax()
- Default value: none
None
The method writes desired temperature measurement resolution in bits to internal buffer representing configuration register of the scratchpad.
void cacheResolutionBits(uint8_t resolution)
- resolution: Temperature measurement resolution in bits.
- Valid values: non-negative integer 9 ~ 12
- Default value: 12 (factory default resolution)
None
The method writes all currently cached parameters to the sensor's scratchpad and EEPROM respectively.
gbj_ds18b20::ResultCodes setCache()
None
Result code from Result and error codes about writing scratchpad and EEPROM.
cacheAlarmLow(), cacheAlarmHigh(), cacheAlarmsReset()
The method reads the scratchpad from EEPROM and puts the concent to the internal cache.
- The method is suitable for unit testing. Otherwise it is used internally by loop methods.
gbj_ds18b20::ResultCodes getCache()
None
Result code from Result and error codes about reading from EEPROM.
The method returns current resolution as a binary value from the configuration register in the scratchpad according to the datasheet.
- The resolution determines the temperature conversion time needed at least.
uint8_t getResolution()
None
Temperature resolution as an internal code from configuration register (R1, R0).
The method returns current resolution expressed in bits.
uint8_t getResolutionBits()
None
Number of bits used for temperature measurement resolution in range 9 ~ 12.
The method returns current resolution of the selected device expressed in centigrades.
float getResolutionTemp()
None
Temperature resolution of measurement in the range 0.0625 ~ 0.5 centigrade.
The method returns recently measured temperature.
- It is useful for repeating utilizing the temperature without storing it in a separate variable in a sketch.
float getTemperature()
None
Recently measured temperature.
Corresponding method returns corresponding typical temperature features (static parameters) for the DS18B20 sensors temperature measurement range.
- Methods getTemperatureMin(), getTemperatureMax() return temperature measurement limits -55 ~ +125 centigrade.
- Method getTemperatureIni() returns power-on reset temperature 85 centigrade.
float getTemperatureMin()
float getTemperatureMax()
float getTemperatureIni()
None
Typical temperature features -55, +125, +85 centigrade.
The method returns product identifier as the very first byte of the ROM address of a currently selected sensor.
uint8_t getFamilyCode()
None
Device specific internal code for product identification of the sensor. For DS18B20 it is always HEX 28, DEC 40.
The method returns identifier of the selected device as the CRC code of the device ROM from its last byte.
uint8_t getId()
None
Short device identifier unique for all devices on the one-wire bus.
The method returns number of microcontroller pin mastering the one-wire bus.
- It is the pinBus parameter of the constructor.
uint8_t getPin()
None
Microcontroller pin number controlling one-wire bus.
The method returns number of milliseconds needed for temperature conversion depending on current temperature resolution.
- The return value defines a waiting period with respect to the datasheet that should last before subsequent new temperature measurement.
- The conversion time determines maximal measurement frequency.
uint16_t getConvMillis()
None
Number of milliseconds that the temperature conversion is going to last, usually at most.
The method returns number of active (communicating) devices on the one-wire bus of all families (not only DS18B20 sensors).
- The number of devices is calculated just in the constructor, i.e., at the moment of the creation of a library instance object unlike updating the number of active DS18B20 temperature sensors at each bus iteration and returned by getSensors().
uint8_t getDevices()
None
Number of devices on the one-wire bus at creation of a library instance object.
The method returns number of active (communicating) DS18B20 temperature sensors on the one-wire bus.
- The number of sensors is calculated the first time in the constructor and it is the number at the moment of creating a library instance object.
- The number of sensors is updated at each iterating over the one-wire bus by the method sensors().
uint8_t getSensors()
None
Number of active DS18B20 sensors on the one-wire bus detected at library instance creation or at recent bus iteration.
The appropriate method determines whether a device is in correponding mode of supplying.
bool isPowerExternal()
bool isPowerParasite()
None
Flag about external or parasitic power mode.
The method sets or initializes the internal status of recent processing on the one-wire bus to input value.
- Without input parameter the method initializes internal status to success result code with class constant SUCCESS.
- The method without input parameter is usually called right before any operation on the bus in order to reset the internal status or in methods without bus communication.
gbj_ds18b20::ResultCodes setLastResult()
gbj_ds18b20::ResultCodes setLastResult(gbj_ds18b20::ResultCodes result)
- result: Desired result code that should be set as a recent result code.
- Valid values: Some of Result or error codes.
- Default value: SUCCESS
New (actual) result code of recent operation from Result and error codes.
The method returns a result code of the recent operation on the one-wire bus. It is usually called for error handling in a sketch.
gbj_ds18b20::ResultCodes getLastResult()
None
Result code of the recent processing from Result and error codes.
The method returns a logical flag whether the recent operation was successful or failed respectivelly.
- The corresponding result code can be obtained by the method [getLastResult()]((#getLastResult).
bool isSuccess()
bool isError()
None
Flag about successful or failed processing of the recent operation.
Corresponding method returns pointer to the internal ROM address or internal scratchpad memory of a selected sensor.
- Methods are useful when just reading is used and there is no need to copy those memory arrays to separate array variables in a sketch.
uint8_t *getAddressRef()
uint8_t *getScratchpadRef()
None
Pointer to a byte array memory inside the library instance object.
The method copies the ROM into a provided input byte array.
void cpyAddress(gbj_ds18b20::Address address)
- address: Array variable for receiving device ROM.
Populated input array with device ROM.
gbj_ds18b20::Address address;
void setup()
{
while (ds.isSuccess(ds.sensors()))
{
ds.cpyAddress(address);
}
}The method copies the current cache of the scratchpad into a provided input byte array.
void cpyScratchpad(gbj_ds18b20::Scratchpad scratchpad)
- scratchpad: Array variable for receiving device scratchpad.
Populated input array with current device scratchpad cache content.
gbj_ds18b20::Scratchpad scratchpad;
void setup()
{
while (ds.isSuccess(ds.sensors()))
{
ds.cpyScratchpad(scratchpad);
}
}The method copies the current cache of the scratchpad into a provided input byte array.
void cpySernum(gbj_ds18b20::Sernum sernum)
- sernum: Array variable for receiving device serial number as a part of ROM.
Populated input array with device serial number.
gbj_ds18b20::Sernum sernum;
void setup()
{
while (ds.isSuccess(ds.sensors()))
{
ds.cpySernum(sernum);
}
}