Matter over Thread on Home Assistant with SONOFF Dongle

[MichaelLearnsToCode]

1. Foreword

This document explains how to use SONOFF Dongle series products as Thread adapters to create Thread networks in Home Assistant and add Matter over Thread smart devices.

This document supports the following SONOFF Dongle products:

• SONOFF Zigbee 3.0 USB Dongle Plus | ZBDongle-E
• SONOFF Zigbee 3.0 USB Dongle Plus | ZBDongle-P
• SONOFF Dongle Lite MG21 Zigbee/Thread USB Dongle | Dongle-LMG21
• SONOFF Zigbee/Thread USB Dongle | Dongle Plus MG24
• SONOFF Dongle Max Zigbee/Thread PoE Dongle | Dongle-M

Note: For detailed information on the Thread feature in Home Assistant, please refer to the official Home Assistant Thread Integration documentation.

2. Environment

• Board Type: Raspberry Pi 4/5 , Generic x86-64
• Installation Type: Home Assistant Operating System (Version 17.0 and later)
• Home Assistant Core: Version 2026.1.0 and later
• OpenThread Border Router App : Version 2.16.3 and later
• Matter Server App : Version 8.2.2 and later
• Home Assistant Companion App : Google Play Apps, Apple App Store

3. Preparation

3.1. Access the Home Assistant Operating System front-end web interface using a browser.

If you have not yet installed, run, and configured the Home Assistant Operating System (aka. HA), please refer to the official Home Assistant Installation Guide.

3.2. Flash the OpenThread RCP firmware onto the SONOFF Dongle and connect it to HA via USB.

SONOFF officially provides three methods for flashing firmware onto Dongle series products:

• SONOFF Dongle Flasher Web App: Connect to Windows/macOS/Linux via USB and use a browser to flash the Dongle firmware. Please refer to https://dongle.sonoff.tech/guide/dongle-pmg24/how_to_flash_openthread_firmware/.

• SONOFF Dongle Flasher HA App: Connect to HA via USB and flash the Dongle firmware through HA front-end web interface. Please refer to https://dongle.sonoff.tech/guide/dongle-pmg24/flash-firmware-via-home-assistant-add-on/.

• SONOFF Dongle Flasher Docker Image: Connect to Windows/macOS/Linux via USB, start a Docker container, and use the container’s web console to flash the Dongle.

Connect the Dongle, which has the OpenThread RCP firmware flashed, to HA, and confirm the Dongle’s file path on HA → Settings → System → Hardware → All Hardware page, as shown in the following screenshot:

Note: The file path for Dongle is usually /dev/ttyUSB0 or /dev/ttyACM0.
Note: Although the screenshots in this document use the Dongle Plus MG24 | Dongle-MG24 as examples, the content of this document applies to all SONOFF Dongle series products mentioned in 1. Foreword.

3.3. Optional: Enable Bluetooth integration on HA

If you plan to use the Matter Server App’s Web UI instead of the Home Assistant Companion App to add Matter over Thread smart devices, you must enable Bluetooth integration on HA.

You can check whether Bluetooth integration is discovered and enabled on HA → Settings → Devices & services → Integrations page, as shown in the screenshot below.

Note: Raspberry Pi 4/5 comes with built-in Bluetooth hardware. Generic x86-64 hosts usually require an additional USB Bluetooth Adapter. Please refer to HA Bluetooth Integration official documentation for details.

4. Install, configure, and run OpenThread Border Router App

4.1 Install OpenThread Border Router App

On HA → Settings → Apps → Install app → App store → OpenThread Border Router page, click the Install button to download and install OpenThread Border Router App, as shown in the screenshots below.

4.2. Configuring OpenThread Border Router App

On HA → Settings → Apps → OpenThread Border Router → Configuration page, set the correct Options:

• Device: Select the Dongle running OpenThread RCP firmware.
• Baudrate: Select 460800 for ZBDongle-E, ZBDongle-P, Dongle-LMG21, and Dongle-PMG24, and select 115200 for Dongle-M.
• Hardware flow control: Disabled (false).

Note: Incorrect settings will cause OpenThread Border Router App to malfunction.

4.3. Start OpenThread Border Router App and configure Thread network.

On HA → Settings → Apps → OpenThread Border Router → Info page, check Start on boot and Watchdog, and click the Start button, as shown in the screenshot below.

Then switch to HA → Settings → Apps → OpenThread Border Router → Log page to view the logs. If you see:

