Skip to content

Thread: migrate to a new adapter #42007

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
frenck merged 7 commits into from
Nov 27, 2025
Merged

Thread: migrate to a new adapter #42007

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7b4aac8
Thread: migrate to a new adapter
c0ffeeca7 Nov 27, 2025
713b27a
Fix typo
c0ffeeca7 Nov 27, 2025
973f453
Add troubleshooting step
c0ffeeca7 Nov 27, 2025
6ea19e3
Update source/_integrations/thread.markdown
c0ffeeca7 Nov 27, 2025
a0b57ed
Tweak
c0ffeeca7 Nov 27, 2025
5e34403
Update source/_integrations/thread.markdown
c0ffeeca7 Nov 27, 2025
5cbaf1c
Update source/_integrations/thread.markdown
frenck Nov 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions source/_integrations/thread.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,44 @@ Note: the steps and images here show the process with a Google Thread network. B
![image](/images/integrations/thread/thread-ha-preferred.png)
- 🎉 You successfully created a Home Assistant Thread network and joined it with a pre-existing third-party network.

## 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.

### Prerequisites

- [Home Assistant Operating System](/docs/glossary/#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
Comment on lines +211 to +212
Copy link
Copy Markdown
Member

@TheJulianJES TheJulianJES Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First "on" is lower-case, second "On" is upper-case, for some reason.

Everything else starts with upper-case, so that's probably the right fix:

Suggested change
- on a Home Assistant Green, where Home Assistant OS is preinstalled
- On a Home Assistant Yellow or on a Raspberry Pi
- On a Home Assistant Green, where Home Assistant OS is preinstalled
- On a Home Assistant Yellow or on a Raspberry Pi

Copy link
Copy Markdown
Member

@TheJulianJES TheJulianJES Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All of these suggestions are fixed with:

- 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 {% my supervisor_addon title="**Settings** > **Add-ons** > **OpenThread Border Router**" addon="core_openthread_border_router" %} and select the **Configuration** tab.
3. Under **Devices**, select your adapter.
4. Enter the **Baudrate** as specified in the documentation of your adapter.
- If you can't find the baudrate, contact the manufacturer's support.
- If you're feeling lucky, try `460800`.
Comment on lines +228 to +229
Copy link
Copy Markdown
Member

@TheJulianJES TheJulianJES Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: I think we can suggest users to try the de facto default for RCP firmware of 460800 before mentioning manufacturer support.

Suggested change
- If you can't find the baudrate, contact the manufacturer's support.
- If you're feeling lucky, try `460800`.
- If you can't find the baudrate, try `460800` or contact the manufacturer's support.

- **Save** your changes.
- **Troubleshooting**:
- Check the logs.
- If the add-on crashes or fails to communicate with the Thread integration: Disable the **Hardware flow control** option and try again.
Copy link
Copy Markdown
Member

@TheJulianJES TheJulianJES Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's use "Toggle" for the hardware flow control.
If it was on, it should be turned off. If it was off, it can be turned on.

Suggested change
- If the add-on crashes or fails to communicate with the Thread integration: Disable the **Hardware flow control** option and try again.
- If the add-on crashes or fails to communicate with the Thread integration: Toggle the **Hardware flow control** option and try again.

Copy link
Copy Markdown
Member

@TheJulianJES TheJulianJES Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We may also be able to mention this should be set per the manufacturer's documentation, similar to the baudrate.
But we can still keep it in the troubleshooting section here, since it doesn't hurt to just toggle it on/off if it doesn't work initially.

5. Restart the add-on and check the logs. Wait.
Comment thread
c0ffeeca7 marked this conversation as resolved.
Comment thread
c0ffeeca7 marked this conversation as resolved.
- **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.
6. Go to {% my integrations title="**Settings** > **Devices & services**" %}, select the **Thread** integration.
- Select the cogwheel {% icon "mdi:cog-outline" %}.
- **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 add-on configuration and adjust your settings, if needed and try again.
Copy link
Copy Markdown
Member

@TheJulianJES TheJulianJES Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: If we have a comma before the "if needed" part, we should also add one after it.

Suggested change
- **Troubleshooting**: If you don't see the network there, go back to the add-on configuration and adjust your settings, if needed and try again.
- **Troubleshooting**: If you don't see the network there, go back to the add-on configuration and adjust your settings, if needed, and try again.

or remove it completely:

Suggested change
- **Troubleshooting**: If you don't see the network there, go back to the add-on configuration and adjust your settings, if needed and try again.
- **Troubleshooting**: If you don't see the network there, go back to the add-on 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.
Expand Down