150 lines
6.5 KiB
C
150 lines
6.5 KiB
C
#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
|