Skip to content
Get started

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.

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: true
  • 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.
  • 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 -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.
  • 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.

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

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: 5s
  • poll_period (Required, Time): The poll period to apply, e.g. the short form openthread.set_poll_period: 5s.

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.

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.

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
}

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_key

Any 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_key
  • 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.

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.

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 LevelOpenThread Level
NONENONE
ERRORCRIT
WARNWARN
INFONOTE
DEBUGINFO
VERBOSEDEBG
# Example ESP-IDF framework log_level setting
esp32:
framework:
type: esp-idf
log_level: INFO

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 options
openthread:
# ...
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.