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
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_launch_mainloop(void)
Launches the OpenThread main loop.
Note
Thie 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
Structures
-
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
-
int rx_pin
UART RX pin
-
int tx_pin
UART TX pin
-
uart_port_t port
-
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_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
-
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_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_START
-
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_NATIVE
Header File
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 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.
- Parameters
block_ticks – [in] The maxinum 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.
Header File
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.
Macros
-
ESP_NETIF_INHERENT_DEFAULT_OPENTHREAD()
Default configuration reference of OT esp-netif.
-
ESP_NETIF_DEFAULT_OPENTHREAD()
Header File
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_rcp_deinit(void)
Deinitializes the conneciton to RCP.