Thread

The Thread integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] helps you track the different Thread networks in your home and manage the Thread network credentials (similar to a Wi-Fi password).

This page documents the Thread integration. To learn more about Thread in Home Assistant, refer to Thread.

You do not need to install this integration. The Thread integration shows up automatically when Home Assistant detects a border router.

Turning Home Assistant into a Thread border router

Follow these steps if you want to turn Home Assistant into a Thread border router using the Thread radio of Yellow, Connect ZBT-1, Connect ZBT-2, or another compatible radio.

To find out if you already have Thread networks:

  1. Go to Settings > Connectivity > Thread.
  2. Check if you see any Thread networks.

Case 1: Making Home Assistant your first Thread network

Follow these steps if you want to turn Home Assistant into a Thread border router using the Thread radio of Yellow, Connect ZBT-1, Connect ZBT-2, or another compatible radio and you do not have any third-party Thread networks present yet. This will automatically create a new Thread network with the name ha-thread-xxxx. The last four digits are a network-specific identifier (PAN ID).

Prerequisites

  • Device with a Thread-capable radio, such as Home Assistant Yellow, Connect ZBT-1, Connect ZBT-2, or another compatible radio
  • Android phone or iPhone
  • No third-party Thread networks present

To make Home Assistant your first Thread network

  1. To enable Thread support on your Home Assistant Yellow, Connect ZBT-1, or Connect ZBT-2, you need to install the OpenThread Border Router app. Follow the corresponding procedure:

  2. Make sure the Home Assistant Thread network is defined as preferred network.

    • This should happen automatically, but check to be sure.

    • Go to Settings > Connectivity > Thread.

    • You should see the Home Assistant logo under Preferred network.

      image

  3. Before you can add Matter-based Thread devices, your phone needs to know the credentials of your newly created Thread network.

    • To share the credentials with your Android phone, open the Home Assistant Companion app.
      • In the Companion app, go to Settings > Companion app > Troubleshooting, then select Sync Thread credentials.
      • Follow the instructions on screen.
      • Result: You see the message Added network from Home Assistant to this device.
    • To share the credentials with your iPhone, open the Home Assistant Companion app.
  4. To add Matter-based Thread devices, follow the steps on Adding a matter device to Home Assistant.

Case 2: Creating a Home Assistant border router when there is an existing network

Follow these steps if you want to turn Home Assistant into a Thread border router using the Thread radio of Yellow, Connect ZBT-1, or another compatible radio but you already have third-party Thread networks present. These steps will join the Home Assistant Thread border router with the existing Thread network.

If you have both Google and Apple Thread networks present, decide which one you would like add the Home Assistant border router to.

Prerequisites

  • Device with a Thread-capable radio, such as Home Assistant Yellow, Connect ZBT-1, Connect ZBT-2, or another compatible radio
  • Third-party Thread network listed
  • Android phone if you have a Google Thread network, iPhone if you have an Apple Thread network

To create a Home Assistant border router when there is an existing network

Note: the steps and images here show the process with a Google Thread network. But the process is very similar if you have an Apple Thread network with an iPhone.

  1. Make sure you have an Android/iPhone phone and your phone is in the same Wi-Fi network as your Google border router.

  2. First you need to import the Thread credentials of your Google thread network.

    • In the Companion app, go to Settings > Connectivity > Thread.
    • Select Send credentials to Home Assistant.
      • Result: On Android, you see the message Imported credential.
  3. Refresh the screen.

    • The network’s card should now show Network information, indicating that Home Assistant now has the credentials of that network.
  4. Select Make preferred network.

    • Result: The selected network now shows as the preferred network.

    image

  5. To enable Thread support, you need to install the OpenThread Border Router app. Follow the corresponding procedure:

    image

    • 🎉 You successfully created a Home Assistant Thread network and joined it with a pre-existing third-party network.

Adding a third-party Thread adapter to Home Assistant

Follow these steps if you want to set up a third-party Thread adapter.

If you have a Home Assistant Thread adapter, follow the corresponding instructions instead:

Prerequisites

  • Home Assistant Operating System installed on your smart home hub. For example:
    • On a Home Assistant Green, where Home Assistant OS is preinstalled
    • On a Home Assistant Yellow or on a Raspberry Pi
  • Latest updates installed
  • A new Thread adapter and a USB extension cable
    • If your adapter supports multiple protocols:
      • They might have another firmware installed by default (Zigbee, for example).
      • Check their documentation and install the OpenThread firmware on the adapter.
      • Check their documentation and take a note of the baudrate.

