OpenThread 组件

Thread 是一种用于物联网设备的低功耗网状网络标准。低功耗特性对于电池供电的智能家居设备很重要。不过，它也是低带宽的，非常适合不发送大量数据的应用，如开关或运动传感器。

Thread 使用与 Zigbee（IEEE 802.15.4）相同的射频技术，但提供类似 Wi-Fi 的 IPv6 连接。与 Zigbee 不同，Thread 本身不允许控制设备：它只是一种通信协议。要控制 Thread 设备，需要一个更高级别的协议：Matter 或 Apple HomeKit 或 ESPHome API。

此组件允许 ESPHome 节点通过 Thread 网络与 Home Assistant 通信。它允许将传感器状态发送到 Home Assistant 以及接收空中更新（OTA）。此 OpenThread 组件依赖于 OpenThread，它是 Thread 的一个开源实现。

NOTE

你需要一个 Thread 边界路由器来将你的节点连接到 Thread 网络。边界路由器将你 Home Assistant 网络上的 IPv6 数据包转换为 Thread 网络上的 6LoWPAN 数据包，从而允许跨两个网络进行通信。

用法

此组件在以下平台上受支持：

ESP32 带 802.15.4 无线电（ESP32-C5、ESP32-C6、ESP32-H2、ESP32-H4、ESP32-H21 或 ESP32-S31），搭配 ESP-IDF 框架。
nRF52840 搭配 Zephyr 框架。

完整配置

配置取决于平台。在 ESP32 上，Thread 数据集可以使用下面显示的各个字段或一个 tlv 字符串来指定。在 nRF52840 上，数据集必须以十六进制编码的 tlv 字符串形式提供，取自 Home Assistant 的 Thread 集成。

# 示例 OpenThread 配置（ESP32）
network:
  enable_ipv6: true

openthread:
  device_type: FTD
  channel: 13
  network_name: OpenThread-8f28
  network_key: 0xdfd34f0f05cad978ec4e32b0413038ff
  pan_id: 0x8f28
  ext_pan_id: 0xd63e8e3e495ebbc3
  pskc: 0xc23a76e98f1a6483639b1ac1271e2e27
  mesh_local_prefix: fd53:145f:ed22:ad81::/64
  force_dataset: true

# 示例 OpenThread 配置（nRF52840）
network:
  enable_ipv6: true

openthread:
  tlv: 0e080000000000010000000300001035060004001fffe00208e227ac6a7f24052f0708fdb753eb517cb4d3051062b2442a928d9ea3b947a1618fc4085a030f4f70656e5468726561642d393837330102987304105330d857354330133c05e1fd7ae81a910c0402a0f7f8
  force_dataset: true

配置变量

device_type (可选, enum): OpenThread 设备类型，FTD 或 MTD。默认为 FTD。在 nRF52840 上，这会选择匹配的 Nordic 预构建 OpenThread 库。
tlv (可选, string): 以十六进制编码的 TLV 字符串形式的 Thread 数据集，取自 Home Assistant 中的 Thread 信息。在 nRF52840 上为必选。
force_dataset (可选, bool): 强制 ESPHome 覆盖之前存储在设备上的任何 OpenThread 网络数据集，确保在启动时应用所配置的数据集。默认为 false。
use_address (可选, string): 手动覆盖用于连接到设备的地址。默认为自动生成的值。

ESP32 配置变量

channel (可选, int): 信道号，从 11 到 26。
network_name (可选, string): 人类可读的网络名称。
network_key (可选, string): OpenThread 网络密钥。
pan_id (可选, string): 2 字节的个域网 ID（PAN ID）。
ext_pan_id (可选, string): 8 字节的扩展个域网 ID（XPAN ID）。
pskc (可选, string): PSKc 用于对外部 Thread 专员（Commissioner）进行身份验证，使其加入 Thread 网络。
mesh_local_prefix (可选, ipv6network): 用于构建 Mesh-Local IPv6 地址（ML-EID），这些地址对网络分区内的每个 Thread 设备都是唯一的。
output_power (可选, integer): Thread 802.15.4 无线电的 TX 功率，单位为 dBm。范围取决于芯片变体：ESP32-C5/C6 为 -15dBm 到 20dBm，ESP32-H2 为 -24dBm 到 20dBm。默认为平台默认值（通常为 0dBm）。确保所配置的值符合当地监管限制。
poll_period (可选, Time): 当在 MTD 设备上设置时，父级路由器会将消息加入队列，并等待子设备提交轮询数据请求。

