DS18x20 1-Wire temperature sensor device. More...

Public Member Functions
	device (idfxx::gpio pin, onewire::address addr=onewire::address::any())
	Constructs a validated device.

	device (const device &)=default

	device (device &&)=default

device &	operator= (const device &)=default

device &	operator= (device &&)=default

constexpr bool	operator== (const device &) const noexcept=default
	Compares two devices for equality.

constexpr idfxx::gpio	pin () const
	Returns the GPIO pin.

constexpr onewire::address	addr () const
	Returns the device address.

void	measure (bool wait=true)
	Initiates a temperature conversion.

thermo::millicelsius	read_temperature () const
	Reads the last converted temperature.

thermo::millicelsius	measure_and_read ()
	Measures and reads the temperature in a single operation.

result< void >	try_measure (bool wait=true)
	Initiates a temperature conversion.

result< thermo::millicelsius >	try_read_temperature () const
	Reads the last converted temperature.

result< thermo::millicelsius >	try_measure_and_read ()
	Measures and reads the temperature in a single operation.

void	set_resolution (resolution res)
	Sets the ADC resolution.

resolution	get_resolution () const
	Gets the current ADC resolution.

result< void >	try_set_resolution (resolution res)
	Sets the ADC resolution.

result< resolution >	try_get_resolution () const
	Gets the current ADC resolution.

std::array< uint8_t, 9 >	read_scratchpad () const
	Reads the 9-byte scratchpad memory.

void	write_scratchpad (std::span< const uint8_t, 3 > data)
	Writes 3 bytes to the scratchpad (TH, TL, configuration register).

void	copy_scratchpad ()
	Copies the scratchpad to EEPROM.

result< std::array< uint8_t, 9 > >	try_read_scratchpad () const
	Reads the 9-byte scratchpad memory.

result< void >	try_write_scratchpad (std::span< const uint8_t, 3 > data)
	Writes 3 bytes to the scratchpad (TH, TL, configuration register).

result< void >	try_copy_scratchpad ()
	Copies the scratchpad to EEPROM.

Static Public Member Functions
static result< device >	make (idfxx::gpio pin, onewire::address addr=onewire::address::any())
	Creates a validated device.

Friends
result< std::vector< device > >	try_scan_devices (idfxx::gpio pin, size_t max_devices)
	Scans for DS18x20 devices on a 1-Wire bus.

Detailed Description

DS18x20 1-Wire temperature sensor device.

Lightweight, copyable value type representing a specific sensor on a 1-Wire bus. Each device is identified by its GPIO pin and 64-bit ROM address.

For single-sensor buses, use onewire::address::any() (the default) to skip ROM matching:

auto dev = idfxx::ds18x20::device(idfxx::gpio_4);

thermo::millicelsius temp = dev.measure_and_read();

idfxx::ds18x20::device

DS18x20 1-Wire temperature sensor device.

Definition ds18x20.hpp:154

idfxx::gpio_4

constexpr gpio gpio_4

Definition gpio.hpp:812

idfxx::result

std::expected< T, std::error_code > result

result type wrapping a value or error code.

Definition error.hpp:120

For multi-sensor buses, first scan for devices:

auto devices = idfxx::ds18x20::scan_devices(idfxx::gpio_4);
for (auto& dev : devices) {
    thermo::millicelsius temp = dev.measure_and_read();
}

Definition at line 154 of file ds18x20.hpp.

Constructor & Destructor Documentation

◆ device() [1/3]

idfxx::ds18x20::device::device	(	idfxx::gpio	pin,
		onewire::address	addr = `onewire::address::any()`
	)

explicit

Constructs a validated device.

Parameters

pin	GPIO pin connected to the 1-Wire bus.
addr	Device address (default: onewire::address::any() for single-device buses).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error if the pin is not connected.

◆ device() [2/3]

idfxx::ds18x20::device::device ( const device & )

default

◆ device() [3/3]

