Thread working on ESP32-H2 - Example Project

[HarvsG]

In ESP Home 2025.6.0 support was released for Thread and thread enabled boards the H2 and the C6, I thought I’d document my bumpy experiences getting an example Thread project going with HomeAssistant:

Pre-requisites

Assumed knowledge:

• You have set up at least 1 ESP Home wifi device before trying a thread device

HA installation with:

• Thread integration enabled and working
  • Requires at least 1 boarder router, in my case I had a Google Home Display and a SkyConnect (with the OpenThread add-on) on the same network (How to combine networks)
  • An ESP32 H2 or C6 - example below is the H2
  • ESPHome Device Builder (I find it can crash my raspberry pi 4 so I use a seperate docker installation)
  • I believe having IPv6 enabled on your router may be a requirement - but I’m not certain about this - its not clear to me if thread traffic ever goes near your router or whether it all happens on it’s own network with border routers doing 6->4 NAT.

0. Getting your tlv
   • In home assistant, go to the Thread integration page, click ‘configure’, then click on the circular icon in the top right
     
     
   • Copy the long TLV somewhere for later
1. Commissioning your ESP32 with esphome
   • I’d usually recommend using esphome webtools for this first step but it doesn’t yet support the H2
   • Instead connect the H2 to your compute and do the ‘add device’ flow in ESPhome, if you’re like me you’ll see two COM devices appear, I tended to go with the one that started with JTAG.
   • The flow would repeatedly fail for me, I guess it is early days for the H2:
     
     
   • Clicking the “skip this step” reveals a list of devices that the H2 isn’t even on.
     
     
   • I clicked “ESP32” and then clicked “skip” when it offered to install
2. Installation
   • Click on ‘edit’ for the new device, we are going to delete/replace most of this default config, except for everything inside the api: and ota: tags so copy and paste them somewhere safe

   •  esphome:
        name: thread-test
        friendly_name: thread-test
      
      esp32:
        board: esp32-h2-devkitm-1
        variant: ESP32H2
        framework:
          type: esp-idf
      
      # Enable logging
      logger:
      
      # Enable Home Assistant API
      api:
        encryption:
          key: "YourEncryptionKeyGenerated by ESPHome"
      
      ota:
        - platform: esphome
          password: "yourOTApasswordGeneratedByESPhome"
      
      network:
        enable_ipv6: true
      
      openthread:
        tlv: yourTLVfromStep0
      
      # Output and light configuration for a single red LED
      output:
        - platform: gpio
          pin: GPIO1
          id: red_led
      
      light:
        - platform: binary
          name: "Red LED"
          output: red_led
     

   • Click install → “Plug into this computer” and follow the steps.
3. Adding to home assistant
   • I found that the device was auto-discovered, I have no idea how I would have added it otherwise.
4. Breadboarding
   • To control the red LED I had a set up like this, note GPIO1 and a 100 or 220Ohm resistor
     
     
   • Looking good in HA, although interestingly nothing to indicate that it is a thread device
     
     

[lerele (IF)]

I’m trying with an ESP32 H2 and at the end of step 2 I get this error:
“Configuration does not match the platform of the connected device. Expected an ESP32 device.”, any idea on what is going on?

Thanks.

[HarvsG]

Can you share your YAML,
This bit is the key but, it is possible you’re using a different H2 board, can you share a link to the board you’re using?

 esp32:
   board: esp32-h2-devkitm-1
   variant: ESP32H2
   framework:
     type: esp-idf

[lerele (IF)]

This is my YAML code:

esphome:
  name: thread-test
  friendly_name: thread-test
 
esp32:
  board: esp32dev-h2-devkitm-1
  variant: ESP32H2
  framework:
    type: esp-idf
     
# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
....

And this is the link to my board:

https://es.aliexpress.com/item/1005006252422191.html?spm=a2g0o.order_list.order_list_main.33.c805194dOJrZke&gatewayAdapt=glo2esp

Can you give me a link to a working board?

Thanks.

[HarvsG]

Hmm I would have thought that board would work.
I used this one: Waveshare ESP32-H2 Development Board - The Pi Hut
The H2 support seems to be quite limited in ESP home at the moment, I would try the C6 instead.

[bagre]

Same here. I had to click “Clean build files” and then it worked:

This is the board config that I’m using:

esp32:
  board: esp32-h2-devkitm-1
  variant: ESP32H2
  framework:
    type: esp-idf

[lerele (IF)]

Thanks bagre, working now.

[remcohn (Remco)]

I am trying to get the TLV for my network, but if i click on the (I) button, i only see network name, channel, dataset ID, panID and extended pan id, no TLV.

Am i missing something?

[francisp (Francis)]

Last one ?