Implement new ds18b20 APIs

extras/ds18b20/ds18b20.h

@@ -1,6 +1,139 @@
 #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;