s6-rc: info: service otbr-agent-configure successfully started 
s6-rc: info: service otbr-agent-configure successfully started 
s6-rc: info: service otbr-agent-rest-discovery successfully started 
s6-rc: info: service legacy-services successfully started

then OpenThread Border Router App has successfully started and is running correctly, as shown in the screenshot below.

Note: Messages such as “DuaManager----: Failed to perform next registration: NotFound” in the log can be ignored.

After OpenThread Border Router App starts successfully for the first time, HA will automatically enable Thread integration. You can view the thread network created by OpenThread Border Router App by clicking the Configure button on HA → Settings → Devices & services → Integrations → Thread page, or on HA → Settings → Thread page, as shown in the screenshots below.

Note: If no Thread network starting with ha-thread is found, please reboot the system (not Restart Home Assistant). If the Thread network starting with ha-thread is not a Preferred network, please set it as the Preferred network.

Please click the Info icon to the right of the Thread network starting with “ha-thread” to view and save the Active dataset TLVs, as shown in the screenshot below.

Note: This Active dataset TLVs is needed when adding Matter over Thread smart devices via Matter Server App’s Web UI for the first time.

5. Install, configure, and run Matter Server App

5.1. Install Matter Server App

On HA → Settings → Apps → Install app → App store → Matter Server page, click the Install button to download and install Matter Server App, as shown in the screenshot below.

5.2. Optional: Configure Matter Server App

If you plan to use Matter Server App’s Web UI instead of Home Assistant Companion App to add Matter over Thread smart devices, you must set the correct Bluetooth adapter ID for Matter Server App.

On HA → Settings → Apps → Matter Server → Configuration page, set the correct Options:

• Enable Show unused optional configuration options
• Bluetooth Adapter ID: The default is 0 (i.e., hci0). If there are multiple Bluetooth adapters in Bluetooth integration, please select the hci number corresponding to the Bluetooth adapter used to add Matter device.

5.3. Start Matter Server App

On HA → Settings → Apps → Matter Server → Info page, check Start on boot, Watchdog, and Add to sidebar, and then click the Start button, as shown in the screenshot below.

Then switch to HA → Settings → Apps → Matter Server → Log page to view the logs. If you see:

INFO [matter_server.server.server] Matter Server successfully initialized.

Then Matter Server App has successfully started and is running correctly, as shown in the screenshot below.

6. Add Matter over Thread new device

6.1. Adding a new Matter over Thread device using Matter Server App Web UI

Please refer to the product manual of your Matter over Thread smart device to put the device into Pairing mode and write down the device’s Pairing code (11 or 21 digits of numbers near the Matter pairing QR code).

On HA → Settings → Apps → Matter Server → Info page, click the Open Web UI button, or click Matter Server menu in HA sidebar to open Matter Server App Web UI page. Then click the Commission node button on the page, select Commission new Thread device, set the Thread dataset (the Active dataset TLVs mentioned above), enter the device Pairing code, and click the Commission button to start the process of searching for and adding the device, as shown in the screenshots below.

6.2. Add a new Matter over Thread device using Home Assistant Companion App

On HA → Settings → Thread page, click the Overflow menu icon to the right of the Thread network starting with ha-thread, and select Used for Android + iOS credentials, as shown in the screenshot below.

Please refer to the product manual of your Matter over Thread smart device to put the device into Pairing mode and write down the device’s Pairing code (11 or 21 digits of numbers near the Matter pairing QR code).

On Home Assistant Companion App → Settings → Devices & services → Integrations → Matter page, or on Home Assistant Companion App → Settings → Matter page, click the Add device button, select No. It’s new, and then follow the prompts to scan the device’s Matter pairing QR code, or manually enter the Pairing code to start the search and add device process, as shown in the screenshots below.

If you are using an Android phone, before adding a Matter over Thread device, you must manually synchronize Thread network credentials by clicking the Sync Thread credentials entry in Home Assistant Companion App → Settings → Companion app → Troubleshooting page, as shown in the screenshots below.

[jam3]

It would be reasonable to publish a list of current firmware versions on the Sonoff Dongle Flasher website.

[MichaelLearnsToCode]

Currently, the type and version of firmwares are displayed after the Dongle is plugged in, it is a good idea to show those information in advance. We’ll get it done ASAP.

[jam3]

@MichaelLearnsToCode

We’ll get it done ASAP.

Great! Thanks, this will make version checking much easier.

Good thing you mention granting permissions to the Companion App — it took me a while to figure that out. It seemed obvious that this would happen by default, but nope. The Home Assistant documentation very elegantly glosses over this detail.