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.
openthread/ot_trel demonstrates Thread Radio Encapsulation Link (TREL) function. This requires a board equipped with a Wi-Fi module.
openthread/ot_sleepy_device/deep_sleep demonstrates Thread Deep-sleep function.
openthread/ot_sleepy_device/light_sleep demonstrates Thread Light-sleep function.

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.

Parameters

init_config -- [in] The initialization configuration.

Returns

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

esp_err_t esp_openthread_auto_start(otOperationalDatasetTlvs *datasetTlvs)

Starts the Thread protocol operation and attaches to a Thread network.

Parameters

datasetTlvs -- [in] The operational dataset (TLV encoded), if it's NULL, the function will generate the dataset based on the configurations from kconfig.

Returns

ESP_OK on success
ESP_FAIL on failures

esp_err_t esp_openthread_launch_mainloop(void)

Launches the OpenThread main loop.

Note

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

Returns

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.

Returns

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.

Returns: The OpenThread instance pointer

Header File

components/openthread/include/esp_openthread_types.h

Structures

struct esp_openthread_role_changed_event_t

OpenThread role changed event data.

Public Members

otDeviceRole previous_role: Previous Thread role

otDeviceRole current_role: Current Thread role

struct esp_openthread_dataset_changed_event_t

OpenThread dataset changed event data.

Public Members

esp_openthread_dataset_type_t type: Dataset type

otOperationalDataset new_dataset: New dataset

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

gpio_num_t rx_pin: UART RX pin

gpio_num_t tx_pin: UART TX pin

struct esp_openthread_spi_host_config_t

The spi port config for OpenThread.

Public Members

spi_host_device_t host_device: SPI host device

spi_dma_chan_t dma_channel: DMA channel

spi_bus_config_t spi_interface: SPI bus

spi_device_interface_config_t spi_device: SPI peripheral device

gpio_num_t intr_pin: SPI interrupt pin

struct esp_openthread_spi_slave_config_t

The spi slave config for OpenThread.

Public Members

spi_host_device_t host_device: SPI host device

spi_bus_config_t bus_config: SPI bus config

spi_slave_interface_config_t slave_config: SPI slave config

gpio_num_t intr_pin: SPI interrupt 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

esp_openthread_spi_host_config_t radio_spi_config: The spi 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

usb_serial_jtag_driver_config_t host_usb_config: The usb configuration to host

esp_openthread_spi_slave_config_t spi_slave_config: The spi 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

Type Definitions

typedef void (*esp_openthread_rcp_failure_handler)(void)

typedef void (*esp_openthread_compatibility_error_callback)(void)

Enumerations

enum esp_openthread_event_t

OpenThread event declarations.

Values:

enumerator OPENTHREAD_EVENT_START: OpenThread stack start

enumerator OPENTHREAD_EVENT_STOP: OpenThread stack stop

enumerator OPENTHREAD_EVENT_DETACHED: OpenThread detached

enumerator OPENTHREAD_EVENT_ATTACHED: OpenThread attached

enumerator OPENTHREAD_EVENT_ROLE_CHANGED: OpenThread role changed

enumerator OPENTHREAD_EVENT_IF_UP: OpenThread network interface up

enumerator OPENTHREAD_EVENT_IF_DOWN: OpenThread network interface down

enumerator OPENTHREAD_EVENT_GOT_IP6: OpenThread stack added IPv6 address

enumerator OPENTHREAD_EVENT_LOST_IP6: OpenThread stack removed IPv6 address

enumerator OPENTHREAD_EVENT_MULTICAST_GROUP_JOIN: OpenThread stack joined IPv6 multicast group

enumerator OPENTHREAD_EVENT_MULTICAST_GROUP_LEAVE: OpenThread stack left IPv6 multicast group

enumerator OPENTHREAD_EVENT_TREL_ADD_IP6: OpenThread stack added TREL IPv6 address

enumerator OPENTHREAD_EVENT_TREL_REMOVE_IP6: OpenThread stack removed TREL IPv6 address

enumerator OPENTHREAD_EVENT_TREL_MULTICAST_GROUP_JOIN: OpenThread stack joined TREL IPv6 multicast group

enumerator OPENTHREAD_EVENT_SET_DNS_SERVER: OpenThread stack set DNS server >

enumerator OPENTHREAD_EVENT_PUBLISH_MESHCOP_E: OpenThread stack start to publish meshcop-e service >

enumerator OPENTHREAD_EVENT_REMOVE_MESHCOP_E: OpenThread stack start to remove meshcop-e service >

enumerator OPENTHREAD_EVENT_DATASET_CHANGED: OpenThread dataset changed >

enum esp_openthread_dataset_type_t

OpenThread dataset type.

Values:

enumerator OPENTHREAD_ACTIVE_DATASET: Active dataset

enumerator OPENTHREAD_PENDING_DATASET: Pending dataset

enum esp_openthread_radio_mode_t

The radio mode of OpenThread.

Values:

enumerator RADIO_MODE_NATIVE: Use the native 15.4 radio

enumerator RADIO_MODE_UART_RCP: UART connection to a 15.4 capable radio co-processor (RCP)

enumerator RADIO_MODE_SPI_RCP: SPI connection to a 15.4 capable radio co-processor (RCP)

enumerator RADIO_MODE_TREL: Use the Thread Radio Encapsulation Link (TREL)

enumerator RADIO_MODE_MAX: Using for parameter check

enum esp_openthread_host_connection_mode_t

How OpenThread connects to the host.

Values:

enumerator HOST_CONNECTION_MODE_NONE: Disable host connection

enumerator HOST_CONNECTION_MODE_CLI_UART: CLI UART connection to the host

enumerator HOST_CONNECTION_MODE_CLI_USB: CLI USB connection to the host

enumerator HOST_CONNECTION_MODE_RCP_UART: RCP UART connection to the host

enumerator HOST_CONNECTION_MODE_RCP_SPI: RCP SPI connection to the host

enumerator HOST_CONNECTION_MODE_MAX: Using for parameter check

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.

Returns

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 function acquires the OpenThread API lock.

Note

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

Parameters

block_ticks -- [in] The maximum number of RTOS ticks to wait for the lock.

Returns

True on lock acquired
False on failing to acquire the lock with the timeout.

void esp_openthread_lock_release(void): This function releases the OpenThread API lock.

bool esp_openthread_task_switching_lock_acquire(TickType_t block_ticks)

This function acquires the OpenThread API task switching lock.

Note

In OpenThread API context, it waits for some actions to be done in other tasks (like lwip), after task switching, it needs to call OpenThread API again. Normally it's not allowed, since the previous OpenThread API lock is not released yet. This task_switching lock allows the OpenThread API can be called in this case.

Note

Please use esp_openthread_lock_acquire() for normal cases.

Parameters

block_ticks -- [in] The maximum number of RTOS ticks to wait for the lock.

Returns

True on lock acquired
False on failing to acquire the lock with the timeout.

void esp_openthread_task_switching_lock_release(void): This function releases the OpenThread API task switching lock.

Note

This API must be called after esp_openthread_task_switching_lock_acquire or esp_openthread_lock_acquire and will cause a crash if the current task is not the task switching lock holder. This error could be caused by calling OpenThread APIs without locking OpenThread stack.

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.

Parameters

config -- [in] The platform configuration.

Returns

glue pointer on success
NULL on failure

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.

Returns: The OpenThread netif or NULL if not initialzied.

void esp_openthread_register_meshcop_e_handler(esp_event_handler_t handler, bool for_publish)

This function register a handler for meshcop-e service publish event and remove event.

Parameters

handler -- [in] The handler.
for_publish -- [in] The usage of handler, true for publish event and false for remove event.

Macros

ESP_NETIF_INHERENT_DEFAULT_OPENTHREAD(): Default configuration reference of OpenThread esp-netif.

ESP_NETIF_DEFAULT_OPENTHREAD()

Header File

components/openthread/include/esp_openthread_border_router.h

Functions

void esp_openthread_set_backbone_netif(esp_netif_t *backbone_netif)

Sets the backbone interface used for border routing.

Note

This function must be called before esp_openthread_init

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

esp_err_t esp_openthread_border_router_init(void)

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.

Returns

ESP_OK on success
ESP_ERR_NOT_SUPPORTED if feature not supported
ESP_ERR_INVALID_STATE if already initialized
ESP_FIAL on other failures

esp_err_t esp_openthread_border_router_deinit(void)

Deinitializes the border router features of OpenThread.

Returns

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.

Returns: The backbone interface or NULL if border router not initialized.

void esp_openthread_register_rcp_failure_handler(esp_openthread_rcp_failure_handler handler): Registers the callback for RCP failure.

void esp_openthread_set_compatibility_error_callback(esp_openthread_compatibility_error_callback callback)

Registers the callback for spinel compatibility error.

Note

This function must be called before esp_openthread_init.

Parameters: callback -- [in] The callback.

esp_err_t esp_openthread_rcp_deinit(void)

Deinitializes the connection to RCP.

Returns

ESP_OK on success
ESP_ERR_INVALID_STATE if fail to deinitialize RCP

esp_err_t esp_openthread_rcp_init(void)

Initializes the connection to RCP.

Returns

ESP_OK on success
ESP_FAIL if fail to initialize RCP

esp_err_t esp_openthread_set_meshcop_instance_name(const char *instance_name)

Sets the meshcop(e) instance name.

Note

This function can only be called before esp_openthread_border_router_init. If instance_name is NULL, then the service will use the hostname as instance name.

Parameters

instance_name -- [in] The instance name, can be NULL.

Returns

ESP_OK on success
ESP_FAIL if fail to initialize RCP

Provide feedback about this document