To add a Thread adapter to the OpenThread Border Router app

  1. Install the OpenThread Border Router app.
  2. Plug the adapter into the extension cable and plug it into the Home Assistant hub.
  3. Go to Settings > Apps > OpenThread Border Router and select the Configuration tab.
  4. Under Device, select your adapter.
  5. Under Baudrate, select the baudrate that is specified in the documentation of your adapter.
    • If you can’t find the baudrate, keep the default 460800 or contact the manufacturer’s support.
    • Save your changes.
    • Troubleshooting:
      • Check the logs.
      • If the app crashes or fails to communicate with the Thread integration: Toggle the Hardware flow control option and try again.
  6. Start the app (or restart it if it is already running). Wait until it has started, then check the logs.
    • Home Assistant then adds the OpenThread Border Router integration automatically.
  7. Go to Settings > Connectivity > Thread.
    • Result: You should now see your OpenThread border router.
    • If you already have a preferred network and the new adapter does not have a Thread network yet, the border router joins your preferred network. If your adapter uses multiprotocol, the preferred network also needs to use the same channel.
    • Otherwise, the border router creates a new Thread network named ha-thread-xxxx. If you did not have a preferred network yet, and Home Assistant does not find any other border router on that network, the new network becomes your preferred network.
    • Troubleshooting: If you don’t see the network there, go back to the app configuration and adjust your settings, if needed, and try again.

Migrating a Thread network to a new adapter

Follow these steps if you already have a Thread adapter running but want to switch to a new adapter.

If you want to migrate to a Home Assistant Connect ZBT-2, follow the steps in the Home Assistant Connect ZBT-2 documentation.

Prerequisites

  • Home Assistant Operating System installed on your smart home hub. For example:
    • On a Home Assistant Green, where Home Assistant OS is preinstalled
    • On a Home Assistant Yellow or on a Raspberry Pi
  • Existing Thread adapter connected to your Home Assistant hub
  • Latest updates installed
  • A new Thread adapter and a USB extension cable
    • If your adapter supports multiple protocols:
      • They might have another firmware installed by default (Zigbee, for example).
      • Check their documentation and install the OpenThread firmware on the adapter.
      • Check their documentation and take a note of the baudrate.
  • Thread devices

To migrate an existing Thread network to a new adapter

  1. Plug the new adapter into the extension cable and plug it into the Home Assistant hub.
  2. Go to Settings > Apps > OpenThread Border Router and select the Configuration tab.
  3. Under Device, select your new adapter.
  4. Under Baudrate, select the baudrate that is specified in the documentation of your adapter.
    • If you can’t find the baudrate, try 460800, which is the default, or contact the manufacturer’s support.
    • Save your changes.
    • Troubleshooting:
      • Check the logs.
      • If the app crashes or fails to communicate with the Thread integration: Toggle the Hardware flow control option and try again.
  5. Restart the app and check the logs.
    • Info: Your Thread network is managed by Home Assistant. It is not stored on the adapter. Migrating the adapter means that Home Assistant will start to use your new adapter’s radio instead of the old one.
    • When the app starts, it migrates the OTBR settings for the new adapter. In the logs, you see Migrating OTBR settings if needed….
  6. Go to Settings > Connectivity > Thread.
    • Result: You should now see that the Thread network is still there.
    • Troubleshooting: If you don’t see the network there, go back to the app configuration and adjust your settings, if needed, and try again.
  7. If you no longer want to use the old adapter, you can unplug it now.

Understanding the Thread configuration page

This section explains why you might see multiple networks on the Thread configuration page and what this means for your network.

About different Thread networks

Today, each vendor forms their own Thread network when you start using their products. This means you can end up having a Home Assistant, an Apple, and a Google Thread network in your home. The Thread configuration panel lists all Thread border routers and groups them by the Thread network.

The Thread configuration page shows three vendor-specific Thread networks.

These are all separate networks using different credentials. This means devices can’t roam between the Thread networks.

A Network information row on a network’s card indicates that Home Assistant has the credentials for that network. Select it to see the network’s details, like its channel and PAN ID. In this case, only the credentials of the home-assistant network are known.

Home Assistant discovers all Thread border routers in your network because they send mDNS/DNS-SD announcements. These local announcements don’t contain the network credentials. That’s why you see the network there, but not the credentials.

About the preferred network

The intention of the Preferred network in Home Assistant is that it will be used as the default network when adding Thread⁻based devices.

Note

The preferred network function isn’t completely implemented yet. In particular, when adding MatterMatter is an open-source standard that defines how to control smart home devices on a Wi-Fi or Thread network. [Learn more] devices through the companion apps, the preferred network of the mobile device is being used.

Making a network your preferred network

