ds18x20 - Driver for DS18B20/DS18S20¶

group ds18x20

ESP-IDF driver for the DS18S20/DS18B20 one-wire temperature sensor ICs.

Ported from esp-open-rtos

foogod@gmail.com

unclerus@gmail.com

BSD Licensed as described in the file LICENSE

Defines

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

DS18B20_FAMILY_ID¶: Family ID (lower address byte) of DS18B20 sensors.

DS18S20_FAMILY_ID¶: Family ID (lower address byte) of DS18S20 sensors.

Typedefs

typedef onewire_addr_t ds18x20_addr_t¶

Functions

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.

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 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 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