Arduino DallasTemperature library

The 1-Wire protocol is complicated to use and requires relatively long code to operate the devices. Using the DallasTemperature library, you can easily retrieve data from the Dallas 1-Wire thermometer IC. The devices supported by the DallasTemperature library are DS18B20, DS1822, DS18S20, DS1820.

In this article, we use the Dallas Semiconductor DS18B20 1-Wire thermometer for examples. The DS18B20 is a small TO92 encapsulated thermometer IC that can be connected to our Arduino board via a digital input. It is a 1 wire device, it only needs a digital pin to communicate with the microcontroller.

Installing the DallasTemperature library

To install the DallasTemperature library, open the library manager by pressing ‘Ctrl+Shift+i’ or go to ‘Sketch -> Include library -> Manage libraries…’.

In the search box, type ‘DallasTemperature’ or ‘DS18B20’, then install the ‘Miles Burton DallasTemperature‘ library.

How to use the DallasTemperature library

To use the DallasTemperature library, you first need the ‘OneWire’ library. Then we can call the DallasTemperature.h file in our sketch.

#include <OneWire.h>
#include <DallasTemperature.h>

To communicate with the DS18B20 sensor, we first create a oneWire object and pass as a parameter the number of the arduino pin to which the DS18B20 sensor’s data line is connected.

We then create an instance of the DallasTemperature object, with a reference to the oneWire object we just created in its parameter.

const char oneWirePin = 10;

OneWire myOneWire(oneWirePin);	
DallasTemperature mySensors(&myOneWire);

begin

First, we initialize the bus using the begin function in the setup() section, then communication can begin.

void setup() 
{
  ....
  mySensors.begin();
  ...
}

Back to table of contents.

getDeviceCount

The getDeviceCount function returns the number of devices found on the bus.

int sensors = mySensors.getDeviceCount();
Serial.print("Devices: ");
Serial.println(sensors);

Back to table of contents.

getAddress

The getAddress function returns a true value if it finds an address on the bus at the location specified in the index parameter. The hexadecimal address of the found device is placed in the ‘deviceAddress’ parameter.

DeviceAddress deviceAddress;
int index = 0;

bool foundAddress = mySensors.getAddress(deviceAddress, index);
if(foundAddress)
{
  for (int i = 0; i < 8; i++)
  {
    if (deviceAddress[i] < 0x10) Serial.print("0");
    Serial.print(deviceAddress[i], HEX);
  }
}

Back to table of contents.

validAddress

The validAddress function returns true if the device address is valid.

DeviceAddress  deviceAddress;
mySensors.getAddress(deviceAddress, 0);

bool addressIsValid = mySensors.validAddress(deviceAddress);

Back to table of contents.

validFamily

The validFamily function returns true if the address belongs to a family of sensors supported by the DallasTemperature library.

DeviceAddress deviceAddress;
mySensors.getAddress(deviceAddress, 0);

bool familyIsValid = mySensors.validFamily(deviceAddress);

Back to table of contents.

isConnected

The isConnected function tries to determine whether the device at the address specified in the parameter is connected to the bus.

DeviceAddress deviceAddress;
mySensors.getAddress(deviceAddress, 0);

bool connected = mySensors.isConnected(deviceAddress);

A second parameter can be given to the isConnected function, thereby enabling the reading of the scratchpad.

DeviceAddress deviceAddress;
ScratchPad scratchPad;
mySensors.getAddress(deviceAddress, 0);

bool connected = mySensors.isConnected(deviceAddress, scratchPad);

Back to table of contents.

readScratchPad

The readScratchPad function reads the contents of the device’s scratchpad.

DeviceAddress deviceAddress;
ScratchPad scratchPad;

mySensors.getAddress(deviceAddress, 0);
mySensors.readScratchPad(deviceAddress, scratchPad);

for(int i = 0; i < 9; i++)
{
  Serial.print(i);
  Serial.print(". byte: ");
  Serial.print(scratchPad[i]);
  Serial.println();
}

Back to table of contents.