idfxx::ds18x20::device::device ( device && )

default

Member Function Documentation

◆ addr()

constexpr onewire::address idfxx::ds18x20::device::addr ( ) const

inlineconstexpr

Returns the device address.

Definition at line 191 of file ds18x20.hpp.

◆ copy_scratchpad()

void idfxx::ds18x20::device::copy_scratchpad ( )

inline

Copies the scratchpad to EEPROM.

Persists the TH, TL, and configuration register values so they survive power cycles.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 326 of file ds18x20.hpp.

References try_copy_scratchpad(), and idfxx::unwrap().

◆ get_resolution()

resolution idfxx::ds18x20::device::get_resolution ( ) const

inline

Gets the current ADC resolution.

Reads the scratchpad and extracts the configuration register.

Returns: The current resolution setting.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 274 of file ds18x20.hpp.

References try_get_resolution(), and idfxx::unwrap().

◆ make()

static result< device > idfxx::ds18x20::device::make	(	idfxx::gpio	pin,
		onewire::address	addr = `onewire::address::any()`
	)

static

Creates a validated device.

Parameters

pin	GPIO pin connected to the 1-Wire bus.
addr	Device address (default: onewire::address::any() for single-device buses).

Returns: The device, or an error if the pin is not connected.

Return values

invalid_state If the pin is not connected.

◆ measure()

void idfxx::ds18x20::device::measure ( bool wait = true )

inline

Initiates a temperature conversion.

Parameters

wait	If true, blocks until conversion completes (up to 750ms). If false, returns immediately and the caller must wait.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 203 of file ds18x20.hpp.

References try_measure(), and idfxx::unwrap().

◆ measure_and_read()

thermo::millicelsius idfxx::ds18x20::device::measure_and_read ( )

inline

Measures and reads the temperature in a single operation.

Sends a convert command, waits for completion, then reads the result.

Returns: The measured temperature.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 223 of file ds18x20.hpp.

References try_measure_and_read(), and idfxx::unwrap().

◆ operator=() [1/2]

device & idfxx::ds18x20::device::operator= ( const device & )

default

◆ operator=() [2/2]

device & idfxx::ds18x20::device::operator= ( device && )

default

◆ operator==()

constexpr bool idfxx::ds18x20::device::operator== ( const device & ) const

constexprdefaultnoexcept

Compares two devices for equality.

◆ pin()

constexpr idfxx::gpio idfxx::ds18x20::device::pin ( ) const

inlineconstexpr

Returns the GPIO pin.

Definition at line 188 of file ds18x20.hpp.

◆ read_scratchpad()

std::array< uint8_t, 9 > idfxx::ds18x20::device::read_scratchpad ( ) const

inline

Reads the 9-byte scratchpad memory.

Returns: The scratchpad contents [temp_lsb, temp_msb, th, tl, config, reserved, reserved, reserved, crc].

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 306 of file ds18x20.hpp.

References try_read_scratchpad(), and idfxx::unwrap().

◆ read_temperature()

thermo::millicelsius idfxx::ds18x20::device::read_temperature ( ) const

inline

Reads the last converted temperature.

Returns: The measured temperature.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 212 of file ds18x20.hpp.

References try_read_temperature(), and idfxx::unwrap().

◆ set_resolution()

void idfxx::ds18x20::device::set_resolution ( resolution res )

inline

Sets the ADC resolution.

Reads the current scratchpad, modifies the configuration register, and writes it back. Only applicable to DS18B20 sensors.

Parameters

res	The desired resolution.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 263 of file ds18x20.hpp.

References try_set_resolution(), and idfxx::unwrap().

◆ try_copy_scratchpad()

result< void > idfxx::ds18x20::device::try_copy_scratchpad ( )

Copies the scratchpad to EEPROM.

Persists the TH, TL, and configuration register values so they survive power cycles.

Returns: An error on bus communication failure.

Referenced by copy_scratchpad().

