ds18x20: Driver for DS18B20/DS18S20 families of 1-Wire temperature sensor ICs

Driver for the DS18B20/DS18S20 families of 1-Wire temperature sensors.

The driver works on top of a 1-Wire bus implementation, and there are two of them to choose from: the bit-banging driver of esp-idf-lib/onewire and the RMT driver of espressif/onewire_bus. The choice is made in menuconfig, see 1-Wire backends.

Supported sensors

Family code

Part

Resolution

LSB

Notes

0x10

DS18S20, DS1820

9 bit

0.5 °C

Fixed resolution, the scratchpad carries the count remainder and the count per °C, which the driver uses to refine the reading

0x22

DS1822

9–12 bit

0.0625 °C

Same register layout as the DS18B20

0x28

DS18B20

9–12 bit

0.0625 °C

The most common part, including the waterproof probes

0x3B

DS1825

9–12 bit

0.0625 °C

Shares the family code with the MAX31850

0x3B

MAX31850, MAX31851

14 bit

0.0625 °C

Thermocouple-to-digital converter

0x42

DS28EA00

9–12 bit

0.0625 °C

Sequence detect and PIO pins, both unused by the driver

0x54

MAX31888

13–16 bit

0.005 °C

Recognized during the scan, but not supported yet: it keeps the readings in a FIFO and uses another command set

ds18x20_scan_devices() returns all devices of the families above, and ds18x20_read_temperature() picks the right formula by the family code. The per-family functions (ds18s20_read_temperature(), ds18b20_read_temperature(), max31850_read_temperature()) remain available for the cases where the address is known in advance.

1-Wire backends

The backend is selected in menuconfig → Component config → DS18x20 → 1-Wire backend. The bit-banging driver is the default.

CONFIG_DS18X20_ONEWIRE_BACKEND_BITBANG

CONFIG_DS18X20_ONEWIRE_BACKEND_ESPRESSIF

Implementation

esp-idf-lib/onewire

espressif/onewire_bus

Hardware

A GPIO pin, no peripheral

A pair of RMT channels per bus

Interrupts

Disabled while a byte is transferred

The RMT peripheral does the timing, interrupts stay enabled

Parasitic power

Supported with a strong pull-up

Not supported, the sensors must have a power pin

Number of buses

Any number of pins

Up to CONFIG_DS18X20_MAX_BUSES (4 by default)

Timing accuracy

Depends on the interrupt latency

Generated by the hardware

Pick the bit-banging backend when the sensors are parasitically powered, when RMT channels are needed elsewhere, or when the application already uses esp-idf-lib/onewire. Pick the RMT backend when long interrupt latencies or a busy WiFi stack make the bit-banging unreliable.

Both backends are declared as dependencies in idf_component.yml, because the dependency set is resolved before sdkconfig exists and cannot depend on the chosen backend. Both components are therefore downloaded and compiled, but only the selected one is linked into the image: the other one has no references, so the linker drops it.

The public API does not change with the backend: every function takes a GPIO pin, and the RMT bus object is created on the first access to the pin and kept until ds18x20_bus_free() is called. ds18x20_bus_init() creates the bus eagerly and lets the application detect the failure at a known place; with the bit-banging backend both functions only validate the pin.

Parasitic power and the 85 °C reading

A sensor without a power pin takes the power from the data line and needs the bus to be held high with a strong pull-up during the conversion, which takes up to 750 ms. Only the bit-banging backend can do that: ds18x20_measure() with wait = true drives the pin as a push-pull output for the whole conversion.

The RMT backend cannot drive the bus during the conversion, because the pin belongs to the RMT peripheral. Such a sensor never converts and keeps the power-on value in its temperature register, which reads as 85 °C. The driver recognizes the pattern (85 °C together with the reserved byte 0x0C) and returns ESP_ERR_INVALID_RESPONSE instead of a plausible-looking value, and logs the reason. Use externally powered sensors with the RMT backend, or add a transistor-based strong pull-up to the board.

Pull-up resistor

