Thread

Introduction

Thread is a IP-based mesh networking protocol. It’s based on the 802.15.4 physical and MAC layer.

Application Examples

The openthread directory of ESP-IDF examples contains the following applications:

• The OpenThread interactive shell openthread/ot_cli.

• The Thread border router openthread/ot_br.

• The Thread radio co-processor openthread/ot_rcp.

API Reference

For manipulating the Thread network, the OpenThread api shall be used. The OpenThread api docs can be found at the OpenThread official website.

ESP-IDF provides extra apis for launching and managing the OpenThread stack, binding to network interfaces and border routing features.

Header File

• components/openthread/include/esp_openthread.h

Functions

esp_err_t esp_openthread_init(const esp_openthread_platform_config_t *init_config)

Initializes the full OpenThread stack.

Note

The OpenThread instance will also be initialized in this function.

Return

• ESP_OK on success

• ESP_ERR_NO_MEM if allocation has failed

• ESP_ERR_INVALID_ARG if radio or host connection mode not supported

• ESP_ERR_INVALID_STATE if already initialized

Parameters

• [in] init_config: The initialization configuration.

esp_err_t esp_openthread_launch_mainloop(void)

Launches the OpenThread main loop.

Note

Thie function will not return unless error happens when running the OpenThread stack.

Return

• ESP_OK on success

• ESP_ERR_NO_MEM if allocation has failed

• ESP_FAIL on other failures

esp_err_t esp_openthread_deinit(void)

This function performs OpenThread stack and platform driver deinitialization.

Return

• ESP_OK on success

• ESP_ERR_INVALID_STATE if not initialized

otInstance *esp_openthread_get_instance(void)

This function acquires the underlying OpenThread instance.

Note

This function can be called on other tasks without lock.

Return

The OpenThread instance pointer

Header File

• components/openthread/include/esp_openthread_types.h

Structures

struct esp_openthread_mainloop_context_t

This structure represents a context for a select() based mainloop.

Public Members

fd_set read_fds

The read file descriptors

fd_set write_fds

The write file descriptors

fd_set error_fds

The error file descriptors

int max_fd

The max file descriptor

struct timeval timeout

The timeout

struct esp_openthread_uart_config_t

The uart port config for OpenThread.

Public Members

uart_port_t port

UART port number

uart_config_t uart_config

UART configuration, see uart_config_t docs

int rx_pin

UART RX pin

int tx_pin

UART TX pin

struct esp_openthread_radio_config_t

The OpenThread radio configuration.

Public Members

esp_openthread_radio_mode_t radio_mode

The radio mode

esp_openthread_uart_config_t radio_uart_config

The uart configuration to RCP

struct esp_openthread_host_connection_config_t

The OpenThread host connection configuration.

Public Members

esp_openthread_host_connection_mode_t host_connection_mode

The host connection mode

esp_openthread_uart_config_t host_uart_config

The uart configuration to host

struct esp_openthread_port_config_t

The OpenThread port specific configuration.

Public Members

const char *storage_partition_name

The partition for storing OpenThread dataset

uint8_t netif_queue_size

The packet queue size for the network interface

uint8_t task_queue_size

The task queue size

struct esp_openthread_platform_config_t

The OpenThread platform configuration.

Public Members

esp_openthread_radio_config_t radio_config

The radio configuration

esp_openthread_host_connection_config_t host_config

The host connection configuration

esp_openthread_port_config_t port_config

The port configuration

Enumerations

enum esp_openthread_event_t

OpenThread event declarations.

Values:

OPENTHREAD_EVENT_START

OpenThread stack start

OPENTHREAD_EVENT_STOP

OpenThread stack stop

OPENTHREAD_EVENT_IF_UP

OpenThread network interface up

OPENTHREAD_EVENT_IF_DOWN

OpenThread network interface down

OPENTHREAD_EVENT_GOT_IP6

OpenThread stack added IPv6 address

OPENTHREAD_EVENT_LOST_IP6

OpenThread stack removed IPv6 address

OPENTHREAD_EVENT_MULTICAST_GROUP_JOIN

OpenThread stack joined IPv6 multicast group

OPENTHREAD_EVENT_MULTICAST_GROUP_LEAVE

OpenThread stack left IPv6 multicast group

enum esp_openthread_radio_mode_t

The radio mode of OpenThread.

Values:

RADIO_MODE_NATIVE = 0x0

Use the native 15.4 radio

RADIO_MODE_UART_RCP = 0x1

UART connection to a 15.4 capable radio co-processor (RCP)

RADIO_MODE_SPI_RCP = 0x2

SPI connection to a 15.4 capable radio co-processor (RCP)

enum esp_openthread_host_connection_mode_t

How OpenThread connects to the host.

Values:

HOST_CONNECTION_MODE_NONE = 0x0

Disable host connection

HOST_CONNECTION_MODE_CLI_UART = 0x1

CLI UART connection to the host

HOST_CONNECTION_MODE_RCP_UART = 0x2

RCP UART connection to the host

Header File

• components/openthread/include/esp_openthread_lock.h

Functions

esp_err_t esp_openthread_lock_init(void)

This function initializes the OpenThread API lock.

Return

• ESP_OK on success

• ESP_ERR_NO_MEM if allocation has failed

• ESP_ERR_INVALID_STATE if already initialized

void esp_openthread_lock_deinit(void)

This function deinitializes the OpenThread API lock.

bool esp_openthread_lock_acquire(TickType_t block_ticks)

This functions acquires the OpenThread API lock.

Note

Every OT APIs that takes an otInstance argument MUST be protected with this API lock except that the call site is in OT callbacks.

Return

• True on lock acquired

• False on failing to acquire the lock with the timeout.

Parameters

• [in] block_ticks: The maxinum number of RTOS ticks to wait for the lock.

void esp_openthread_lock_release(void)

This function releases the OpenThread API lock.

Header File

• components/openthread/include/esp_openthread_netif_glue.h

Functions

void *esp_openthread_netif_glue_init(const esp_openthread_platform_config_t *config)

This function initializes the OpenThread network interface glue.

Return

• glue pointer on success

• NULL on failure

Parameters

• [in] config: The platform configuration.

void esp_openthread_netif_glue_deinit(void)

This function deinitializes the OpenThread network interface glue.

esp_netif_t *esp_openthread_get_netif(void)

This function acquires the OpenThread netif.

Return

The OpenThread netif or NULL if not initialzied.

Header File

• components/openthread/include/esp_openthread_border_router.h

Functions

esp_err_t esp_openthread_border_router_init(esp_netif_t *backbone_netif)

Initializes the border router features of OpenThread.

Note

Calling this function will make the device behave as an OpenThread border router. Kconfig option CONFIG_OPENTHREAD_BORDER_ROUTER is required.

Return

• ESP_OK on success

• ESP_ERR_NOT_SUPPORTED if feature not supported

• ESP_ERR_INVALID_STATE if already initialized

• ESP_FIAL on other failures

Parameters

• [in] backbone_netif: The backbone network interface (WiFi or ethernet)

esp_err_t esp_openthread_border_router_deinit(void)

Deinitializes the border router features of OpenThread.

Return

• ESP_OK on success

• ESP_ERR_INVALID_STATE if not initialized

• ESP_FIAL on other failures

esp_netif_t *esp_openthread_get_backbone_netif(void)

Gets the backbone interface of OpenThread border router.

Return

The backbone interface or NULL if border router not initialized.

提供有关此文档的反馈