NOTE

当 poll_period > 0 时，esphome.ota 无法工作。在执行 OTA 之前，使用 openthread.set_poll_period 操作将轮询周期设置为 0，之后再将其设置回原值以恢复睡眠（SED）行为。

数据集 TLV 配置

在 nRF52840 上，TLV 方法是配置 Thread 数据集所必需的。在 ESP32 上，它是上面所示基于单独字段的配置的一种替代方法。

还可以从 Home Assistant 的 Thread 信息中提供整个数据集 TLV，各个值将从其中自动提取。

# 来自 Home Assistant Thread 信息的示例 OpenThread TLV 值
openthread:
  tlv: 0e080000000000010000000300001035060004001fffe00208e227ac6a7f24052f0708fdb753eb517cb4d3051062b2442a928d9ea3b947a1618fc4085a030f4f70656e5468726561642d393837330102987304105330d857354330133c05e1fd7ae81a910c0402a0f7f8

`openthread.set_poll_period` 操作

在运行时为 MTD 设备设置轮询周期。当 poll_period > 0 时，无线电在空闲时关闭（睡眠端设备）；当为 0 时，无线电始终开启。此操作在 FTD 设备上是空操作。

on_...:
  then:
    # 长格式：始终开启无线电
    - openthread.set_poll_period:
        poll_period: 0s
    # 短格式：始终开启无线电
    - openthread.set_poll_period: 0s
    # 短格式：空闲时关闭无线电
    - openthread.set_poll_period: 5s

配置变量

poll_period (必选, Time): 要应用的轮询周期，例如短格式 openthread.set_poll_period: 5s。

OpenThread 设备类型

参见 https://openthread.io/guides/thread-primer/node-roles-and-types

FTD — 全功能 Thread 设备（Full Thread Device）。作为符合路由器资格的端设备（REED）工作，并且可以被提升为路由器。
MTD — 最小功能 Thread 设备（Minimal Thread Device）。不能被提升为路由器。从 MTD 切回 FTD 不会使其变为 REED，除非清除非易失性存储（NVS）。

睡眠端设备（SED）

轮询周期使设备表现为 SED。后续工作需要在 esp-idf 中利用电源管理和/或浅睡眠（Light Sleep）功能。如果设备始终处于唤醒状态，API 超时为 60 秒，因此当轮询周期大于 60 秒时，ping 请求将强制与父设备交互。

公共 API

OpenThreadComponent 暴露以下方法供 lambda 和自定义组件使用：

get_poll_period()（仅 MTD）: 返回当前轮询周期（毫秒）。

此方法仅存在于 MTD 构建中，因此以下 lambda 将无法在 FTD 设备上编译：

on_...:
  then:
    - lambda: |-
        if (id(openthread_id).get_poll_period() > 0) {
          // 设备在轮询之间处于睡眠状态
        }

OpenThread ESP-IDF 日志

OpenThread 日志级别由 ESP-IDF 框架配置中的 log_level 设置控制。 ESP-IDF 日志级别按如下方式映射到 OpenThread 日志级别：

ESP-IDF 级别	OpenThread 级别
NONE	NONE
ERROR	CRIT
WARN	WARN
INFO	NOTE
DEBUG	INFO
VERBOSE	DEBG

# 示例 ESP-IDF 框架 log_level 设置
esp32:
  framework:
    type: esp-idf
    log_level: INFO

OpenThread 组件

用法

完整配置

配置变量

ESP32 配置变量

数据集 TLV 配置

openthread.set_poll_period 操作

配置变量

OpenThread 设备类型

睡眠端设备（SED）

公共 API

OpenThread ESP-IDF 日志

另请参阅

`openthread.set_poll_period` 操作