The internal pull-up of the ESP32 is about 47 kΩ and does not meet the requirements of the 1-Wire bus. It works with one or two sensors on short wires, but a real application needs an external 4.7 kΩ resistor between the data line and 3.3 V.

Resolution

The DS1822, DS18B20, DS1825 and DS28EA00 convert with 9, 10, 11 or 12 bits of resolution, which changes the conversion time and the step of the result:

Resolution

Step

Conversion time

9 bit

0.5 °C

93.75 ms

10 bit

0.25 °C

187.5 ms

11 bit

0.125 °C

375 ms

12 bit

0.0625 °C

750 ms

ds18x20_set_resolution() writes the new value to the scratchpad and copies it to the EEPROM of the sensor, so it survives a power cycle. ds18x20_get_resolution() reads the value the sensor currently uses. The driver masks the bits that are undefined at the configured resolution, so a 9-bit sensor never reports a step finer than 0.5 °C.

ds18x20_measure() always waits for the longest conversion, 750 ms, so the code works with any resolution. The DS18S20 has a fixed 9-bit resolution, and the MAX31850 has a fixed 14-bit one: both functions return ESP_ERR_NOT_SUPPORTED for them.

Examples

  • examples/default scans the bus, takes the first sensor it finds, prints its address and family, and reads the temperature once a second. It does not need the address of the sensor.

  • examples/multi scans the bus and reads every sensor it finds, several times per second.

Defines

DS18X20_ANY

An address value which can be used to indicate “any device on the bus”.

Typedefs

typedef onewire_addr_t ds18x20_addr_t

Address of a DS18x20 device on the bus.

Enums

enum ds18x20_family_id_t

Family ID (lower address byte) of sensors.

Values:

enumerator DS18X20_FAMILY_DS18S20

DS1820/DS18S20 9-bit +/-0.5°C.

enumerator DS18X20_FAMILY_DS1822

DS1822 9-12 bit, 0.0625°C.

enumerator DS18X20_FAMILY_DS18B20

DS18B20 9-12 bit, 0.0625°C.

enumerator DS18X20_FAMILY_MAX31850

MAX31850 14-bit +/-0.25°C.

enumerator DS18X20_FAMILY_DS1825

DS1825 9-12 bit (same family code as MAX31850)

enumerator DS18X20_FAMILY_DS28EA00

DS28EA00 9-12 bit, 0.0625°C.

enumerator DS18X20_FAMILY_MAX31888

MAX31888 13-16 bit, 0.005°C (not supported yet)

enum ds18x20_resolution_t

Resolution of the temperature conversion (DS1822/DS18B20/DS1825/DS28EA00)

Values:

enumerator DS18X20_RESOLUTION_9_BIT

0.5°C, 93.75 ms

enumerator DS18X20_RESOLUTION_10_BIT

0.25°C, 187.5 ms

enumerator DS18X20_RESOLUTION_11_BIT

0.125°C, 375 ms

enumerator DS18X20_RESOLUTION_12_BIT

0.0625°C, 750 ms

Functions

esp_err_t ds18x20_bus_init(gpio_num_t pin)

Prepare the 1-Wire bus on a pin.

The driver can be built on top of the bit-banging onewire component or on top of the RMT-based espressif/onewire_bus component, depending on CONFIG_DS18X20_ONEWIRE_BACKEND. In the first case the function only validates the pin: the bus is driven directly by the bit-banging code.

In the second case the bus handle is created on demand, so calling this function is not required: it only lets the application reserve the bus before the first operation and detect the failure at a known place. At most CONFIG_DS18X20_MAX_BUSES buses can be open at the same time.

Parameters:

pin – The GPIO pin connected to the DS18x20 bus

Returns:

ESP_OK on success ESP_ERR_INVALID_ARG if the pin is not usable ESP_ERR_NO_MEM if there is no room for another bus other error codes of the underlying backend

esp_err_t ds18x20_bus_free(gpio_num_t pin)

Release the 1-Wire bus on a pin.

With the bit-banging backend there is nothing to release: the function only validates the pin. With the RMT-based backend the bus handle is destroyed, which frees the RMT channels; the next operation on the pin creates the bus again.

Parameters:

pin – The GPIO pin connected to the DS18x20 bus

Returns:

ESP_OK on success ESP_ERR_INVALID_ARG if the pin is not usable ESP_ERR_NOT_FOUND if the bus on the pin was not open

esp_err_t ds18x20_scan_devices(gpio_num_t pin, ds18x20_addr_t *addr_list, size_t addr_count, size_t *found)

Find the addresses of all ds18x20 devices on the bus.

Scans the bus for all devices and places their addresses in the supplied array. If there are more than addr_count devices on the bus, only the first addr_count are recorded.

Parameters:
  • pin – The GPIO pin connected to the DS18x20 bus

  • addr_list – A pointer to an array of ds18x20_addr_t values. This will be populated with the addresses of the found devices.

  • addr_count – Number of slots in the addr_list array. At most this many addresses will be returned.

  • found – The number of devices found. Note that this may be less than, equal to, or more than addr_count, depending on how many ds18x20 devices are attached to the bus.

Returns:

ESP_OK if the command was successfully issued

esp_err_t ds18x20_measure(gpio_num_t pin, ds18x20_addr_t addr, bool wait)

Tell one or more sensors to perform a temperature measurement and conversion (CONVERT_T) operation.

This operation can take up to 750ms to complete.

If wait=true, this routine will automatically drive the pin high for the necessary 750ms after issuing the command to ensure parasitically-powered devices have enough power to perform the conversion operation (for non-parasitically-powered devices, this is not necessary but does not hurt). If wait=false, this routine will drive the pin high, but will then return immediately. It is up to the caller to wait the requisite time and then depower the bus using onewire_depower() or by issuing another command once conversion is done.

Only the bit-banging backend can hold the bus with a strong pull-up, which parasitically-powered devices need during the conversion: it drives the pin as a push-pull output for the whole wait_ms. The RMT-based backend has no strong pull-up at all, so such devices require an external transistor switched pull-up; with wait=false neither backend drives the bus.

Parameters:
  • pin – The GPIO pin connected to the DS18x20 device

  • addr – The 64-bit address of the device on the bus. This can be set to DS18X20_ANY to send the command to all devices on the bus at the same time.

  • wait – Whether to wait for the necessary 750ms for the ds18x20 to finish performing the conversion before returning to the caller (You will normally want to do this).

Returns:

ESP_OK if the command was successfully issued

esp_err_t ds18x20_read_temperature(gpio_num_t pin, ds18x20_addr_t addr, float *temperature)

Read the value from the last CONVERT_T operation.

This should be called after ds18x20_measure() to fetch the result of the temperature measurement.

Parameters:
  • pin – The GPIO pin connected to the DS18x20 device

  • addr – The 64-bit address of the device to read. This can be set to DS18X20_ANY to read any device on the bus (but note that this will only work if there is exactly one device connected, or they will corrupt each others’ transmissions)

  • temperature – The temperature in degrees Celsius

Returns:

ESP_OK if the command was successfully issued

esp_err_t ds18b20_read_temperature(gpio_num_t pin, ds18x20_addr_t addr, float *temperature)

Read the value from the last CONVERT_T operation (DS18B20/DS1822 version).

This should be called after ds18x20_measure() to fetch the result of the temperature measurement.

Parameters:
  • pin – The GPIO pin connected to the DS18B20/DS1822 device

  • addr – The 64-bit address of the device to read. This can be set to DS18X20_ANY to read any device on the bus (but note that this will only work if there is exactly one device connected, or they will corrupt each others’ transmissions)

  • temperature – The temperature in degrees Celsius

Returns:

ESP_OK if the command was successfully issued

esp_err_t ds18s20_read_temperature(gpio_num_t pin, ds18x20_addr_t addr, float *temperature)

Read the value from the last CONVERT_T operation (DS18S20 version).