writeScratchPad

Use the writeScratchPad function to write the scratchpad contents of the device.

DeviceAddress deviceAddress;
ScratchPad scratchPad;

mySensors.getAddress(deviceAddress, 0);

scratchPad[2] = 30;
scratchPad[3] = 18;
mySensors.writeScratchPad(deviceAddress, scratchPad);

Back to table of contents.

readPowerSupply

The readPowerSupply function returns true if parasitic mode, i.e. 2-wire mode, is used. Returns false when using normal 3-wire mode.

If no device address is specified, it checks to see if any device on the bus is using parasitic mode.

DeviceAddress deviceAddress;
mySensors.getAddress(deviceAddress, 0);

Serial.println(mySensors.readPowerSupply(deviceAddress));

Back to table of contents.

getResolution

If the getResolution function is called without parameters, it returns the general value of the resolution for the devices on the 1-Wire bus. The resolution can be 9, 10, 11 or 12 bits.

int resolutionGlobal = mySensors.getResolution();

If the parameter of the getResolution function is the address of a given device, it returns the resolution of the given device.

DeviceAddress deviceAddress;
mySensors.getAddress(deviceAddress, 0);

Serial.print(mySensors.getResolution(deviceAddress), DEC);

Back to table of contents.

setResolution

The general value of the resolution for devices on the 1-Wire bus can be set to the value specified in the setResolution function parameter. The resolution can be 9, 10, 11 or 12 bits.

mySensors.setResolution(12);

If the setResolution function is called with two parameters, the resolution value for the devices specified in parameter 1 can be set to the value specified in parameter 2.

DeviceAddress deviceAddress;
mySensors.getAddress(deviceAddress, 0);

mySensors.setResolution(deviceAddress, 12);

Back to table of contents.

setWaitForConversion

The setWaitForConversion function is used to set a flag.

If setWaitForConversion is true, requestTemperature() returns when the conversion is complete. This is the default.

If setWaitForConversion is false, requestTemperature() returns immediately. Use with caution, the time required for conversion should be provided. This method does not block the main program from running during the conversion.

#include <OneWire.h>
#include <DallasTemperature.h>

const char oneWirePin = 10;

OneWire myOneWire(oneWirePin);	
DallasTemperature mySensors(&myOneWire);

int  resolution = 12;
unsigned long lastTemperatureRequest = 0;
int delayForConversion = 0;
float temperature = 0.0;
DeviceAddress deviceAddress;

void setup()
{
  Serial.begin(115200);

  mySensors.begin();
  mySensors.getAddress(deviceAddress, 0);
  mySensors.setResolution(deviceAddress, resolution);
  mySensors.setWaitForConversion(false);
  mySensors.requestTemperatures();

  delayForConversion = 750 / (1 << (12 - resolution));
  lastTemperatureRequest = millis();
}

void loop()
{
  if (millis() - lastTemperatureRequest >= delayForConversion)
  {
    Serial.print(" Temperature: ");
    Serial.println(mySensors.getTempCByIndex(0));
    mySensors.requestTemperatures();
    lastTemperatureRequest = millis();
  }

}

Back to table of contents.

getWaitForConversion

The getWaitForConversion function can be used to retrieve the value of the flag set by the setWaitForConversion function.

bool waitForConversionFlag = mySensors.getWaitForConversion();

Back to table of contents.

setCheckForConversion

setCheckForConversion sets the value of the checkForConversion flag.
If the flag is true, the requestTemperature() function waits for a response from the thermometer IC that the conversion is complete. If the flag is false, the requestTemperature() function waits for a specified time until the conversion is sure to be complete.

mySensors.setCheckForConversion(false);

Back to table of contents.

getCheckForConversion

The getCheckForConversion function can be used to retrieve the value of the checkForConversion flag.

bool checkForConversionFlag = mySensors.getCheckForConversion();

Back to table of contents.

requestTemperatures

The requestTemperatures function sends a command to all devices on the bus to perform the temperature conversion.

mySensors.requestTemperatures();

