This guide explains how to add Matter over Thread devices to Home Assistant and provides troubleshooting steps for common issues.

1. This document is organized into the following sections:

2. Pairing Process Overview

3. Pre-Setup Environment Checks

4. Configure a Thread Border Router

5. Sync Thread Network Credentials to Your Phone

6. Start Matter Pairing

7. Troubleshooting & Reference Documentation

1. Pairing Process Overview

Matter over Thread pairing is typically completed in the following order:

1. Verify that the Home Assistant Thread network is working properly

2. Sync Thread credentials to your phone

3. Put the device into pairing mode

4. Use the Home Assistant Companion App to scan the QR code and pair

5. Device joins Home Assistant

If any step is not completed correctly, the Thread device may fail to function properly. It is strongly recommended to follow this guide in order.

2. Pre-Setup Environment Checks

Before starting Matter over Thread pairing, please confirm the following environment settings are properly configured.

2.1 Home Assistant and Device Environment

2.2 Home Assistant Services and Thread Network Environment

2.3 Important Notes for Android Users

Android Matter over Thread pairing depends on Google Services.

Please confirm:

• Google Services Framework is installed on your phone

• Google Home App is installed and signed in

• Google Home remains running in the background during pairing

Otherwise, you may encounter the error: “Matter is currently unavailable.”

3. Configure a Thread Border Router

If you have already completed Thread Border Router setup, you may skip directly to Section 4.

Different Thread Border Routers require different setup methods.

Some devices require manually flashing OpenThread RCP firmware before use, while others come with firmware preinstalled and can be used directly.

Examples:

• Sonoff Dongle-M / Dongle Plus MG24 requires firmware flashing by following the generic OTBR setup process in Section 3.1

• SMLight SLZB-06mu / Home Assistant Connect ZBT-2: Firmware is preinstalled by default and does not require manual flashing. Please follow the pre-flashed OTBR setup process in Section 3.2 and switch the device to either Thread RCP mode or Thread + OTBR running on device mode (the displayed option name may vary depending on the product).

3.1 Generic OpenThread Border Router (OTBR) Setup

Step 1: Flash OpenThread RCP Firmware

For Sonoff Dongle-M / Dongle Plus MG24: Visit: https://dongle.sonoff.tech/sonoff-dongle-flasher/ Flash the OpenThread RCP firmware.

Step 2: Install the OTBR Add-on

Path: HA → Settings → Add-ons → OpenThread Border Router → Install

Step 3: Configure Parameters

Path:

HA → Settings → Add-ons → OpenThread Border Router → Configuration → Options (top-right) → Edit in YAML

Enter:
device: /dev/ttyUSB0
baudrate: "115200"
flow_control: false
otbr_log_level: notice
firewall: true
nat64: false
beta: false

Important: The device field and baudrate must match your current hardware model. Otherwise, OTBR may fail to start or fail to create a Thread network.

Device Field Information
Example:
device: /dev/ttyUSB0

Check the correct device path here: Settings → System → Hardware → All Hardw

Baudrate Information

Incorrect baudrate settings are one of the most common configuration issues. The required baudrate depends on the device model and USB bridge chipset.

Step 4: Start the OTBR Add-on

Start the OpenThread Border Router add-on.

Step 5: Verify Configuration

Go to: HA → Settings → Devices & Services → Thread

Confirm that a Thread network is visible.

3.2 Pre-Flashed OTBR Setup Method

(Example: Home Assistant Connect ZBT-2)

• Plug the ZBT-2 into a USB-A port on the HA device

Note: Avoid using blue USB 3.0 ports

• HA should automatically detect the device and display a protocol selection prompt

• Select Thread (the displayed option name may vary depending on the product)

• HA will automatically complete the configuration

• It is recommended to position the antenna vertically and place the device near the center of the house

• Verify successful setup:

HA → Settings → Devices & Services → Thread → Confirm the Thread network is visible

4. Thread Credential Synchronization

⚠️ This is one of the most commonly overlooked steps in Matter over Thread pairing and also one of the most common causes of pairing failures or “Thread network not found” issues.

During Matter pairing, the phone must first obtain the Thread credentials currently used by Home Assistant so it can help the device join the correct Thread network.

4.1 Set Preferred Network

This step is performed inside Home Assistant to register the Thread network as the system preferred network.

Path:

1. Go to HA → Settings → Devices & Services → Thread

2. Locate the Thread network (usually shown as ha-thread-xxxx)

3. Click the three-dot menu (⋮) next to the Border Router

4. Select “Used for Android + iOS credentials”

5. Confirm the network appears at the top of the Preferred Network section

4.2 Sync Thread Network Credentials

4.2.1 iPhone

Make sure the iPhone and HA are connected to the same Wi-Fi network.

1. Open the HA App

2. Go to: Settings → HA App → Thread

3. Wait for automatic synchronization

If synchronization fails:

• Fully close and reopen the app

• Clear app cache if necessary

4.2.2 Android (Requires Google Home App)

Make sure the phone and HA are connected to the same Wi-Fi network.

1. Open the Google Home App and keep it running in the background ⚠️ Android itself does not manage Thread credentials directly, so Google Home is required as an intermediary tool.

2. Open the HA App

3. Go to: Settings → HA App → Troubleshooting → Sync Thread Credentials

4. Repeatedly tap Sync until the following message appears: “Home Assistant and this device use the same network.”

• If synchronization continuously fails: Clear Google Play Services data and try again

5. Start Pairing the Thread Device

• Confirm the Thread Border Router is working properly in the HA App

• Confirm the Thread network has been set as the Preferred Network

• Confirm the phone has synchronized Thread credentials

• Temporarily disable other non-HA Thread Border Routers (such as Google Nest Hub) to avoid interference

• Power on the Meross device (For the Meross Smart Presence Sensor Thread MS605, wait approximately 30 seconds after power-on for stabilization)

• Enter pairing mode (For example: on MS605, press and hold the button for 5 seconds until the indicator rapidly flashes amber)

• Open the HA App and ensure Bluetooth is enabled

• Scan the device QR code to add the device

• Once pairing succeeds, the device will appear online in the HA device list

Example:

After successfully adding MS605 to HA, four sensors will appear:

• MS605 Illuminance

• Occupancy (2)

• Occupancy (3)

• Occupancy (4)

You may then refer to the corresponding product FAQ for further customization settings. https://www.meross.com/en-gc/FAQ/781.html

6. Troubleshooting

6.1 No Thread Network Appears in Home Assistant / Thread Border Router Not Found / Border Router Setup Failed

Please refer to Section 3 and check the following in order:

1. Confirm the Thread Border Router is properly connected to HA

• For USB devices, confirm the device is plugged in

• For network-based devices, confirm network connectivity is working properly

2. Confirm the OpenThread Border Router (OTBR) add-on is running Path: HA → Settings → Add-ons → OpenThread Border Router

3. Check whether the device field and baudrate are configured correctly Incorrect baudrate settings are one of the most common causes of setup failure.

4. Check whether HA recognizes the Thread Border Router Path: HA → Settings → System → Hardware → All Hardware

5. Restart the entire Home Assistant system and check again ⚠️ It is recommended to reboot the entire HA system rather than only restarting the Home Assistant service.

6.2 HA Shows the Thread Network Is Working, but Thread Credential Sync Fails

Please refer to Section 4 and check the following in order:

• Confirm the phone and HA are connected to the same Wi-Fi network (Strongly recommended: both connected to 2.4GHz Wi-Fi)

• Confirm the Thread network is set as the Preferred Network Path: HA → Settings → Devices & Services → Thread

Confirm that the current Thread network is displayed at the top of the Preferred Network section.

• Sync Thread credentials via: HA App → Settings → Companion App → Troubleshooting → Sync Thread Credentials (Repeatedly tap Sync until synchronization succeeds)

Important:

• Android requires the Google Home App to remain open in the background during synchronization

• If synchronization fails on iOS, try restarting the phone or the relevant device

• Clear Google Play Services data and retry

6.3 Pairing Starts but Fails or Gets Stuck

Please troubleshoot in the following order:

1. Temporarily disable other non-HA Thread Border Routers (such as Google Nest Hub) to avoid interference

2. Confirm the phone has completed Thread credential synchronization Please complete all steps in Section 4 first.

3. Confirm the device has correctly entered Matter pairing mode Example for MS605: Press and hold the device button for approximately 5 seconds until the indicator rapidly flashes orange.

4. Confirm the HA Matter Server is running properly Path: HA → Settings → Add-ons → Matter Server → Start Matter Server

5. Use the Meross App to check whether the device firmware is up to date. If not, update the firmware and retry.

If the issue persists after updating to the latest firmware, please contact Meross Technical Support for further assistance.

6.4 Frequent Pairing Failures / Device Frequently Offline or Unresponsive

Possible causes:

1. Device is too far from the Thread Border Router

2. Thread channel interference from Wi-Fi networks

Solutions

1. Check Distance Between Device and Thread Border Router

For initial pairing, it is recommended to place the device within 3 meters of the Thread Border Router.

Additional recommendations:

• Place the Border Router near the center of the house

• Avoid placing it inside metal cabinets, weak-current boxes, or behind large appliance

2. Try Changing the Thread Channel

In crowded wireless environments, the Thread network may experience Wi-Fi interference.

Generally:

• Channel 26: Least affected by Wi-Fi interference (recommended first)

• Channel 25: Also reduces interference but may still overlap with some Wi-Fi channels

If OTBR logs frequently display: “ChannelAccessFailure”

This usually indicates that the current wireless channel is excessively congested.

How to Change the Thread Channel

1. Go to: HA → Settings → Devices & Services → Thread

2. Select: Configure

3. Change the Thread Channel (Recommended: Channel 26 or 25)

4. Wait approximately 5 minutes for the network to switch automatically

⚠️ During the switch process:

• Do NOT restart the Border Router

• Do NOT modify other network settings

• If devices do not reconnect automatically after the switch completes: Restart the device and test again

7. Official Reference Documentation

Home Assistant

• HA Thread Integration Documentation

• HA Matter Integration Documentation

• HA Connect ZBT-2 Official Page

• HA OpenThread Border Router Documentation

• HA Connect ZBT-2 Setup Guide

SONOFF

• SONOFF Official Flashing Tool

• SONOFF Matter over Thread Tutorial

• SONOFF MG24 Plus Product Page

SMLIGHT

• SMLIGHT SLZB-06mu Thread Configuration

• SMLIGHT Matter over Thread Guide