Interface definitions for the 1-Wire bus component. More...

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include "driver/gpio.h"
#include "owb_gpio.h"
#include "owb_rmt.h"

Include dependency graph for owb.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	OneWireBus
	Structure containing 1-Wire bus information relevant to a single instance. More...

union	OneWireBus_ROMCode
	Represents a 1-Wire ROM Code. This is a sequence of eight bytes, where the first byte is the family number, then the following 6 bytes form the serial number. The final byte is the CRC8 check byte. More...

struct	OneWireBus_ROMCode::fields
	Provides access via field names. More...

struct	OneWireBus_SearchState
	Represents the state of a device search on the 1-Wire bus. More...

struct	owb_driver

Macros
#define	OWB_ROM_SEARCH 0xF0
	Perform Search ROM cycle to identify devices on the bus. More...

#define	OWB_ROM_READ 0x33
	Read device ROM (single device on bus only) More...

#define	OWB_ROM_MATCH 0x55
	Address a specific device on the bus by ROM. More...

#define	OWB_ROM_SKIP 0xCC
	Address all devices on the bus simultaneously. More...

#define	OWB_ROM_SEARCH_ALARM 0xEC
	Address all devices on the bus with a set alarm flag. More...

#define	OWB_ROM_CODE_STRING_LENGTH (17)
	Typical length of OneWire bus ROM ID as ASCII hex string, including null terminator. More...

#define	GPIO_NUM_NC (-1)
	ESP-IDF prior to v4.x does not define GPIO_NUM_NC. More...

Enumerations
enum	owb_status { OWB_STATUS_NOT_SET = -1 , OWB_STATUS_OK = 0 , OWB_STATUS_NOT_INITIALIZED , OWB_STATUS_PARAMETER_NULL , OWB_STATUS_DEVICE_NOT_RESPONDING , OWB_STATUS_CRC_FAILED , OWB_STATUS_TOO_MANY_BITS , OWB_STATUS_HW_ERROR }
	Represents the result of OWB API functions. More...

Functions
owb_status	owb_uninitialize (OneWireBus *bus)
	call to release resources after completing use of the OneWireBus More...

owb_status	owb_use_crc (OneWireBus *bus, bool use_crc)
	Enable or disable use of CRC checks on device communications. More...

owb_status	owb_use_parasitic_power (OneWireBus *bus, bool use_parasitic_power)
	Enable or disable use of parasitic power on the One Wire Bus. This affects how devices signal on the bus, as devices cannot signal by pulling the bus low when it is pulled high. More...

owb_status	owb_use_strong_pullup_gpio (OneWireBus *bus, gpio_num_t gpio)
	Enable or disable use of extra GPIO to activate strong pull-up circuit. This only has effect if parasitic power mode is enabled. signal by pulling the bus low when it is pulled high. More...

owb_status	owb_read_rom (const OneWireBus bus, OneWireBus_ROMCode rom_code)
	Read ROM code from device - only works when there is a single device on the bus. More...

owb_status	owb_verify_rom (const OneWireBus bus, OneWireBus_ROMCode rom_code, bool is_present)
	Verify the device specified by ROM code is present. More...

owb_status	owb_reset (const OneWireBus bus, bool is_present)
	Reset the 1-Wire bus. More...

owb_status	owb_read_bit (const OneWireBus bus, uint8_t out)
	Read a single bit from the 1-Wire bus. More...

owb_status	owb_read_byte (const OneWireBus bus, uint8_t out)
	Read a single byte from the 1-Wire bus. More...

owb_status	owb_read_bytes (const OneWireBus bus, uint8_t buffer, unsigned int len)
	Read a number of bytes from the 1-Wire bus. More...

owb_status	owb_write_bit (const OneWireBus *bus, uint8_t bit)
	Write a bit to the 1-Wire bus. More...

owb_status	owb_write_byte (const OneWireBus *bus, uint8_t data)
	Write a single byte to the 1-Wire bus. More...

owb_status	owb_write_bytes (const OneWireBus bus, const uint8_t buffer, size_t len)
	Write a number of bytes to the 1-Wire bus. More...

owb_status	owb_write_rom_code (const OneWireBus *bus, OneWireBus_ROMCode rom_code)
	Write a ROM code to the 1-Wire bus ensuring LSB is sent first. More...

