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 |
|---|---|---|---|---|
|
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 |
|
DS1822 |
9–12 bit |
0.0625 °C |
Same register layout as the DS18B20 |
|
DS18B20 |
9–12 bit |
0.0625 °C |
The most common part, including the waterproof probes |
|
DS1825 |
9–12 bit |
0.0625 °C |
Shares the family code with the MAX31850 |
|
MAX31850, MAX31851 |
14 bit |
0.0625 °C |
Thermocouple-to-digital converter |
|
DS28EA00 |
9–12 bit |
0.0625 °C |
Sequence detect and PIO pins, both unused by the driver |
|
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.
|
|
|
|---|---|---|
Implementation |
||
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 |
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/defaultscans 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/multiscans 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_buscomponent, depending onCONFIG_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_BUSESbuses can be open at the same time.
- Parameters:
pin – The GPIO pin connected to the DS18x20 bus
- Returns:
ESP_OKon successESP_ERR_INVALID_ARGif the pin is not usableESP_ERR_NO_MEMif 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_OKon successESP_ERR_INVALID_ARGif the pin is not usableESP_ERR_NOT_FOUNDif 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_countdevices on the bus, only the firstaddr_countare 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_listarray. 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_OKif 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). Ifwait=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; withwait=falseneither 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_OKif 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_OKif 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_OKif 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_OKif 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_OKif 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_countentries.- Returns:
ESP_OKif 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_countentries.- Returns:
ESP_OKif 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_OKif 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_OKif 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_OKif 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_OKon successESP_ERR_INVALID_ARGif an argument is invalidESP_ERR_NOT_SUPPORTEDif 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_SUPPORTEDis 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_OKon successESP_ERR_INVALID_ARGif an argument is invalidESP_ERR_NOT_SUPPORTEDif the sensor has a fixed resolutionESP_ERR_INVALID_RESPONSEif the scratchpad could not be read other error codes of the underlying commands