API Reference

Header files

include/onewire_bus.h
include/onewire_bus_impl_rmt.h
include/onewire_bus_impl_uart.h
include/onewire_cmd.h
include/onewire_crc.h
include/onewire_device.h
include/onewire_types.h
interface/onewire_bus_interface.h

File include/onewire_bus.h

Functions

Type	Name
esp_err_t	onewire_bus_del (onewire_bus_handle_t bus) Free 1-Wire bus resources.
esp_err_t	onewire_bus_read_bit (onewire_bus_handle_t bus, uint8_t rx_bit) Read a bit from 1-wire bus.*
esp_err_t	onewire_bus_read_bytes (onewire_bus_handle_t bus, uint8_t rx_buf, size_t rx_buf_size) Read bytes from 1-wire bus.*
esp_err_t	onewire_bus_reset (onewire_bus_handle_t bus) Send reset pulse to the bus, and check if there are devices attached to the bus.
esp_err_t	onewire_bus_write_bit (onewire_bus_handle_t bus, uint8_t tx_bit) Write a bit to 1-wire bus, this is a blocking function.
esp_err_t	onewire_bus_write_bytes (onewire_bus_handle_t bus, const uint8_t tx_data, uint8_t tx_data_size) Write bytes to 1-wire bus.*

Functions Documentation

function `onewire_bus_del`

Free 1-Wire bus resources.

esp_err_t onewire_bus_del (
    onewire_bus_handle_t bus
)

Parameters:

bus 1-Wire bus handle

Returns:

ESP_OK: Free resources successfully
ESP_FAIL: Free resources failed because error occurred

function `onewire_bus_read_bit`

Read a bit from 1-wire bus.

esp_err_t onewire_bus_read_bit (
    onewire_bus_handle_t bus,
    uint8_t *rx_bit
)

Parameters:

bus 1-wire bus handle
rx_bit received bit, 0 for zero bit, 1 for one bit

Returns:

ESP_OK Read bit from 1-wire bus successfully.
ESP_ERR_INVALID_ARG Invalid argument.

function `onewire_bus_read_bytes`

Read bytes from 1-wire bus.

esp_err_t onewire_bus_read_bytes (
    onewire_bus_handle_t bus,
    uint8_t *rx_buf,
    size_t rx_buf_size
)

Parameters:

bus 1-wire bus handle
rx_buf pointer to buffer to store received data
rx_buf_size size of buffer to store received data, in bytes

Returns:

ESP_OK: Read bytes from 1-Wire bus successfully
ESP_ERR_INVALID_ARG: Read bytes from 1-Wire bus failed because of invalid argument
ESP_FAIL: Read bytes from 1-Wire bus failed because of other errors

function `onewire_bus_reset`

Send reset pulse to the bus, and check if there are devices attached to the bus.

esp_err_t onewire_bus_reset (
    onewire_bus_handle_t bus
)

Parameters:

bus 1-Wire bus handle

Returns:

ESP_OK: Reset 1-Wire bus successfully and find device on the bus
ESP_ERR_NOT_FOUND: Reset 1-Wire bus successfully but no device found on the bus
ESP_FAIL: Reset 1-Wire bus failed because of other errors

function `onewire_bus_write_bit`

Write a bit to 1-wire bus, this is a blocking function.

esp_err_t onewire_bus_write_bit (
    onewire_bus_handle_t bus,
    uint8_t tx_bit
)

Parameters:

bus 1-wire bus handle
tx_bit bit to transmit, 0 for zero bit, other for one bit

Returns:

ESP_OK Write bit to 1-wire bus successfully.
ESP_ERR_INVALID_ARG Invalid argument.

function `onewire_bus_write_bytes`

Write bytes to 1-wire bus.

esp_err_t onewire_bus_write_bytes (
    onewire_bus_handle_t bus,
    const uint8_t *tx_data,
    uint8_t tx_data_size
)