uint8_t	owb_crc8_byte (uint8_t crc, uint8_t data)
	1-Wire 8-bit CRC lookup. More...

uint8_t	owb_crc8_bytes (uint8_t crc, const uint8_t *data, size_t len)
	1-Wire 8-bit CRC lookup with accumulation over a block of bytes. More...

owb_status	owb_search_first (const OneWireBus bus, OneWireBus_SearchState state, bool *found_device)
	Locates the first device on the 1-Wire bus, if present. More...

owb_status	owb_search_next (const OneWireBus bus, OneWireBus_SearchState state, bool *found_device)
	Locates the next device on the 1-Wire bus, if present, starting from the provided state. Further calls will yield additional devices, if present. More...

char *	owb_string_from_rom_code (OneWireBus_ROMCode rom_code, char *buffer, size_t len)
	Create a string representation of a ROM code, most significant byte (CRC8) first. More...

owb_status	owb_set_strong_pullup (const OneWireBus *bus, bool enable)
	Enable or disable the strong-pullup GPIO, if configured. More...

Detailed Description

Interface definitions for the 1-Wire bus component.

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

Externally powered and "parasite-powered" devices are supported. Please consult your device's datasheet for power requirements.

Definition in file owb.h.

Macro Definition Documentation

◆ GPIO_NUM_NC

#define GPIO_NUM_NC (-1)

ESP-IDF prior to v4.x does not define GPIO_NUM_NC.

Definition at line 60 of file owb.h.

◆ OWB_ROM_CODE_STRING_LENGTH

#define OWB_ROM_CODE_STRING_LENGTH (17)

Typical length of OneWire bus ROM ID as ASCII hex string, including null terminator.

Definition at line 57 of file owb.h.

◆ OWB_ROM_MATCH

#define OWB_ROM_MATCH 0x55

Address a specific device on the bus by ROM.

Definition at line 53 of file owb.h.

◆ OWB_ROM_READ

#define OWB_ROM_READ 0x33

Read device ROM (single device on bus only)

Definition at line 52 of file owb.h.

◆ OWB_ROM_SEARCH

#define OWB_ROM_SEARCH 0xF0

Perform Search ROM cycle to identify devices on the bus.

Definition at line 51 of file owb.h.

◆ OWB_ROM_SEARCH_ALARM

#define OWB_ROM_SEARCH_ALARM 0xEC

Address all devices on the bus with a set alarm flag.

Definition at line 55 of file owb.h.

◆ OWB_ROM_SKIP

#define OWB_ROM_SKIP 0xCC

Address all devices on the bus simultaneously.

Definition at line 54 of file owb.h.

Enumeration Type Documentation

◆ owb_status

enum owb_status

Represents the result of OWB API functions.

Enumerator
OWB_STATUS_NOT_SET	A status value has not been set.
OWB_STATUS_OK	Operation succeeded.
OWB_STATUS_NOT_INITIALIZED	Function was passed an uninitialised variable.
OWB_STATUS_PARAMETER_NULL	Function was passed a null pointer.
OWB_STATUS_DEVICE_NOT_RESPONDING	No response received from the addressed device or devices.
OWB_STATUS_CRC_FAILED	CRC failed on data received from a device or devices.
OWB_STATUS_TOO_MANY_BITS	Attempt to write an incorrect number of bits to the One Wire Bus.
OWB_STATUS_HW_ERROR	A hardware error occurred.

Definition at line 113 of file owb.h.

Function Documentation

◆ owb_crc8_byte()

uint8_t owb_crc8_byte	(	uint8_t	crc,
		uint8_t	data
	)

1-Wire 8-bit CRC lookup.

Parameters

[in]	crc	Starting CRC value. Pass in prior CRC to accumulate.
[in]	data	Byte to feed into CRC.

Returns: Resultant CRC value. Should be zero if last byte was the CRC byte and the CRC matches.

Definition at line 647 of file owb.c.

◆ owb_crc8_bytes()

uint8_t owb_crc8_bytes	(	uint8_t	crc,
		const uint8_t *	data,
		size_t	len
	)

1-Wire 8-bit CRC lookup with accumulation over a block of bytes.

Parameters

[in]	crc	Starting CRC value. Pass in prior CRC to accumulate.
[in]	data	Array of bytes to feed into CRC.
[in]	len	Length of data array in bytes.

