Thread Border Router (THBR) THBR

A complete Thread border router on an ESP32-C6 stick, reached through the chip's own USB port — no radio co-processor in the host. Runs as a Home Assistant add-on or as a plain Docker container.

Version 2026.8.40  runs on: ESP32-C6, ESP32-C5

Thread Border Router (THBR)

The border router runs entirely on an ESP32-C6. It reaches the host through the chip’s native USB port, which the host side turns into a network interface (tap). There is no radio co-processor in the host, no Ethernet chip on the stick, and no Spinel link that stops working when a host process restarts.

Because the border router lives on the stick, the Thread network survives whatever happens on the host: restarting Home Assistant, updating the add-on, recreating the container. The mesh keeps running — only the path to it pauses.

Features

• Border routing — the stick forms or joins a Thread network, advertises the route to it, and the host reaches Thread devices over IPv6. On the private backbone between host and stick it answers with an ot-br-posix-compatible REST API.
• Matter over Thread — Home Assistant imports the network from the router and commissions devices through it; firmware updates for those devices flow through it too.
• Bluetooth LE for commissioning — a Matter device is talked to over BLE before it has ever seen a Thread network. Servers and NUCs often have no Bluetooth at all. The stick lends its radio to the Matter server: the server drives the scan, the connection and the exchange, the stick carries them.
• Its own page in the sidebar — firmware on the stick against the one the add-on carries, border routing state, memory, the route into the mesh and whether anything answers through it, plus a graph of the mesh.
• Firmware and flasher ship inside the image — add-on and Docker container both carry the finished ESP binary and the flashing tool. A new stick needs nothing but being plugged in: no web flasher, no ESP-IDF toolchain, no shell on the host. Before writing anything the container reads chip type and serial number over the ROM protocol and stops if they do not match the chosen port; an application it did not build is never overwritten unasked.
• Save the network settings — the stick’s Thread credentials in a file that Home Assistant backups carry. Restored onto a replacement stick, the network moves to new hardware without re-commissioning a single device.

Requirements

• An ESP32-C6 with 4 MB flash, connected through its native USB port (USB-Serial/JTAG). Firmware for the ESP32-C5 ships alongside it and the add-on writes whichever matches the chip it finds — but the Bluetooth work was measured on a C6, and the C5 carries caveats (see addon/DOCS.md). The ESP32-H2 cannot run this: Espressif ships no border-router library for it.
• Home Assistant OS or Supervised — or Home Assistant in a container on a host you control.

Getting started

Under Settings → Add-ons → Add-on store → ⋮ → Repositories add the repository URL https://github.com/tostmann/THBR, install THBR Thread Border Router, pick the stick under device on the Configuration tab, and start it. The Supervisor pulls a published image, so this takes seconds rather than a build.

Two steps remain in Home Assistant: under System → Network, enable the tap interface in addition to your normal adapter and restart — otherwise the announcements crossing the backbone never reach discovery — and add the Open Thread Border Router integration with the stick’s address. It has to be typed in; that integration carries no mDNS discovery.

Without the Home Assistant Supervisor the same thing runs as an ordinary container: docker pull tostmann/thbr (multi-arch, arm64 and amd64), take the service from addon/compose.yaml and point it at the stick. Firmware and flasher are in the same image — nothing else to install here either.

Limits

Commissioning over the stick’s Bluetooth radio needs a Matter server that accepts a proxy radio — matter.js does with --ble-proxy, the python-matter-server turns the offer away. Everything else works regardless.

The code is under the PolyForm Noncommercial License 1.0.0: free for anything that is not commercial. The components it builds on keep their own licences (OpenThread BSD-3-Clause, the Espressif components Apache-2.0, cJSON MIT, esptool GPL-2.0-or-later).