You can only set a Thread network as preferred if the credentials are known.

  1. To import Thread credentials, you need your Android or iOS companion app.
    • The Android app sends the preferred Thread network of your phone.
    • The iOS app sends the preferred Thread network of your iPhone, and any other Thread networks that the app can access.
  2. On your companion app, go to Settings > Connectivity > Thread.
    • At the bottom of the page, you should see a Send credentials to Home Assistant button.

    • Select it, then refresh the screen.

    • Importing the credentials allows a Google- or Apple-created Thread network to be the preferred network of Home Assistant.

  3. If the Make preferred network button is shown, select it.

Combining Thread networks

Having multiple TBRs from different vendors can result in separate networks using different credentials. This prevents devices from roaming between the Thread networks. In theory, it would be better to join all Thread networks into a single network to increase the size of the mesh network. A dense mesh network should lead to better RF coverage and better link quality, which lowers transmission latencies, making communication faster.

A new Home Assistant border router can join an existing Thread network from another vendor. For the steps, refer to Case 2: Creating a Home Assistant border router when there is an existing network.

Troubleshooting

This section helps you resolve common issues with Thread networks and device commissioning.

IPv6 is not working

Symptom: “IPv6 routing/forwarding is not enabled” warning in the OTBR app logs, or Thread devices join the network but cannot be reached

Thread is an IPv6-only protocol. For Thread devices to communicate with Home Assistant and other devices on your network, your Home Assistant system must have working IPv6 connectivity. In setups that route traffic between networks, IPv6 forwarding must also be enabled on the system acting as the router. If any required layer is missing IPv6 support, Thread devices may join the mesh but fail to communicate beyond it.

Layers to check

Every setup should have these basics in place:

  • Home Assistant host — the system where Home Assistant runs must have working IPv6 connectivity
  • Network router — the device that manages traffic on your local network must support IPv6 routing for your network

Depending on how Home Assistant is deployed, there may be additional layers to check:

  • Hypervisor host — if Home Assistant runs inside a virtual machine, like Proxmox, ESXi, or VirtualBox, make sure the virtual NIC connected to the Home Assistant VM has IPv6 connectivity. In bridged setups, the hypervisor usually does not need IPv6 forwarding. If the hypervisor is routing traffic, IPv6 forwarding may be required there
  • Docker daemon — if Home Assistant runs as a container, Docker may need IPv6 enabled in its configuration
  • Host operating system — if Home Assistant runs as a container on Linux, the host OS may need IPv6 forwarding enabled at the kernel level when it is routing container traffic

Note

The warning in the OTBR app logs only detects whether IPv6 forwarding is enabled on the Home Assistant host itself. Issues at the hypervisor, Docker, host OS, virtual network, or router layer will not trigger this warning but can still prevent Thread devices from communicating.

Home Assistant Operating System

IPv6 may not be enabled in Docker on your Home Assistant OS installation. There is currently no UI option for this setting — it must be changed from the command line. To check and enable it:

  1. Open the Terminal & SSH app (or any equivalent terminal app).

  2. Check the current setting:

    ha docker info
    

    If enable_ipv6 shows null or false, enable it:

    ha docker options --enable-ipv6=true
    
  3. Reboot the Home Assistant host for the change to take effect:

    ha host reboot
    

If Home Assistant OS is running inside a virtual machine, make sure the VM has IPv6 connectivity. If the hypervisor is routing traffic (rather than bridging), IPv6 forwarding may also need to be enabled. Refer to your hypervisor’s documentation for instructions.

Home Assistant Container

If you are running Home Assistant Container, there are two additional layers to check on the machine that hosts the container:

  • Docker daemon — IPv6 must be enabled in the Docker daemon configuration. Refer to the Docker documentation on enabling IPv6 for instructions.
  • Host operating system — the Linux host needs IPv6 forwarding enabled at the kernel level. Refer to your distribution’s documentation for instructions on enabling IPv6 forwarding.

If the host machine is itself a virtual machine, make sure the VM has IPv6 connectivity. If the hypervisor is routing traffic (rather than bridging), IPv6 forwarding may also need to be enabled. Refer to your hypervisor’s documentation for instructions.

Network router

Your network router needs IPv6 forwarding enabled so that IPv6 traffic can flow between your local network and the Thread mesh. Refer to your router’s documentation for details on enabling IPv6 support and forwarding.

Changing the Thread channel

Symptom: frequent pairing failures or poor device communication

If you experience frequent pairing failures or devices that drop off the network, the Thread channel may be suffering from interference.

Description

Thread uses the IEEE 802.15.4 radio standard, which operates in the 2.4 GHz band, the same band used by Wi-Fi and Bluetooth. Thread channels 11 through 24 can overlap with 2.4 GHz Wi-Fi, including common Wi-Fi channels like 1, 6, and 11. This overlap can cause interference that prevents the Thread radio from transmitting successfully.

