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. An ESP32 running ESPHome can be that border router itself, see OpenThread Border Router.
This component is supported on the following platforms:
- ESP32 with an 802.15.4 radio (ESP32-C5, ESP32-C6, ESP32-H2, ESP32-H4, ESP32-H21, or ESP32-S31) with the ESP-IDF framework, version 5.5.5 or newer.
- ESP32 with Wi-Fi and an external OpenThread Radio Co-Processor, with the same ESP-IDF framework and version, as a border router only, see OpenThread Border Router.
- nRF52840 with the Zephyr framework.
Full Configuration
Section titled “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.
With OpenThread configured, IPv4 is disabled by default unless another component requires it. Add
enable_ipv4: true under network to keep it enabled on ESP32.
# Example OpenThread configuration (ESP32)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)openthread: tlv: 0e080000000000010000000300001035060004001fffe00208e227ac6a7f24052f0708fdb753eb517cb4d3051062b2442a928d9ea3b947a1618fc4085a030f4f70656e5468726561642d393837330102987304105330d857354330133c05e1fd7ae81a910c0402a0f7f8 force_dataset: trueConfiguration Variables
Section titled “Configuration Variables”- device_type (Optional, enum): OpenThread Device Type, either
FTDorMTD. Defaults toFTD. 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
Section titled “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.
- 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
-15dBmto20dBm, ESP32-H2 from-24dBmto20dBm. Defaults to the platform default (typically0dBm). Ensure the configured value complies with local regulatory limits. - 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.
- core_options (Optional, mapping): OpenThread compile-time options to set. See OpenThread Core Options.
NOTE
esphome.ota does not work when poll_period > 0. Use the openthread.set_poll_period action to set the poll
period to 0 before attempting OTA, then set it back afterwards to restore sleepy (SED) behavior.
Dataset TLV Configuration
Section titled “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 Assistantopenthread: tlv: 0e080000000000010000000300001035060004001fffe00208e227ac6a7f24052f0708fdb753eb517cb4d3051062b2442a928d9ea3b947a1618fc4085a030f4f70656e5468726561642d393837330102987304105330d857354330133c05e1fd7ae81a910c0402a0f7f8openthread.set_poll_period Action
Section titled “openthread.set_poll_period Action”Sets the poll period at runtime on an MTD device. When poll_period > 0 the radio is off while idle (sleepy end
device); when 0 the radio is always on. This action is a no-op on FTD devices.
on_...: then: # Long form turns radio on all the time - openthread.set_poll_period: poll_period: 0s # Short form turns radio on all the time - openthread.set_poll_period: 0s # Short form turns radio off when idle - openthread.set_poll_period: 5sConfiguration Variables
Section titled “Configuration Variables”- poll_period (Required, Time): The poll period to apply, e.g. the
short form
openthread.set_poll_period: 5s.
OpenThread Device Type
Section titled “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)
Section titled “Sleepy End Device (SED)”The Poll Period makes the device behave as a SED. Combine it with ESP32 Power Management light sleep to save power between polls. 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.
Public API
Section titled “Public API”The OpenThreadComponent exposes the following method for use in lambdas and custom components:
get_poll_period()(MTD only): returns the current poll period in milliseconds.
The method only exists on MTD builds, so the following lambda will not compile on an FTD device:
on_...: then: - lambda: |- if (id(openthread_id).get_poll_period() > 0) { // device is sleeping between polls }OpenThread Border Router
Section titled “OpenThread Border Router”Border Router mode bridges a Thread network to a Wi-Fi network. It requires an ESP32, IPv6 enabled in the
Network Component, and the default device_type: FTD. The Thread
dataset is configured as in the Full Configuration above; Thread starts on boot and border
routing begins once Wi-Fi is connected.
The native radio is supported on ESP32-C5 and ESP32-C6:
network: enable_ipv6: true
wifi: ssid: !secret wifi_ssid password: !secret wifi_password
openthread: border_router: {} network_key: !secret thread_network_keyAny Wi-Fi-capable ESP32 can instead use an external OpenThread Radio Co-Processor (RCP) over UART. The
co-processor runs OpenThread RCP firmware, for instance ESP-IDF’s examples/openthread/ot_rcp on an ESP32-H2,
built for the same UART speed as baud_rate; a mismatch gives a co-processor that never answers.
openthread: border_router: rcp: rx_pin: GPIOXX tx_pin: GPIOXX reset_pin: GPIOXX network_key: !secret thread_network_keyConfiguration Variables
Section titled “Configuration Variables”- border_router (Optional, map): Enables Border Router mode.
- rcp (Optional, map): Configures an external OpenThread RCP.
- rx_pin (Required, Pin): ESP32 receive pin connected to the RCP transmit pin.
- tx_pin (Required, Pin): ESP32 transmit pin connected to the RCP receive pin.
- baud_rate (Optional, integer): UART baud rate. Defaults to
460800. - reset_pin (Optional, Pin): RCP reset pin, inverted (active low) unless configured otherwise. With this pin the RCP is reset in hardware when it stops responding, up to five times.
- rcp (Optional, map): Configures an external OpenThread RCP.
Wi-Fi must have at least one STA network, must not use AP or fallback AP mode, and must keep enable_on_boot: true.
WARNING
An external RCP uses UART1 directly and cannot be combined with the ESPHome UART Component. The Logger Component must also use USB or a UART other than UART1.
OpenThread ESP-IDF Logging
Section titled “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 settingesp32: framework: type: esp-idf log_level: INFOOpenThread Core Options (ESP32)
Section titled “OpenThread Core Options (ESP32)”OpenThread has many compile-time options that ESP-IDF does not offer as Kconfig options, such as frame retry counts
or optional features. On ESP32 they can be set with core_options. ESPHome writes each entry as
#define NAME VALUE to a header file in the build directory and tells ESP-IDF to include it when building OpenThread.
Every name must start with OPENTHREAD_CONFIG_ and may only contain A-Z, 0-9 and _. Values must be strings, so
quote numbers. The available options and
their defaults are listed in the
OpenThread core configuration headers.
# Example OpenThread core optionsopenthread: # ... core_options: OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE: "1" OPENTHREAD_CONFIG_MAC_DEFAULT_MAX_FRAME_RETRIES_DIRECT: "5"ESP-IDF Kconfig options for OpenThread (CONFIG_OPENTHREAD_*) are still set with sdkconfig_options in the
ESP-IDF framework configuration.
WARNING
Some OpenThread options are already set by ESP-IDF from a Kconfig option, for example
OPENTHREAD_CONFIG_MLE_MAX_CHILDREN from CONFIG_OPENTHREAD_MLE_MAX_CHILDREN. Setting one of these in
core_options stops the build with an is redefined error; set the matching CONFIG_OPENTHREAD_* option in
sdkconfig_options instead.