Returns: Resultant CRC value. Should be zero if last byte was the CRC byte and the CRC matches.

Definition at line 652 of file owb.c.

◆ owb_read_bit()

owb_status owb_read_bit	(	const OneWireBus *	bus,
		uint8_t *	out
	)

Read a single bit from the 1-Wire bus.

Parameters

[in]	bus	Pointer to initialised bus instance.
[out]	out	The bit value read from the bus.

Returns: status

Definition at line 480 of file owb.c.

Here is the caller graph for this function:

◆ owb_read_byte()

owb_status owb_read_byte	(	const OneWireBus *	bus,
		uint8_t *	out
	)

Read a single byte from the 1-Wire bus.

Parameters

[in]	bus	Pointer to initialised bus instance.
[out]	out	The byte value read from the bus (lsb only).

Returns: status

Definition at line 502 of file owb.c.

◆ owb_read_bytes()

owb_status owb_read_bytes	(	const OneWireBus *	bus,
		uint8_t *	buffer,
		unsigned int	len
	)

Read a number of bytes from the 1-Wire bus.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in,out]	buffer	Pointer to buffer to receive read data.
[in]	len	Number of bytes to read, must not exceed length of receive buffer.

Returns: status.

Definition at line 524 of file owb.c.

◆ owb_read_rom()

owb_status owb_read_rom	(	const OneWireBus *	bus,
		OneWireBus_ROMCode *	rom_code
	)

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

Parameters

[in]	bus	Pointer to initialised bus instance.
[out]	rom_code	the value read from the device's rom

Returns: status

Definition at line 361 of file owb.c.

Here is the caller graph for this function:

◆ owb_reset()

owb_status owb_reset	(	const OneWireBus *	bus,
		bool *	is_present
	)

Reset the 1-Wire bus.

Parameters

[in]	bus	Pointer to initialised bus instance.
[out]	is_present	set to true if at least one device is present on the bus

Returns: status

Definition at line 460 of file owb.c.

Here is the caller graph for this function:

◆ owb_search_first()

owb_status owb_search_first	(	const OneWireBus *	bus,
		OneWireBus_SearchState *	state,
		bool *	found_device
	)

Locates the first device on the 1-Wire bus, if present.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in,out]	state	Pointer to an existing search state structure.
[out]	found_device	True if a device is found, false if no devices are found. If a device is found, the ROM Code can be obtained from the state.

Returns: status

Definition at line 657 of file owb.c.

Here is the caller graph for this function:

◆ owb_search_next()

owb_status owb_search_next	(	const OneWireBus *	bus,
		OneWireBus_SearchState *	state,
		bool *	found_device
	)

Locates the next device on the 1-Wire bus, if present, starting from the provided state. Further calls will yield additional devices, if present.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in,out]	state	Pointer to an existing search state structure.
[out]	found_device	True if a device is found, false if no devices are found. If a device is found, the ROM Code can be obtained from the state.

Returns: status

Definition at line 685 of file owb.c.

Here is the caller graph for this function:

◆ owb_set_strong_pullup()

owb_status owb_set_strong_pullup	(	const OneWireBus *	bus,
		bool	enable
	)

Enable or disable the strong-pullup GPIO, if configured.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in]	enable	If true, enable the external strong pull-up by setting the GPIO high. If false, disable the external strong pull-up by setting the GPIO low.

Returns: status

Definition at line 719 of file owb.c.

Here is the caller graph for this function:

◆ owb_string_from_rom_code()

char* owb_string_from_rom_code	(	OneWireBus_ROMCode	rom_code,
		char *	buffer,
		size_t	len
	)

Create a string representation of a ROM code, most significant byte (CRC8) first.

Parameters

[in]	rom_code	The ROM code to convert to string representation.
[out]	buffer	The destination for the string representation. It will be null terminated.
[in]	len	The length of the buffer in bytes. 64-bit ROM codes require 16 characters to represent as a string, plus a null terminator, for 17 bytes. See OWB_ROM_CODE_STRING_LENGTH.

Returns: pointer to the byte beyond the last byte written

Definition at line 709 of file owb.c.

Here is the caller graph for this function:

◆ owb_uninitialize()

owb_status owb_uninitialize ( OneWireBus * bus )

