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"

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.

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

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

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

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

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

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

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.

Enumeration Type Documentation

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.

Function Documentation

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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.

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.

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

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

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

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

Data Structures

Macros

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation