Interface definitions for the Maxim Integrated DS18B20 Programmable Resolution 1-Wire Digital Thermometer device. More...

#include "owb.h"

Data Structures
struct	DS18B20_Info
	Structure containing information related to a single DS18B20 device connected via a 1-Wire bus. More...

Enumerations
enum	DS18B20_ERROR { DS18B20_ERROR_UNKNOWN = -1, DS18B20_OK = 0, DS18B20_ERROR_DEVICE, DS18B20_ERROR_CRC, DS18B20_ERROR_OWB, DS18B20_ERROR_NULL }
	Success and error codes. More...

enum	DS18B20_RESOLUTION { DS18B20_RESOLUTION_INVALID = -1, DS18B20_RESOLUTION_9_BIT = 9, DS18B20_RESOLUTION_10_BIT = 10, DS18B20_RESOLUTION_11_BIT = 11, DS18B20_RESOLUTION_12_BIT = 12 }
	Symbols for the supported temperature resolution of the device. More...

Functions
DS18B20_Info *	ds18b20_malloc (void)
	Construct a new device info instance. New instance should be initialised before calling other functions. More...

void	ds18b20_free (DS18B20_Info **ds18b20_info)
	Delete an existing device info instance. More...

void	ds18b20_init (DS18B20_Info ds18b20_info, const OneWireBus bus, OneWireBus_ROMCode rom_code)
	Initialise a device info instance with the specified GPIO. More...

void	ds18b20_init_solo (DS18B20_Info ds18b20_info, const OneWireBus bus)
	Initialise a device info instance as a solo device on the bus. More...

void	ds18b20_use_crc (DS18B20_Info *ds18b20_info, bool use_crc)
	Enable or disable use of CRC checks on device communications. More...

bool	ds18b20_set_resolution (DS18B20_Info *ds18b20_info, DS18B20_RESOLUTION resolution)
	Set temperature measurement resolution. More...

DS18B20_RESOLUTION	ds18b20_read_resolution (DS18B20_Info *ds18b20_info)
	Update and return the current temperature measurement resolution from the device. More...

OneWireBus_ROMCode	ds18b20_read_rom (DS18B20_Info *ds18b20_info)
	Read 64-bit ROM code from device - only works when there is a single device on the bus. More...

bool	ds18b20_convert (const DS18B20_Info *ds18b20_info)
	Start a temperature measurement conversion on a single device. More...

void	ds18b20_convert_all (const OneWireBus *bus)
	Start temperature conversion on all connected devices. More...

float	ds18b20_wait_for_conversion (const DS18B20_Info *ds18b20_info)
	Wait for the maximum conversion time according to the current resolution of the device. In external power mode, the device or devices can signal when conversion has completed. In parasitic power mode, this is not possible, so a pre-calculated delay is performed. More...

DS18B20_ERROR	ds18b20_read_temp (const DS18B20_Info ds18b20_info, float value)
	Read last temperature measurement from device. More...

DS18B20_ERROR	ds18b20_convert_and_read_temp (const DS18B20_Info ds18b20_info, float value)
	Convert, wait and read current temperature from device. More...

DS18B20_ERROR	ds18b20_check_for_parasite_power (const OneWireBus bus, bool present)
	Check OneWire bus for presence of parasitic-powered devices. More...

Detailed Description

Interface definitions for the Maxim Integrated DS18B20 Programmable Resolution 1-Wire Digital Thermometer device.

This component provides structures and functions that are useful for communicating with DS18B20 devices connected via a Maxim Integrated 1-Wire® bus.

Enumeration Type Documentation

enum DS18B20_ERROR

Success and error codes.

Enumerator
DS18B20_ERROR_UNKNOWN	An unknown error occurred, or the value was not set.
DS18B20_OK	Success.
DS18B20_ERROR_DEVICE	A device error occurred.
DS18B20_ERROR_CRC	A CRC error occurred.
DS18B20_ERROR_OWB	A One Wire Bus error occurred.
DS18B20_ERROR_NULL	A parameter or value is NULL.

enum DS18B20_RESOLUTION

Symbols for the supported temperature resolution of the device.

Enumerator
DS18B20_RESOLUTION_INVALID	Invalid resolution.
DS18B20_RESOLUTION_9_BIT	9-bit resolution, LSB bits 2,1,0 undefined
DS18B20_RESOLUTION_10_BIT	10-bit resolution, LSB bits 1,0 undefined
DS18B20_RESOLUTION_11_BIT	11-bit resolution, LSB bit 0 undefined
DS18B20_RESOLUTION_12_BIT	12-bit resolution (default)

Function Documentation

DS18B20_Info* ds18b20_malloc ( void )

Construct a new device info instance. New instance should be initialised before calling other functions.