Back to table of contents.

requestTemperaturesByAddress

The requestTemperaturesByAddress function sends a command to the device with the address specified in the parameter to perform the temperature conversion.

DeviceAddress deviceAddress;
mySensors.getAddress(deviceAddress, 0);

mySensors.requestTemperaturesByAddress(deviceAddress);

Back to table of contents.

requestTemperaturesByIndex

The requestTemperaturesByIndex function sends a command to the device with the index specified in the parameter to perform the temperature conversion.

mySensors.requestTemperaturesByIndex(0);

Back to table of contents.

getTemp

The getTemp returns the raw temperature value, or DEVICE_DISCONNECTED_RAW if the scratchPad memory of the device cannot be read successfully. DEVICE_DISCONNECTED_RAW is a large negative number outside the operating range of the device.

float tempRaw = mySensors.getTemp(deviceAddress);

Back to table of contents.

getTempC

The getTempC function returns the temperature in °C or DEVICE_DISCONNECTED_C if the scratchPad memory of the device cannot be read successfully. The DEVICE_DISCONNECTED_C numeric value is a large negative number outside the operating range of the device.

float tempC = mySensors.getTempC(deviceAddress);

Back to table of contents.

getTempF

The getTempF function returns the temperature in °F or DEVICE_DISCONNECTED_F if the scratchPad memory cannot be read successfully. The numeric value of DEVICE_DISCONNECTED_F is a large negative number outside the operating range of the device.

float tempF = mySensors.getTempF(deviceAddress);

Back to table of contents.

getTempCByIndex

The getTempCByIndex function returns the temperature in °C of the device with the index specified in the parameter.

float tempC = mySensors.getTempCByIndex(0);

Back to table of contents.

getTempFByIndex

The getTempFByIndex function returns the temperature in °F of the device with the index specified in the parameter.

float tempF = mySensors.getTempFByIndex(0);

Back to table of contents.

advertising – Amazon.com

isParasitePowerMode

The isParasitePowerMode function returns true if the device on the 1-wire bus needs parasite power.

bool parasiteModeFlag = mySensors.isParasitePowerMode(); 

Back to table of contents.

isConversionComplete

The isConversionComplete function returns true when the conversion is complete on the 1-wire device. It only applies to the first sensor on the bus.

Back to table of contents.

setHighAlarmTemp

With the setHighAlarmTemp function you can set the high alarm temperature of the device in Celsius degrees. It accepts the floating point value but ignores values after the decimal point. The valid range is -55C – 125C.

int celsius = 36;

mySensors.setHighAlarmTemp(deviceAddress, celsius);

Back to table of contents.

setLowAlarmTemp

setLowAlarmTemp function to set the low alarm temperature of the device in Celsius degrees. It accepts the floating point value but ignores values after the decimal point. The valid range is -55C – 125C.

int celsius = 14;

mySensors.setLowAlarmTemp(deviceAddress, celsius);

Back to table of contents.

getHighAlarmTemp

getHighAlarmTemp returns the current high alarm temperature for the device specified in the parameter.

int highAlarmTemp = mySensors.getHighAlarmTemp(deviceAddress);

Back to table of contents.

getLowAlarmTemp

getLowAlarmTemp returns the current low alarm temperature for the device specified in the parameter.

int lowAlarmTemp = mySensors.getLowAlarmTemp(deviceAddress);

Back to table of contents.

resetAlarmSearch

resetAlarmSearch resets the internal variables used by the alarmSearch function.

Back to table of contents.

alarmSearch

alarmSearch searches for devices with active alarms on the 1-wire bus. If it finds a device, it returns true and stores the address of the found device in a variable in the parameter.

DeviceAddress deviceWithAlarmAddress;
bool foundAlarm = mySensors.alarmSearch(deviceWithAlarmAddress);

if(foundAlarm)
{
  for (int i = 0; i < 8; i++)
  {
    if (deviceWithAlarmAddress[i] < 0x10) Serial.print("0");
    Serial.print(deviceWithAlarmAddress[i], HEX);
  }
}
Serial.println();

