# OpenThread

[English]

OpenThread 是在 802.15.4 MAC 层上运行的 IP 协议栈，支持 mesh 网络，具有低功耗特性。

## OpenThread 协议栈运行模式

在乐鑫的芯片上，OpenThread 可按以下模式运行：

### 独立节点模式

在此模式下，完整的 OpenThread 协议栈及其应用层在同一芯片上运行，适用于支持 15.4 无线通信协议的芯片，如 ESP32-H2, ESP32-C5, ESP32-C6。

### 无线协处理器 (RCP) 模式

在此模式下，芯片通过连接到运行 OpenThread IP 协议栈的另一个主机，代表主机发送和接收 15.4 数据包。该模式适用于支持 15.4 无线通信协议的芯片，如 ESP32-H2, ESP32-C6。对于芯片和主机之间的通信方式，目前 ESP-IDF 支持 SPI 或 UART。考虑到传输延迟，建议使用 SPI。

### OpenThread 主机模式

在此模式下，不支持 15.4 无线通信协议的芯片可以连接到 RCP，并在主机模式下运行 OpenThread。这种模式支持在 Wi-Fi 芯片上（如 ESP32、ESP32-S2、ESP32-S3 和 ESP32-C3 等）运行 OpenThread。下图展示了设备在不同模式下的工作方式：

OpenThread 设备模式

## 编写 OpenThread 应用程序

要学习编写 OpenThread 应用程序，可以从 OpenThread 应用示例 openthread/ot_cli 开始。该示例中展示了简单的 OpenThread 网络组网流程，以及在 Openthread 网络上，如何实现基于套接字的服务器和客户端之间的简单通信。

### 初始化 OpenThread 协议栈所需的准备

- s1.1： 主任务调用 `esp_vfs_eventfd_register()`，初始化 eventfd 虚拟文件系统。eventfd 文件系统用于实现 OpenThread 协议栈中的任务通知。

- s1.2： 主任务调用 `nvs_flash_init()` 初始化 NVS，即 Thread 网络数据的存储位置。

- s1.3： 可选。主任务调用 `esp_netif_init()`，为 Thread 创建网络接口。

- s1.4： 主任务调用 `esp_event_loop_create()` 创建系统事件任务，并初始化应用程序事件的回调函数。

### OpenThread 协议栈初始化

- s2.1： 调用 `esp_openthread_init()` 初始化 OpenThread 协议栈。

### OpenThread 网络接口初始化

以下为 可选 步骤，仅在应用程序需为 Thread 创建网络接口时使用。

- s3.1：使用 `ESP_NETIF_DEFAULT_OPENTHREAD` 调用 `esp_netif_new()`，创建网络接口。

- s3.2：调用 `esp_openthread_netif_glue_init()`，创建 OpenThread 网络接口处理程序。

- s3.3：调用 `esp_netif_attach()` 将处理程序附加到网络接口。

### OpenThread 主循环

- s4.3：调用 `esp_openthread_launch_mainloop()` 启动 OpenThread 主循环。注意，OpenThread 主循环属于忙等循环，仅在 OpenThread 协议栈终止后返回。

### 调用 OpenThread API

OpenThread API 非线程安全。当从其他任务中调用 OpenThread API 时，请确保以 `esp_openthread_lock_acquire()` 获取锁，并在之后以 `esp_openthread_lock_release()` 释放锁。

### 卸载 Openthread 协议栈

要在应用程序中卸载 OpenThread 协议栈，请遵循以下步骤：

- 如果创建了 OpenThread 网络接口，请调用 `esp_netif_destroy()` 和 `esp_openthread_netif_glue_deinit()` 卸载 OpenThread 协议栈。

- 调用 `esp_openthread_deinit()` 卸载 OpenThread 协议栈。

## OpenThread 宏定义

在 OpenThread 协议栈中，定义宏来进行功能启用以及参数配置是常见行为。在实际使用中，用户可以通过定义宏的值来启用/禁用相关功能和修改参数。乐鑫提供以下方式来进行 OpenThread 宏定义：

- 使用配置菜单配置 (`menuconfig`)：部分宏已经映射到 Kconfig 文件，可通过 `idf.py menuconfig → Component config → OpenThread` 启用/关闭相应功能，并配置相关参数。

- 使用用户自定义头文件配置：用户可编写头文件，并启用 `idf.py menuconfig → Component config → OpenThread → Thread Extensioned Features → Use a header file defined by customer` 来应用自定义头文件。自定义头文件的优先级将仅次于配置菜单。

- 使用 `openthread-core-esp32x-xxx-config.h` 的配置：部分宏在 OpenThread private 头文件中已经设置默认值，暂不支持通过 menuconfig 修改，但可以通过用户自定义头文件修改。

- 使用 OpenThread 协议栈默认配置：对于其他宏，OpenThread 协议栈在定义时已设置默认值。

备注

以上四种配置方式，优先级由高到低为：配置菜单 → 用户自定义头文件 → openthread-core-esp32x-xxx-config.h → OpenThread 协议栈默认配置

## OpenThread 边界路由器

OpenThread 边界路由器连接了 Thread 网络和其他 IP 网络，提供 IPv6 连通性、服务注册和委托功能。

要在 ESP 芯片上启用 OpenThread 边界路由器，需要将 RCP 连接到具备 Wi-Fi 功能的芯片上，如 ESP32。

在初始化过程中，调用 `esp_openthread_border_router_init()` 会启用所有边界路由功能。

要了解更多有关边界路由器的详细信息，请参阅 openthread/ot_br 示例和其中的 README 文件。

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。