◆ try_get_resolution()

result< resolution > idfxx::ds18x20::device::try_get_resolution ( ) const

Gets the current ADC resolution.

Reads the scratchpad and extracts the configuration register.

Returns: The current resolution setting, or an error on bus communication failure.

Referenced by get_resolution().

◆ try_measure()

result< void > idfxx::ds18x20::device::try_measure ( bool wait = true )

Initiates a temperature conversion.

Parameters

wait	If true, blocks until conversion completes (up to 750ms). If false, returns immediately and the caller must wait.

Returns: An error on bus communication failure.

Referenced by measure().

◆ try_measure_and_read()

result< thermo::millicelsius > idfxx::ds18x20::device::try_measure_and_read ( )

Measures and reads the temperature in a single operation.

Sends a convert command, waits for completion, then reads the result.

Returns: The measured temperature, or an error on bus communication failure.

Referenced by measure_and_read().

◆ try_read_scratchpad()

result< std::array< uint8_t, 9 > > idfxx::ds18x20::device::try_read_scratchpad ( ) const

Reads the 9-byte scratchpad memory.

Returns: The scratchpad contents, or an error on bus communication failure.

Referenced by read_scratchpad().

◆ try_read_temperature()

result< thermo::millicelsius > idfxx::ds18x20::device::try_read_temperature ( ) const

Reads the last converted temperature.

Returns: The measured temperature, or an error on bus communication failure.

Referenced by read_temperature().

◆ try_set_resolution()

result< void > idfxx::ds18x20::device::try_set_resolution ( resolution res )

Sets the ADC resolution.

Reads the current scratchpad, modifies the configuration register, and writes it back. Only applicable to DS18B20 sensors.

Parameters

res	The desired resolution.

Returns: An error on bus communication failure.

Referenced by set_resolution().

◆ try_write_scratchpad()

result< void > idfxx::ds18x20::device::try_write_scratchpad ( std::span< const uint8_t, 3 > data )

Writes 3 bytes to the scratchpad (TH, TL, configuration register).

Parameters

data	The 3 bytes to write [th, tl, config].

Returns: An error on bus communication failure.

Referenced by write_scratchpad().

◆ write_scratchpad()

void idfxx::ds18x20::device::write_scratchpad ( std::span< const uint8_t, 3 > data )

inline

Writes 3 bytes to the scratchpad (TH, TL, configuration register).

Parameters

data	The 3 bytes to write [th, tl, config].

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 315 of file ds18x20.hpp.

References try_write_scratchpad(), and idfxx::unwrap().

Friends And Related Symbol Documentation

◆ try_scan_devices

result< std::vector< device > > try_scan_devices	(	idfxx::gpio	pin,
		size_t	max_devices
	)

friend

Scans for DS18x20 devices on a 1-Wire bus.

Discovers all DS18x20-family devices connected to the specified GPIO pin.

Parameters

pin	GPIO pin connected to the 1-Wire bus.
max_devices	Maximum number of devices to discover.

Returns: A vector of discovered devices, or an error on bus communication failure.

Return values

invalid_state If the pin is not connected.

The documentation for this class was generated from the following file:

idfxx_ds18x20/include/idfxx/ds18x20.hpp

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ device() [1/3]

◆ device() [2/3]

◆ device() [3/3]

Member Function Documentation

◆ addr()

◆ copy_scratchpad()

◆ get_resolution()

◆ make()

◆ measure()

◆ measure_and_read()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ pin()

◆ read_scratchpad()

◆ read_temperature()

◆ set_resolution()

◆ try_copy_scratchpad()

◆ try_get_resolution()

◆ try_measure()

◆ try_measure_and_read()

◆ try_read_scratchpad()

◆ try_read_temperature()

◆ try_set_resolution()

◆ try_write_scratchpad()

◆ write_scratchpad()

Friends And Related Symbol Documentation

◆ try_scan_devices