Back to table of contents.

hasAlarm

The hasAlarm function returns true if any device reports an alarm condition on the bus.

bool hasAlarmFlag = mySensors.hasAlarm();

If hasAlarm is called with the device address passed in the parameter, it returns true if the device has an alarm.

DeviceAddress deviceAddress;
bool hasAlarmFlag = mySensors.hasAlarm(deviceAddress);

Back to table of contents.

processAlarms

The processAlarms() function runs the alarm handler on all devices returned by alarmSearch().

mySensors.processAlarms();

Back to table of contents.

setAlarmHandler

The setAlarmHandler function sets the alarm handler.

.....

void myAlarmHandler(const uint8_t* deviceAddress)
{
  Serial.print(mySensors.getHighAlarmTemp(deviceAddress), DEC);
  Serial.println(" °C");

  Serial.print(mySensors.getLowAlarmTemp(deviceAddress), DEC);
  Serial.println(" °C");
}
....

void setup()
{

  .....
  mySensors.begin();
  mySensors.setHighAlarmTemp(deviceAddress, 32);
  mySensors.setLowAlarmTemp(deviceAddress, 16);

  mySensors.setAlarmHandler(&myAlarmHandler);
  ....
}

void loop()
{
  .....
  mySensors.processAlarms();
  ......
}

Back to table of contents.

set/get UserData

If no alarm handler is used, the two bytes can be used as user data.

int data;
DeviceAddress deviceAddress;

mySensors.setUserData(deviceAddress, data);

int data;
int deviceIndex;

mySensors.setUserDataByIndex(deviceIndex, data); 

DeviceAddress deviceAddress;

int data = mySensors.getUserData(deviceAddress);

int deviceIndex = 0;

int data = mySensors.getUserDataByIndex(deviceIndex);

Back to table of contents.

toFahrenheit

The toFahrenheit function converts from Celsius to Fahrenheit.

float celsius = mySensors.getTempC(deviceAddress);
float fahrenheit = mySensors.toFahrenheit(celsius); 

Back to table of contents.

toCelsius

The toCelsius function converts from Fahrenheit to Celsius.

float fahrenheit = mySensors.getTempF(deviceAddress);
float celsius = mySensors.toCelsius(fahrenheit);

Back to table of contents.

rawToCelsius

RawToCelsius converts raw data to Celsius.

int raw = mySensors.getTemp(deviceAddress);
float celsius = mySensors.rawToCelsius(raw);

Back to table of contents.

rawToFahrenheit

The rawToFahrenheit function converts from raw data to Fahrenheit.

int raw = mySensors.getTemp(deviceAddress);
float fahrenheit = mySensors.rawToFahrenheit(raw);

Back to table of contents.

celsiusToRaw

The celsiusToRaw function converts from Celsius to raw temperature.

float celsius = mySensors.getTempC(deviceAddress);
int raw = mySensors.celsiusToRaw(celsius);

Back to table of contents.

Példák DallasTemperature könyvtár használatára

Read DS18B20

In the first example, the temperature of a single DS18B20 sensor is retrieved and written to the serial monitor.

At the beginning of the sketch, we’ll pull in the necessary libraries and create an instance of OneWire and DallasTemperature.

Then in the setup section initialize the serial port and the 1-wire bus with the begin function.

The requestTemperatures function is used to start the temperature conversion. Then the getTempCByIndex function is used to retrieve the temperature in °C from the DS 18B20 device.

#include <OneWire.h>
#include <DallasTemperature.h>

const char oneWirePin = 10;

OneWire myOneWire(oneWirePin);	
DallasTemperature mySensors(&myOneWire);

void setup()
{
  Serial.begin(9600);
  mySensors.begin();
}


void loop()
{
  mySensors.requestTemperatures();
  float tempC = mySensors.getTempCByIndex(0);


  Serial.print("Temperature: ");
  Serial.print(tempC);

  Serial.println("°C");
}

Back to table of contents.

Read DS18B20 devices by index

When calling the begin function of the DallasTemperature library, it will look for all supported sensors on the bus. It treats the sensors found on the bus as an array and assigns an index to each one. As a result, each sensor can be identified by its index.

Here is a simple schematic that locates all the DSB1820s on the bus and then shows the temperature of each one.

#include <OneWire.h>
#include <DallasTemperature.h>

const char oneWirePin = 10;

OneWire myOneWire(oneWirePin);	
DallasTemperature mySensors(&myOneWire);

int deviceCount = 0;
float tempC;

void setup()
{
  Serial.begin(9600);
  mySensors.begin();
  
  deviceCount = mySensors.getDeviceCount();
  Serial.print(deviceCount, DEC);
  Serial.println(" device is on the 1-wire bus.");
}

void loop()
{ 
  mySensors.requestTemperatures();
  for (int i = 0;  i < deviceCount;  i++)
  {
    Serial.print(i+1);
    Serial.print(". Sensor temp.: ");
    tempC = mySensors.getTempCByIndex(i);
    Serial.print(tempC);
    Serial.print("°C -- ");
    Serial.print(mySensors.toFahrenheit(tempC));
    Serial.println("°F");
  }
  
  Serial.println("");
  delay(1000);
}

Back to table of contents.

Finding the address of DS18B20 thermometers on a bus

Each DS18B20 thermometer IC was given a unique 64-bit address during manufacturing, so we can distinguish each device from the other on the 1-wire bus.

The following sketch can be used to locate all DS18B20 thermometers on the oneWire bus and print their 1-wire address to the serial monitor. To make it easier to identify each device, connect only one DS18B20 IC to the bus at a time.

#include <OneWire.h>
#include <DallasTemperature.h>

const char oneWirePin = 10;

OneWire myOneWire(oneWirePin);	
DallasTemperature mySensors(&myOneWire);

DeviceAddress newAddress;
int deviceCount = 0;

void setup()
{
  Serial.begin(9600);
  mySensors.begin();

  deviceCount = mySensors.getDeviceCount();
  Serial.print(deviceCount, DEC);
  Serial.println(" device is on the 1-wire bus.");
  Serial.println();

  for (int i = 0;  i < deviceCount;  i++)
  {
    Serial.print(i+1);
    Serial.print(". Sensor Address: ")
    mySensors.getAddress(newAddress, i);
    printAddress(newAddress);
  }
}

void loop() {}

void printAddress(DeviceAddress deviceAddress)
{ 
  for (uint8_t i = 0; i < 8; i++)
  {
    Serial.print("0x");
    if (deviceAddress[i] < 0x10) Serial.print("0");
    Serial.print(deviceAddress[i], HEX);
    if (i < 7) Serial.print(", ");
  }
  Serial.println();
}

Make a note of all the addresses.

Back to table of contents.

DS18B20 olvasása cím szerint

The following example uses the addresses of the DS18B20 thermometer ICs to read the temperatures. Don’t forget to replace the addresses of the DS18B20 sensors with the addresses extracted using the previous example!

#include <OneWire.h>
#include <DallasTemperature.h>

const char oneWirePin = 10;

OneWire myOneWire(oneWirePin);	
DallasTemperature mySensors(&myOneWire);

DeviceAddress sensor1 = {0x28, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0};
DeviceAddress sensor2 = {0x28, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0};

void setup()
{
  Serial.begin(9600);
  sensors.begin();
}

void loop()
{
  mySensors.requestTemperatures();
  
  Serial.print("1.Sensor temperature: ");
  printTemperature(sensor1);
  
  Serial.print("2.Sensor temperature: ");
  printTemperature(sensor2);

  Serial.println();
  delay(1000);
}

void printTemperature(DeviceAddress deviceAddress)
{
  float tempC = mySensors.getTempC(deviceAddress);
  Serial.print(tempC);
  Serial.print("°C -- ");
  Serial.print(mySensors.toFahrenheit(tempC));
  Serial.println("°F");
}

Back to table of contents.