Returns: Pointer to new device info instance, or NULL if it cannot be created.

void ds18b20_free ( DS18B20_Info ** ds18b20_info )

Delete an existing device info instance.

Parameters

[in]	ds18b20_info	Pointer to device info instance.
[in,out]	ds18b20_info	Pointer to device info instance that will be freed and set to NULL.

void ds18b20_init	(	DS18B20_Info *	ds18b20_info,
		const OneWireBus *	bus,
		OneWireBus_ROMCode	rom_code
	)

Initialise a device info instance with the specified GPIO.

Parameters

[in]	ds18b20_info	Pointer to device info instance.
[in]	bus	Pointer to initialised 1-Wire bus instance.
[in]	rom_code	Device-specific ROM code to identify a device on the bus.

void ds18b20_init_solo	(	DS18B20_Info *	ds18b20_info,
		const OneWireBus *	bus
	)

Initialise a device info instance as a solo device on the bus.

This is subject to the requirement that this device is the ONLY device on the bus. This allows for faster commands to be used without ROM code addressing.

NOTE: if additional devices are added to the bus, operation will cease to work correctly.

Parameters

[in]	ds18b20_info	Pointer to device info instance.
[in]	bus	Pointer to initialised 1-Wire bus instance.

void ds18b20_use_crc	(	DS18B20_Info *	ds18b20_info,
		bool	use_crc
	)

Enable or disable use of CRC checks on device communications.

Parameters

[in]	ds18b20_info	Pointer to device info instance.
[in]	use_crc	True to enable CRC checks, false to disable.

bool ds18b20_set_resolution	(	DS18B20_Info *	ds18b20_info,
		DS18B20_RESOLUTION	resolution
	)

Set temperature measurement resolution.

This programs the hardware to the specified resolution and sets the cached value to be the same. If the program fails, the value currently in hardware is used to refresh the cache.

Parameters

[in]	ds18b20_info	Pointer to device info instance.
[in]	resolution	Selected resolution.

Returns: True if successful, otherwise false.

DS18B20_RESOLUTION ds18b20_read_resolution ( DS18B20_Info * ds18b20_info )

Update and return the current temperature measurement resolution from the device.

Parameters

[in] ds18b20_info Pointer to device info instance.

Returns: The currently configured temperature measurement resolution.

OneWireBus_ROMCode ds18b20_read_rom ( DS18B20_Info * ds18b20_info )

Read 64-bit ROM code from device - only works when there is a single device on the bus.

Parameters

[in] ds18b20_info Pointer to device info instance.

Returns: The 64-bit value read from the device's ROM.

bool ds18b20_convert ( const DS18B20_Info * ds18b20_info )

Start a temperature measurement conversion on a single device.

Parameters

[in] ds18b20_info Pointer to device info instance.

void ds18b20_convert_all ( const OneWireBus * bus )

Start temperature conversion on all connected devices.

This should be followed by a sufficient delay to ensure all devices complete their conversion before the measurements are read.

Parameters

[in] bus Pointer to initialised bus instance.

float ds18b20_wait_for_conversion ( const DS18B20_Info * ds18b20_info )

Wait for the maximum conversion time according to the current resolution of the device. In external power mode, the device or devices can signal when conversion has completed. In parasitic power mode, this is not possible, so a pre-calculated delay is performed.

Parameters

[in] ds18b20_info Pointer to device info instance.

Returns: An estimate of the time elapsed, in milliseconds. Actual elapsed time may be greater.

DS18B20_ERROR ds18b20_read_temp	(	const DS18B20_Info *	ds18b20_info,
		float *	value
	)

Read last temperature measurement from device.

This is typically called after ds18b20_start_mass_conversion(), provided enough time has elapsed to ensure that all devices have completed their conversions.

Parameters

[in]	ds18b20_info	Pointer to device info instance. Must be initialised first.
[out]	value	Pointer to the measurement value returned by the device, in degrees Celsius.

Returns: DS18B20_OK if read is successful, otherwise error.

DS18B20_ERROR ds18b20_convert_and_read_temp	(	const DS18B20_Info *	ds18b20_info,
		float *	value
	)

Convert, wait and read current temperature from device.

Parameters

[in]	ds18b20_info	Pointer to device info instance. Must be initialised first.
[out]	value	Pointer to the measurement value returned by the device, in degrees Celsius.

Returns: DS18B20_OK if read is successful, otherwise error.

DS18B20_ERROR ds18b20_check_for_parasite_power	(	const OneWireBus *	bus,
		bool *	present
	)

Check OneWire bus for presence of parasitic-powered devices.

Parameters

[in]	bus	Pointer to initialised bus instance.
[out]	present	Result value, true if a parasitic-powered device was detected.

Returns: DS18B20_OK if check is successful, otherwise error.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation