# Thread

[中文]

## Introduction

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

## Application Examples

- openthread/ot_br demonstrates how to set up a Thread border router on ESP32-S3, enabling functionalities such as bidirectional IPv6 connectivity, service discovery, etc.

- openthread/ot_cli demonstrates how to use the OpenThread Command Line Interface with additional features such as TCP, UDP, and Iperf. This requires a board equipped with an IEEE 802.15.4 module. This example provides instructions on how to set up a network using at least two 802.15.4 boards.

- openthread/ot_rcp demonstrates how to work with a Host Processor to perform as a Thread border router and function as a Thread sniffer, using a board with an IEEE 802.15.4 module.

- 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 API docs.

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

- This header file can be included with:

  >     #include "esp_openthread.h"

- This header file is a part of the API provided by the `openthread` component. To declare that your component depends on `openthread`, add the following to your CMakeLists.txt:

  >     REQUIRES openthread

  > or

  >     PRIV_REQUIRES openthread

### 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

esp_err_t esp_openthread_mainloop_exit(void)

  Signals the OpenThread main loop to exit.

  Returns:

    - ESP_OK on success

    - ESP_FAIL on failures

esp_err_t esp_openthread_start(const esp_openthread_config_t *config)

  Starts the full OpenThread stack and create a handle task.

  Note

  The OpenThread instance will also be initialized in this function.

  Parameters:

    config -- [in] The OpenThread platform configuration.

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_STATE if already initialized

esp_err_t esp_openthread_stop(void)

  This function performs OpenThread stack and platform driver deinitialization and delete the handle task.

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_STATE if Thread is already active

### Header File

- components/openthread/include/esp_openthread_types.h

- This header file can be included with:

  >     #include "esp_openthread_types.h"

- This header file is a part of the API provided by the `openthread` component. To declare that your component depends on `openthread`, add the following to your CMakeLists.txt:

  >     REQUIRES openthread

  > or

  >     PRIV_REQUIRES openthread

### 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

struct esp_openthread_config_t

  The OpenThread configuration.

  Public Members

  esp_netif_config_t netif_config

    The netif configuration

  esp_openthread_platform_config_t platform_config

    The platform configuration

### Type Definitions

typedef void (*esp_openthread_rcp_failure_handler)(void)

  The OpenThread rcp failure handler.

typedef void (*esp_openthread_compatibility_error_callback)(void)

  The OpenThread compatibility error callback.

typedef void (*esp_openthread_coprocessor_reset_failure_callback)(void)

  The OpenThread co-processor reset failure callback.

### 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_RCP_USB

    RCP USB Serial JTAG connection to the host

  enumerator HOST_CONNECTION_MODE_MAX

    Using for parameter check

### Header File

- components/openthread/include/esp_openthread_lock.h

- This header file can be included with:

  >     #include "esp_openthread_lock.h"

- This header file is a part of the API provided by the `openthread` component. To declare that your component depends on `openthread`, add the following to your CMakeLists.txt:

  >     REQUIRES openthread

  > or

  >     PRIV_REQUIRES openthread

### 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

- This header file can be included with:

  >     #include "esp_openthread_netif_glue.h"

- This header file is a part of the API provided by the `openthread` component. To declare that your component depends on `openthread`, add the following to your CMakeLists.txt:

  >     REQUIRES openthread

  > or

  >     PRIV_REQUIRES openthread

### 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.

bool is_openthread_internal_mesh_local_addr(const otIp6Address *address)

  This function judges the target address is openthread mesh local or not.

  Parameters:

    address -- [in] The address.

  Returns:

    - True if the address is openthread mesh local, otherwise false

### 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

- This header file can be included with:

  >     #include "esp_openthread_border_router.h"

- This header file is a part of the API provided by the `openthread` component. To declare that your component depends on `openthread`, add the following to your CMakeLists.txt:

  >     REQUIRES openthread

  > or

  >     PRIV_REQUIRES openthread

### 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.

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

const char *esp_openthread_get_meshcop_instance_name(void)

  Gets the meshcop(e) instance name.

  Returns:

    The instance name.

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.