Parameters:

bus 1-Wire bus handle
tx_data pointer to data to be sent
tx_data_size size of data to be sent, in bytes

Returns:

ESP_OK: Write bytes to 1-Wire bus successfully
ESP_ERR_INVALID_ARG: Write bytes to 1-Wire bus failed because of invalid argument
ESP_FAIL: Write bytes to 1-Wire bus failed because of other errors

File include/onewire_bus_impl_rmt.h

Structures and Types

Type	Name
struct	onewire_bus_rmt_config_t 1-Wire bus RMT specific configuration

Functions

Type	Name
esp_err_t	onewire_new_bus_rmt (const onewire_bus_config_t bus_config, const onewire_bus_rmt_config_t* rmt_config, onewire_bus_handle_t* ret_bus) Create 1-Wire bus with RMT backend.*

Structures and Types Documentation

struct `onewire_bus_rmt_config_t`

1-Wire bus RMT specific configuration

Variables:

uint32_t max_rx_bytes
Set the largest possible single receive size, which determines the size of the internal buffer that used to save the receiving RMT symbols

Functions Documentation

function `onewire_new_bus_rmt`

Create 1-Wire bus with RMT backend.

esp_err_t onewire_new_bus_rmt (
    const onewire_bus_config_t *bus_config,
    const onewire_bus_rmt_config_t *rmt_config,
    onewire_bus_handle_t *ret_bus
)

Note:

One 1-Wire bus utilizes a pair of RMT TX and RX channels

Parameters:

bus_config 1-Wire bus configuration
rmt_config RMT specific configuration
ret_bus Returned 1-Wire bus handle

Returns:

ESP_OK: create 1-Wire bus handle successfully
ESP_ERR_INVALID_ARG: create 1-Wire bus handle failed because of invalid argument
ESP_ERR_NO_MEM: create 1-Wire bus handle failed because of out of memory
ESP_FAIL: create 1-Wire bus handle failed because some other error

File include/onewire_bus_impl_uart.h

Structures and Types

Type	Name
struct	onewire_bus_uart_config_t 1-Wire bus UART specific configuration

Functions

Type	Name
esp_err_t	onewire_new_bus_uart (const onewire_bus_config_t bus_config, const onewire_bus_uart_config_t* uart_config, onewire_bus_handle_t* ret_bus) Create 1-Wire bus with UART backend.*

Structures and Types Documentation

struct `onewire_bus_uart_config_t`

1-Wire bus UART specific configuration

Variables:

int uart_port_num
UART port number, e.g. UART_NUM_1

Functions Documentation

function `onewire_new_bus_uart`

Create 1-Wire bus with UART backend.

esp_err_t onewire_new_bus_uart (
    const onewire_bus_config_t *bus_config,
    const onewire_bus_uart_config_t *uart_config,
    onewire_bus_handle_t *ret_bus
)

Note:

TX and RX will both be configured to bus_config->bus_gpio_num. And this GPIO will be configured as open-drain mode.

Parameters:

bus_config 1-Wire bus configuration
uart_config UART specific configuration
ret_bus Returned 1-Wire bus handle

Returns:

ESP_OK: create 1-Wire bus handle successfully
ESP_ERR_INVALID_ARG: create 1-Wire bus handle failed because of invalid argument
ESP_ERR_NO_MEM: create 1-Wire bus handle failed because of out of memory
ESP_FAIL: create 1-Wire bus handle failed because some other error

File include/onewire_cmd.h

Macros

Type	Name
define	ONEWIRE_CMD_MATCH_ROM 0x55
define	ONEWIRE_CMD_READ_POWER_SUPPLY 0xB4
define	ONEWIRE_CMD_SEARCH_ALARM 0xEC
define	ONEWIRE_CMD_SEARCH_NORMAL 0xF0
define	ONEWIRE_CMD_SKIP_ROM 0xCC

Macros Documentation

