OpenThread Component

Thread is a low-power mesh networking standard for IoT devices. The low-power aspect is important for battery-powered smart home devices. However, it’s also low-bandwidth, making it ideal for applications that don’t send a lot of data, like switches or motion sensors.

Thread uses the same RF technology as Zigbee (IEEE 802.15.4), but provides IPv6 connectivity similar to Wi-Fi. Unlike Zigbee, Thread by itself does not allow controlling devices: It is just a communication protocol. To control the Thread devices, a higher-level protocol is required: Matter or Apple HomeKit or ESPHome API.

This component allows ESPHome nodes to communicate with Home Assistant over a Thread network. It permits sending sensor state to Home Assistant and receiving Over-the-Air Updates (OTA). This OpenThread component relies on OpenThread which is an open-source implementation of Thread.

NOTE

You will need a Thread border router to connect your node to a Thread network. The border router adapts IPv6 packets on your Home Assistant network to 6LoWPAN packets on your Thread network, allowing communication across both networks.

Usage

This component is supported on the following platforms:

ESP32 (ESP32-C5, ESP32-C6, or ESP32-H2) with the ESP-IDF framework.
nRF52840 with the Zephyr framework.

Full Configuration

The configuration depends on the platform. On ESP32, the Thread dataset can be specified using the individual fields shown below or a tlv string. On nRF52840, the dataset must be provided as a hex-encoded tlv string from Home Assistant's Thread integration.

# Example OpenThread configuration (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

# Example OpenThread configuration (nRF52840)
network:
  enable_ipv6: true

openthread:
  tlv: 0e080000000000010000000300001035060004001fffe00208e227ac6a7f24052f0708fdb753eb517cb4d3051062b2442a928d9ea3b947a1618fc4085a030f4f70656e5468726561642d393837330102987304105330d857354330133c05e1fd7ae81a910c0402a0f7f8
  force_dataset: true

Configuration Variables

device_type (Optional, enum): OpenThread Device Type, either FTD or MTD. Defaults to FTD. On nRF52840 this selects the matching Nordic prebuilt OpenThread library.
tlv (Optional, string): The Thread dataset as a hex-encoded TLV string, taken from the Thread information in Home Assistant. Required on nRF52840.
force_dataset (Optional, bool): Forces ESPHome to override any OpenThread network dataset previously stored on the device, ensuring the configured dataset is applied at startup. Defaults to false.
use_address (Optional, string): Manually override the address used to connect to the device. Defaults to an auto-generated value.

ESP32 Configuration Variables

channel (Optional, int): Channel number from 11 to 26.
network_name (Optional, string): A human-readable Network Name.
network_key (Optional, string): OpenThread network key.
pan_id (Optional, string): 2-byte Personal Area Network ID (PAN ID).
ext_pan_id (Optional, string): 8-byte Extended Personal Area Network ID (XPAN ID).
pskc (Optional, string): PSKc is used to authenticate an external Thread Commissioner to a Thread network.
mesh_local_prefix (Optional, ipv6network): Used to build Mesh-Local IPv6 addresses (ML-EIDs), which are unique to each Thread device within the network partition.
poll_period (Optional, Time): When set on an MTD device, the parent router enqueues any messages and waits for the child to submit a poll data request.
output_power (Optional, integer): The amount of TX power for the Thread 802.15.4 radio in dBm. Range depends on the chip variant: ESP32-C5/C6 from -15dBm to 20dBm, ESP32-H2 from -24dBm to 20dBm. Defaults to the platform default (typically 0dBm). Ensure the configured value complies with local regulatory limits.

NOTE

esphome.ota does not work when poll_period > 0; instead use http_request.ota. timeout and watchdog_timeout need to be tested to find the correct values. Values greater than 100s may be required.

Dataset TLV Configuration

On nRF52840, the TLV approach is required for configuring the Thread dataset. On ESP32, it is an alternative to the individual field-based configuration shown above.

It is also possible to supply the entire dataset TLVs from the Thread information in Home Assistant and the individual values will be automatically extracted from it.

# Example OpenThread TLV value from the Thread information in Home Assistant
openthread:
  tlv: 0e080000000000010000000300001035060004001fffe00208e227ac6a7f24052f0708fdb753eb517cb4d3051062b2442a928d9ea3b947a1618fc4085a030f4f70656e5468726561642d393837330102987304105330d857354330133c05e1fd7ae81a910c0402a0f7f8

OpenThread Device Type

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

FTD — Full Thread Device. Acts as a Router Eligible End Device (REED) and can be promoted to a Router.
MTD — Minimal Thread Device. Cannot be promoted to a Router. Switching back from MTD to FTD will not result in a REED unless Non-Volatile Storage (NVS) is cleared.

Sleepy End Device (SED)

The Poll Period makes the device behave as a SED. Follow on work is needed utilizing Power Management and/or Light Sleep capability in esp-idf. If the device is always awake, the API timeout is 60 seconds, so a ping request will force interaction with the parent when the poll period is greater than 60 seconds.

OpenThread ESP-IDF Logging

The OpenThread log level is controlled by the log_level setting in the ESP-IDF framework configuration. The ESP-IDF log levels are mapped to OpenThread log levels as follows:

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

# Example ESP-IDF framework log_level setting
esp32:
  framework:
    type: esp-idf
    log_level: INFO