esp-open-rtos/extras/ds18b20/ds18b20.h

#ifndef DRIVER_DS18B20_H_
#define DRIVER_DS18B20_H_

#include "onewire/onewire.h"

/** @file ds18b20.h
 *
 *  Communicate with the DS18B20 family of one-wire temperature sensor ICs.
 *
 */

typedef onewire_addr_t ds18b20_addr_t;

/** An address value which can be used to indicate "any device on the bus" */
#define DS18B20_ANY ONEWIRE_NONE

/** Find the addresses of all DS18B20 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.
 *
 *  @param pin         The GPIO pin connected to the DS18B20 bus
 *  @param addr_list   A pointer to an array of ds18b20_addr_t values.  This
 *                     will be populated with the addresses of the found
 *                     devices.
 *  @param addr_count  Number of slots in the `addr_list` array.  At most this
 *                     many addresses will be returned.
 *
 *  @returns The number of devices found.  Note that this may be less than,
 *  equal to, or more than `addr_count`, depending on how many DS18B20 devices
 *  are attached to the bus.
 */
int ds18b20_scan_devices(int pin, ds18b20_addr_t *addr_list, int addr_count);

/** 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.
 *
 *  @param pin   The GPIO pin connected to the DS18B20 device
 *  @param addr  The 64-bit address of the device on the bus.  This can be set
 *               to ::DS18B20_ANY to send the command to all devices on the bus
 *               at the same time.
 *  @param wait  Whether to wait for the necessary 750ms for the DS18B20 to
 *               finish performing the conversion before returning to the
 *               caller (You will normally want to do this).
 *
 *  @returns `true` if the command was successfully issued, or `false` on error.
 */
bool ds18b20_measure(int pin, ds18b20_addr_t addr, bool wait);

/** Read the value from the last CONVERT_T operation.
 *
 *  This should be called after ds18b20_measure() to fetch the result of the
 *  temperature measurement.
 *
 *  @param pin     The GPIO pin connected to the DS18B20 device
 *  @param addr    The 64-bit address of the device to read.  This can be set
 *                 to ::DS18B20_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 The temperature in degrees Celsius, or NaN if there was an error.
 */
float ds18b20_read_temperature(int pin, ds18b20_addr_t addr);

/** Read the value from the last CONVERT_T operation for multiple devices.
 *
 *  This should be called after ds18b20_measure() to fetch the result of the
 *  temperature measurement.
 *
 *  @param pin         The GPIO pin connected to the DS18B20 bus
 *  @param addr_list   A list of addresses for devices to read.
 *  @param addr_count  The number of entries in `addr_list`.
 *  @param result_list An array of floats to hold the returned temperature
 *                     values.  It should have at least `addr_count` entries.
 *
 *  @returns `true` if all temperatures were fetched successfully, or `false`
 *  if one or more had errors (the temperature for erroring devices will be
 *  returned as NaN).
 */
bool ds18b20_read_temp_multi(int pin, ds18b20_addr_t *addr_list, int addr_count, float *result_list);

/** Perform a ds18b20_measure() followed by ds18b20_read_temperature()
 *
 *  @param pin     The GPIO pin connected to the DS18B20 device
 *  @param addr    The 64-bit address of the device to read.  This can be set
 *                 to ::DS18B20_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 The temperature in degrees Celsius, or NaN if there was an error.
 */
float ds18b20_measure_and_read(int pin, ds18b20_addr_t addr);

/** Perform a ds18b20_measure() followed by ds18b20_read_temp_multi()
 *
 *  @param pin         The GPIO pin connected to the DS18B20 bus
 *  @param addr_list   A list of addresses for devices to read.
 *  @param addr_count  The number of entries in `addr_list`.
 *  @param result_list An array of floats to hold the returned temperature
 *                     values.  It should have at least `addr_count` entries.
 *
 *  @returns `true` if all temperatures were fetched successfully, or `false`
 *  if one or more had errors (the temperature for erroring devices will be
 *  returned as NaN).
 */
bool ds18b20_measure_and_read_multi(int pin, ds18b20_addr_t *addr_list, int addr_count, float *result_list);

/** Read the scratchpad data for a particular DS18B20 device.
 *
 *  This is not generally necessary to do directly.  It is done automatically
 *  as part of ds18b20_read_temperature().
 *
 *  @param pin     The GPIO pin connected to the DS18B20 device
 *  @param addr    The 64-bit address of the device to read.  This can be set
 *                 to ::DS18B20_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)
 *  @param buffer  An 8-byte buffer to hold the read data.
 *
 *  @returns `true` if the data was read successfully, or `false` on error.
 */
bool ds18b20_read_scratchpad(int pin, ds18b20_addr_t addr, uint8_t *buffer);

// The following are obsolete/deprecated APIs

typedef struct {
    uint8_t id;
    float value;
} ds_sensor_t;

// Scan all ds18b20 sensors on bus and return its amount.
// Result are saved in array of ds_sensor_t structure.
uint8_t ds18b20_read_all(uint8_t pin, ds_sensor_t *result);

// This method is just to demonstrate how to read 
// temperature from single dallas chip.
float ds18b20_read_single(uint8_t pin);

#endif