call to release resources after completing use of the OneWireBus

Parameters

[in] bus Pointer to initialised bus instance.

Returns: status

Definition at line 259 of file owb.c.

Here is the caller graph for this function:

◆ owb_use_crc()

owb_status owb_use_crc	(	OneWireBus *	bus,
		bool	use_crc
	)

Enable or disable use of CRC checks on device communications.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in]	use_crc	True to enable CRC checks, false to disable.

Returns: status

Definition at line 276 of file owb.c.

Here is the caller graph for this function:

◆ owb_use_parasitic_power()

owb_status owb_use_parasitic_power	(	OneWireBus *	bus,
		bool	use_parasitic_power
	)

Enable or disable use of parasitic power on the One Wire Bus. This affects how devices signal on the bus, as devices cannot signal by pulling the bus low when it is pulled high.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in]	use_parasitic_power	True to enable parasitic power, false to disable.

Returns: status

Definition at line 299 of file owb.c.

Here is the caller graph for this function:

◆ owb_use_strong_pullup_gpio()

owb_status owb_use_strong_pullup_gpio	(	OneWireBus *	bus,
		gpio_num_t	gpio
	)

Enable or disable use of extra GPIO to activate strong pull-up circuit. This only has effect if parasitic power mode is enabled. signal by pulling the bus low when it is pulled high.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in]	gpio	Set to GPIO number to use, or GPIO_NUM_NC to disable.

Returns: status

Definition at line 322 of file owb.c.

Here is the caller graph for this function:

◆ owb_verify_rom()

owb_status owb_verify_rom	(	const OneWireBus *	bus,
		OneWireBus_ROMCode	rom_code,
		bool *	is_present
	)

Verify the device specified by ROM code is present.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in]	rom_code	ROM code to verify.
[out]	is_present	Set to true if a device is present, false if not

Returns: status

Definition at line 416 of file owb.c.

Here is the caller graph for this function:

◆ owb_write_bit()

owb_status owb_write_bit	(	const OneWireBus *	bus,
		uint8_t	bit
	)

Write a bit to the 1-Wire bus.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in]	bit	Value to write (lsb only).

Returns: status

Definition at line 554 of file owb.c.

◆ owb_write_byte()

owb_status owb_write_byte	(	const OneWireBus *	bus,
		uint8_t	data
	)

Write a single byte to the 1-Wire bus.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in]	data	Byte value to write to bus.

Returns: status

Definition at line 576 of file owb.c.

Here is the caller graph for this function:

◆ owb_write_bytes()

owb_status owb_write_bytes	(	const OneWireBus *	bus,
		const uint8_t *	buffer,
		size_t	len
	)

Write a number of bytes to the 1-Wire bus.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in]	buffer	Pointer to buffer to write data from.
[in]	len	Number of bytes to write.

Returns: status

Definition at line 598 of file owb.c.

◆ owb_write_rom_code()

owb_status owb_write_rom_code	(	const OneWireBus *	bus,
		OneWireBus_ROMCode	rom_code
	)

Write a ROM code to the 1-Wire bus ensuring LSB is sent first.

Parameters

[in]	bus	Pointer to initialised bus instance.
[in]	rom_code	ROM code to write to bus.

Returns: status

Definition at line 626 of file owb.c.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ GPIO_NUM_NC

◆ OWB_ROM_CODE_STRING_LENGTH

◆ OWB_ROM_MATCH

◆ OWB_ROM_READ

◆ OWB_ROM_SEARCH

◆ OWB_ROM_SEARCH_ALARM

◆ OWB_ROM_SKIP

Enumeration Type Documentation

◆ owb_status

Function Documentation

◆ owb_crc8_byte()

◆ owb_crc8_bytes()

◆ owb_read_bit()

◆ owb_read_byte()

◆ owb_read_bytes()

◆ owb_read_rom()

◆ owb_reset()

◆ owb_search_first()

◆ owb_search_next()

◆ owb_set_strong_pullup()

◆ owb_string_from_rom_code()

◆ owb_uninitialize()

◆ owb_use_crc()

◆ owb_use_parasitic_power()

◆ owb_use_strong_pullup_gpio()

◆ owb_verify_rom()

◆ owb_write_bit()

◆ owb_write_byte()

◆ owb_write_bytes()

◆ owb_write_rom_code()