A sign of interference in the OTBR app logs is repeated ChannelAccessFailure errors. This means the radio attempted to send a frame but the channel was too busy, even after multiple retries.

Thread channel 26 is the least likely to experience Wi-Fi interference. Channel 25 can also help reduce interference, but it may still partially overlap with some Wi-Fi configurations, depending on channel width. Channel 26 is a common recommendation for environments with heavy Wi-Fi traffic.

Resolution

You can change the Thread channel through the Thread integration in Home Assistant.

Note

Risk of Thread devices becoming unavailable after a channel change

Some Thread devices might not move to the new channel automatically. You might need to add them to your Thread network again before they show up in Home Assistant. If the new channel is busy, your Thread devices can also become unavailable from time to time. You can only undo the change by changing the channel again.

To avoid this:

  • Change the channel before you add Thread devices, if possible.

  1. Go to Settings > Connectivity > Thread.
  2. Next to your OpenThread border router, select Overflow menu , then Change channel.
  3. Enter your desired channel (for example, 26), and select Change channel.
  4. After you confirm the change, the network will continue to operate normally on the current channel. The border router schedules the switch for approximately five minutes later so that all devices on the mesh can learn about the new channel and switch simultaneously. During this waiting period, nothing will appear to have changed. This is expected. Do not restart the border router or make additional changes while the switch is pending.
  5. After the switch, check your Thread devices. If a device does not come back, add it to your Thread network again.

Pairing a Thread device fails

Symptom: the device is in pairing mode, but commissioning does not complete

You are trying to add a Thread device through the Home Assistant Companion app, but the process fails or times out.

Description

Pairing a Thread device involves multiple steps that happen automatically: your phone connects to the device over Bluetooth Low Energy (BLE), shares the Thread network credentials, and then the device joins the Thread mesh and gets commissioned into Home Assistant. A failure at any of these steps can cause pairing to fail.

Resolution

First, make sure you have followed all the prerequisites for adding a Matter device, including phone setup and Bluetooth requirements. Refer to the adding a Matter device to Home Assistant procedure for the full checklist.

If pairing still fails after verifying the prerequisites, check the following:

  • The device is still in pairing mode. Most devices only stay in pairing mode for a limited time. If it expires, reset the device to pairing mode and try again.
  • Restart your phone. If commissioning fails or stalls, a full restart of your phone can clear stale Bluetooth state or stale Thread routes and often resolves the issue.
  • Mesh Wi-Fi access points are not blocking multicast. Some mesh Wi-Fi systems aggressively filter multicast traffic on Wi-Fi. This can prevent your phone from discovering the border router via mDNS. If you suspect this, check your mesh system’s settings for options related to multicast, IGMP snooping, or mDNS.
  • Your container platform has a limited kernel. If you are running Home Assistant as a container on a NAS or similar device, the host kernel may be missing the IPv6 routing support that Thread requires. Thread border routers announce routes to the host, and if the kernel cannot process these announcements, Thread devices cannot be reached — even after pairing appears to succeed. The most reliable solution is to migrate to a platform with a fully capable kernel, such as a dedicated device running Home Assistant Operating System or a virtual machine running a standard Linux distribution. For technical details, see the Matter Server OS requirements.

Understanding OTBR log messages

The OpenThread Border Router app logs can contain messages that look alarming but are often normal behavior. Here is what some of the most common messages mean.

ChannelAccessFailure

Handle transmit done failed: ChannelAccessFailure

This means the radio tried to transmit but the channel was too busy. The radio performs a “clear channel assessment” before sending, and if it detects other traffic, it backs off and retries. After 16 failed attempts, it reports this error.

Occasional ChannelAccessFailure messages are normal, especially on channels that overlap with Wi-Fi. If you see them frequently (multiple times per minute), consider changing the Thread channel to one with less interference, such as channel 25 or 26.

NoAck

Failed to send IPv6 UDP msg... error:NoAck

This means the border router sent a message to a device, but the device did not acknowledge it. For battery-powered devices (known as Sleepy End Devices), this is expected. These devices turn off their radio most of the time to conserve battery and only wake up periodically to check for messages. The border router queues messages and delivers them when the device wakes up.

If you see NoAck errors for a device that should be powered on and responsive, the device may be out of range or experiencing a hardware issue.

mDNSPlatformSendUDP errors

mDNSPlatformSendUDP got error 99
(Cannot assign requested address)

These errors typically appear for Docker virtual network interfaces (veth devices) and are cosmetic. The mDNS responder inside the OTBR container tries to send multicast on all network interfaces, including internal Docker bridge interfaces that cannot send multicast. These errors do not affect the border router’s ability to advertise on your actual network.