define `ONEWIRE_CMD_MATCH_ROM`

#define ONEWIRE_CMD_MATCH_ROM 0x55

define `ONEWIRE_CMD_READ_POWER_SUPPLY`

#define ONEWIRE_CMD_READ_POWER_SUPPLY 0xB4

define `ONEWIRE_CMD_SEARCH_ALARM`

#define ONEWIRE_CMD_SEARCH_ALARM 0xEC

define `ONEWIRE_CMD_SEARCH_NORMAL`

#define ONEWIRE_CMD_SEARCH_NORMAL 0xF0

define `ONEWIRE_CMD_SKIP_ROM`

#define ONEWIRE_CMD_SKIP_ROM 0xCC

File include/onewire_crc.h

Functions

Type	Name
uint8_t	onewire_crc8 (uint8_t init_crc, uint8_t input, size_t input_size) Calculate Dallas CRC8 value of a given buffer.*

Functions Documentation

function `onewire_crc8`

Calculate Dallas CRC8 value of a given buffer.

uint8_t onewire_crc8 (
    uint8_t init_crc,
    uint8_t *input,
    size_t input_size
)

Parameters:

init_crc Initial CRC value
input Input buffer to calculate CRC value
input_size Size of input buffer, in bytes

Returns:

CRC8 result of the input buffer

File include/onewire_device.h

Structures and Types

Type	Name
struct	onewire_device_t 1-Wire device generic type
typedef struct onewire_device_t	onewire_device_t 1-Wire device generic type

Functions

Type	Name
esp_err_t	onewire_del_device_iter (onewire_device_iter_handle_t iter) Delete the device iterator.
esp_err_t	onewire_device_iter_get_next (onewire_device_iter_handle_t iter, onewire_device_t dev) Get the next 1-Wire device from the iterator.*
esp_err_t	onewire_new_device_iter (onewire_bus_handle_t bus, onewire_device_iter_handle_t ret_iter) Create an iterator to enumerate the 1-Wire devices on the bus.*

Structures and Types Documentation

struct `onewire_device_t`

1-Wire device generic type

Variables:

onewire_device_address_t address
Device address (represented by its internal ROM ID)
onewire_bus_handle_t bus
Which bus the 1-Wire device is attached to

typedef `onewire_device_t`

1-Wire device generic type

typedef struct onewire_device_t onewire_device_t;

Functions Documentation

function `onewire_del_device_iter`

Delete the device iterator.

esp_err_t onewire_del_device_iter (
    onewire_device_iter_handle_t iter
)

Parameters:

iter Device iterator handle

Returns:

ESP_OK: Delete device iterator successfully
ESP_ERR_INVALID_ARG: Invalid argument
ESP_FAIL: Other errors

function `onewire_device_iter_get_next`

Get the next 1-Wire device from the iterator.

esp_err_t onewire_device_iter_get_next (
    onewire_device_iter_handle_t iter,
    onewire_device_t *dev
)

Parameters:

iter Device iterator handle
dev Returned 1-Wire device handle

Returns:

ESP_OK: Get next device successfully
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_NOT_FOUND: No more device to get
ESP_FAIL: Other errors

function `onewire_new_device_iter`

Create an iterator to enumerate the 1-Wire devices on the bus.

esp_err_t onewire_new_device_iter (
    onewire_bus_handle_t bus,
    onewire_device_iter_handle_t *ret_iter
)

Parameters:

bus 1-Wire bus handle
ret_iter Returned created device iterator

Returns:

ESP_OK: Create device iterator successfully
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_NO_MEM: No memory to create device iterator
ESP_FAIL: Other errors

File include/onewire_types.h

Structures and Types

Type	Name
struct	onewire_bus_config_t 1-Wire bus configuration
struct	onewire_bus_config_flags
typedef struct onewire_bus_t *	onewire_bus_handle_t Type of 1-Wire bus handle.
typedef uint64_t	onewire_device_address_t Type of the address for a 1-Wire compatible device.
typedef struct onewire_device_iter_t *	onewire_device_iter_handle_t Type of 1-Wire device iterator handle.