This should be called after ds18x20_measure() to fetch the result of the temperature measurement.

Parameters:
  • pin – The GPIO pin connected to the DS18S20 device

  • addr – The 64-bit address of the device to read. This can be set to DS18X20_ANY to read any device on the bus (but note that this will only work if there is exactly one device connected, or they will corrupt each others’ transmissions)

  • temperature – The temperature in degrees Celsius

Returns:

ESP_OK if the command was successfully issued

esp_err_t max31850_read_temperature(gpio_num_t pin, ds18x20_addr_t addr, float *temperature)

Read the value from the last CONVERT_T operation (MAX31850 version).

This should be called after ds18x20_measure() to fetch the result of the temperature measurement.

Parameters:
  • pin – The GPIO pin connected to the MAX31850 device

  • addr – The 64-bit address of the device to read. This can be set to DS18X20_ANY to read any device on the bus (but note that this will only work if there is exactly one device connected, or they will corrupt each others’ transmissions)

  • temperature – The temperature in degrees Celsius

Returns:

ESP_OK if the command was successfully issued

esp_err_t ds18x20_read_temp_multi(gpio_num_t pin, ds18x20_addr_t *addr_list, size_t addr_count, float *result_list)

Read the value from the last CONVERT_T operation for multiple devices.

This should be called after ds18x20_measure() to fetch the result of the temperature measurement.

Parameters:
  • pin – The GPIO pin connected to the ds18x20 bus

  • addr_list – A list of addresses for devices to read.

  • addr_count – The number of entries in addr_list.

  • result_list – An array of floats to hold the returned temperature values. It should have at least addr_count entries.

Returns:

ESP_OK if all temperatures were fetched successfully

esp_err_t ds18x20_measure_and_read(gpio_num_t pin, ds18x20_addr_t addr, float *temperature)

Perform a ds18x20_measure() followed by ds18x20_read_temperature()

Parameters:
  • pin – The GPIO pin connected to the DS18x20 device

  • addr – The 64-bit address of the device to read. This can be set to DS18X20_ANY to read any device on the bus (but note that this will only work if there is exactly one device connected, or they will corrupt each others’ transmissions)

  • temperature – The temperature in degrees Celsius

esp_err_t ds18s20_measure_and_read(gpio_num_t pin, ds18x20_addr_t addr, float *temperature)

Perform a ds18x20_measure() followed by ds18s20_read_temperature()

Parameters:
  • pin – The GPIO pin connected to the DS18S20 device

  • addr – The 64-bit address of the device to read. This can be set to DS18X20_ANY to read any device on the bus (but note that this will only work if there is exactly one device connected, or they will corrupt each others’ transmissions)

  • temperature – The temperature in degrees Celsius

esp_err_t ds18b20_measure_and_read(gpio_num_t pin, ds18x20_addr_t addr, float *temperature)

Perform a ds18x20_measure() followed by ds18b20_read_temperature()

Parameters:
  • pin – The GPIO pin connected to the DS18B20 device

  • addr – The 64-bit address of the device to read. This can be set to DS18X20_ANY to read any device on the bus (but note that this will only work if there is exactly one device connected, or they will corrupt each others’ transmissions)

  • temperature – The temperature in degrees Celsius

esp_err_t max31850_measure_and_read(gpio_num_t pin, ds18x20_addr_t addr, float *temperature)

Perform a ds18x20_measure() followed by max31850_read_temperature()

Parameters:
  • pin – The GPIO pin connected to the MAX31850 device

  • addr – The 64-bit address of the device to read. This can be set to DS18X20_ANY to read any device on the bus (but note that this will only work if there is exactly one device connected, or they will corrupt each others’ transmissions)

  • temperature – The temperature in degrees Celsius

esp_err_t ds18x20_measure_and_read_multi(gpio_num_t pin, ds18x20_addr_t *addr_list, size_t addr_count, float *result_list)

Perform a ds18x20_measure() followed by ds18x20_read_temp_multi()

Parameters:
  • pin – The GPIO pin connected to the DS18x20 bus

  • addr_list – A list of addresses for devices to read.

  • addr_count – The number of entries in addr_list.

  • result_list – An array of floats to hold the returned temperature values. It should have at least addr_count entries.

Returns:

ESP_OK if all temperatures were fetched successfully

esp_err_t ds18x20_read_scratchpad(gpio_num_t pin, ds18x20_addr_t addr, uint8_t *buffer)

Read the scratchpad data for a particular ds18x20 device.

This is not generally necessary to do directly. It is done automatically as part of ds18x20_read_temperature().

Parameters:
  • pin – The GPIO pin connected to the DS18X20 device

  • addr – The 64-bit address of the device to read. This can be set to DS18X20_ANY to read any device on the bus (but note that this will only work if there is exactly one device connected, or they will corrupt each others’ transmissions)

  • buffer – An 8-byte buffer to hold the read data.

Returns:

ESP_OK if the command was successfully issued

esp_err_t ds18x20_write_scratchpad(gpio_num_t pin, ds18x20_addr_t addr, uint8_t *buffer)

Write the scratchpad data for a particular ds18x20 device.

Parameters:
  • pin – The GPIO pin connected to the DS18x20 device

  • addr – The 64-bit address of the device to write. This can be set to DS18X20_ANY to read any device on the bus (but note that this will only work if there is exactly one device connected, or they will corrupt each others’ transmissions)

  • buffer – An 3-byte buffer to hold the data to write

Returns:

ESP_OK if the command was successfully issued

esp_err_t ds18x20_copy_scratchpad(gpio_num_t pin, ds18x20_addr_t addr)

Issue the copy scratchpad command, copying current scratchpad to EEPROM.

Parameters:
  • pin – The GPIO pin connected to the DS18x20 device

  • addr – The 64-bit address of the device to command. This can be set to DS18X20_ANY to read any device on the bus (but note that this will only work if there is exactly one device connected, or they will corrupt each others’ transmissions)

Returns:

ESP_OK if the command was successfully issued

esp_err_t ds18x20_get_resolution(gpio_num_t pin, ds18x20_addr_t addr, ds18x20_resolution_t *resolution)

Read the resolution of the temperature conversion.

The resolution is read from the configuration register of the scratchpad, so it is the value the sensor currently uses, not the one that will be used after the next power cycle (see ds18x20_set_resolution()).

Parameters:
  • pin – The GPIO pin connected to the DS18x20 bus

  • addr – The 64-bit address of the device

  • resolution – Where to store the resolution

Returns:

ESP_OK on success ESP_ERR_INVALID_ARG if an argument is invalid ESP_ERR_NOT_SUPPORTED if the sensor has a fixed resolution other error codes of ds18x20_read_scratchpad()

esp_err_t ds18x20_set_resolution(gpio_num_t pin, ds18x20_addr_t addr, ds18x20_resolution_t resolution)

Set the resolution of the temperature conversion.

The resolution is written to the scratchpad and copied to the EEPROM of the sensor, so it survives a power cycle. The conversion takes 93.75, 187.5, 375 or 750 ms depending on the resolution, and ds18x20_measure() always waits for the longest one.

The DS18S20 has a fixed 9-bit resolution, and the MAX31850 is a thermocouple converter with a fixed 14-bit resolution, so ESP_ERR_NOT_SUPPORTED is returned for them. The DS1825 shares the family code 0x3B with the MAX31850 and is therefore rejected as well: use ds18x20_write_scratchpad() for it if you need a different resolution.

Parameters:
  • pin – The GPIO pin connected to the DS18x20 bus

  • addr – The 64-bit address of the device

  • resolution – The requested resolution

Returns:

ESP_OK on success ESP_ERR_INVALID_ARG if an argument is invalid ESP_ERR_NOT_SUPPORTED if the sensor has a fixed resolution ESP_ERR_INVALID_RESPONSE if the scratchpad could not be read other error codes of the underlying commands