Thread
概述
Thread 是一个基于 IP 的网状网络协议,它基于 802.15.4 物理层和 MAC 层。
应用示例
openthread/ot_br 演示了如何在 ESP32 上设置 Thread 边界路由器,启用双向 IPv6 连接、服务发现等功能。
openthread/ot_cli 演示了如何使用支持 TCP、UDP 和 Iperf 等附加功能的 OpenThread 命令行界面。该示例需要在配备 IEEE 802.15.4 模块的开发板上运行,并说明了如何使用至少两个这样的开发板进行网络配置。
openthread/ot_rcp 演示了如何与主处理器配合使用,作为 Thread 边界路由器和 Thread Sniffer。该示例需要在配备 IEEE 802.15.4 模块的开发板上运行。
API参考
应使用 OpenThread API 操作 Thread 网络。请参考 OpenThread API 文档。
ESP-IDF 提供额外的 API,用于启动和管理 OpenThread 实现执行网络接口绑定和边界路由功能。
Header File
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 onopenthread
, 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.
备注
The OpenThread instance will also be initialized in this function.
- 参数
init_config -- [in] The initialization configuration.
- 返回
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.
- 参数
datasetTlvs -- [in] The operational dataset (TLV encoded), if it's NULL, the function will generate the dataset based on the configurations from kconfig.
- 返回
ESP_OK on success
ESP_FAIL on failures
-
esp_err_t esp_openthread_launch_mainloop(void)
Launches the OpenThread main loop.
备注
This function will not return unless error happens when running the OpenThread stack.
- 返回
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.
- 返回
ESP_OK on success
ESP_ERR_INVALID_STATE if not initialized
-
otInstance *esp_openthread_get_instance(void)
This function acquires the underlying OpenThread instance.
备注
This function can be called on other tasks without lock.
- 返回
The OpenThread instance pointer
Header File
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 onopenthread
, 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.
-
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
-
esp_openthread_dataset_type_t type
-
struct esp_openthread_mainloop_context_t
This structure represents a context for a select() based mainloop.
-
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
-
uart_port_t port
-
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
-
spi_host_device_t host_device
-
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
-
spi_host_device_t host_device
-
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
-
esp_openthread_radio_mode_t radio_mode
-
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
-
esp_openthread_host_connection_mode_t host_connection_mode
-
struct esp_openthread_port_config_t
The OpenThread port specific configuration.
-
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
-
esp_openthread_radio_config_t radio_config
Type Definitions
-
typedef void (*esp_openthread_rcp_failure_handler)(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 >
-
enumerator OPENTHREAD_EVENT_START
-
enum esp_openthread_dataset_type_t
OpenThread dataset type.
Values:
-
enumerator OPENTHREAD_ACTIVE_DATASET
Active dataset
-
enumerator OPENTHREAD_PENDING_DATASET
Pending dataset
-
enumerator OPENTHREAD_ACTIVE_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
-
enumerator RADIO_MODE_NATIVE
-
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
-
enumerator HOST_CONNECTION_MODE_NONE
Header File
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 onopenthread
, 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.
- 返回
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.
备注
Every Openthread APIs that takes an otInstance argument MUST be protected with this API lock except that the call site is in Openthread callbacks.
- 参数
block_ticks -- [in] The maximum number of RTOS ticks to wait for the lock.
- 返回
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.
备注
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.
备注
Please use esp_openthread_lock_acquire() for normal cases.
- 参数
block_ticks -- [in] The maximum number of RTOS ticks to wait for the lock.
- 返回
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.
备注
This API must be called after
esp_openthread_task_switching_lock_acquire
oresp_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
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 onopenthread
, 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.
- 参数
config -- [in] The platform configuration.
- 返回
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.
- 返回
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.
- 参数
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
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 onopenthread
, 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.
备注
This function must be called before esp_openthread_init
- 参数
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.
备注
Calling this function will make the device behave as an OpenThread border router. Kconfig option CONFIG_OPENTHREAD_BORDER_ROUTER is required.
- 返回
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.
- 返回
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.
- 返回
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.
-
esp_err_t esp_openthread_rcp_deinit(void)
Deinitializes the connection to RCP.
- 返回
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.
- 返回
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.
备注
This function can only be called before
esp_openthread_border_router_init
. Ifinstance_name
is NULL, then the service will use the hostname as instance name.- 参数
instance_name -- [in] The instance name, can be
NULL
.- 返回
ESP_OK on success
ESP_FAIL if fail to initialize RCP