Structures and Types Documentation

struct `onewire_bus_config_t`

1-Wire bus configuration

Variables:

int bus_gpio_num
GPIO number that used by the 1-Wire bus
struct onewire_bus_config_t::onewire_bus_config_flags flags
Configuration flags for the bus

struct `onewire_bus_config_t::onewire_bus_config_flags`

Variables:

uint32_t en_pull_up
Set true to enable internal pull-up resistor. Please note the internal pull-up resistor cannot provide enough current for some devices, so external pull-up resistor is still recommended.

typedef `onewire_bus_handle_t`

Type of 1-Wire bus handle.

typedef struct onewire_bus_t* onewire_bus_handle_t;

typedef `onewire_device_address_t`

Type of the address for a 1-Wire compatible device.

typedef uint64_t onewire_device_address_t;

typedef `onewire_device_iter_handle_t`

Type of 1-Wire device iterator handle.

typedef struct onewire_device_iter_t* onewire_device_iter_handle_t;

File interface/onewire_bus_interface.h

Structures and Types

Type	Name
struct	onewire_bus_t 1-Wire bus interface definition
typedef struct onewire_bus_t	onewire_bus_t

Structures and Types Documentation

struct `onewire_bus_t`

1-Wire bus interface definition

Variables:

esp_err_t(* del
Free 1-Wire bus resources.
Parameters:

bus 1-Wire bus handle

Returns:

ESP_OK: Free resources successfully
ESP_FAIL: Free resources failed because error occurred

esp_err_t(* read_bit
Read a bit from 1-wire bus.
Parameters:

handle 1-wire bus handle
rx_bit received bit, 0 for zero bit, 1 for one bit

Returns:

ESP_OK Read bit from 1-wire bus successfully.
ESP_ERR_INVALID_ARG Invalid argument.

esp_err_t(* read_bytes
Read bytes from 1-wire bus.
Parameters:

bus 1-wire bus handle
rx_buf pointer to buffer to store received data
rx_buf_size size of buffer to store received data, in bytes

Returns:

ESP_OK: Read bytes from 1-Wire bus successfully
ESP_ERR_INVALID_ARG: Read bytes from 1-Wire bus failed because of invalid argument
ESP_FAIL: Read bytes from 1-Wire bus failed because of other errors

esp_err_t(* reset
Send reset pulse to the bus, and check if there are devices attached to the bus.
Parameters:

bus 1-Wire bus handle

Returns:

ESP_OK: Reset 1-Wire bus successfully and find device on the bus
ESP_ERR_NOT_FOUND: Reset 1-Wire bus successfully but no device found on the bus
ESP_FAIL: Reset 1-Wire bus failed because of other errors

esp_err_t(* write_bit
Write a bit to 1-wire bus, this is a blocking function.
Parameters:

handle 1-wire bus handle
tx_bit bit to transmit, 0 for zero bit, other for one bit

Returns:

ESP_OK Write bit to 1-wire bus successfully.
ESP_ERR_INVALID_ARG Invalid argument.

esp_err_t(* write_bytes
Write bytes to 1-wire bus.
Note:

This is a blocking function

Parameters:

bus 1-Wire bus handle
tx_data pointer to data to be sent
tx_data_size size of data to be sent, in bytes

Returns:

ESP_OK: Write bytes to 1-Wire bus successfully
ESP_ERR_INVALID_ARG: Write bytes to 1-Wire bus failed because of invalid argument
ESP_FAIL: Write bytes to 1-Wire bus failed because of other errors

typedef `onewire_bus_t`

typedef struct onewire_bus_t onewire_bus_t;

Type of 1-Wire bus

Keyboard shortcuts

1-Wire Bus Documentation