1. Foreword
This document explains how to use SONOFF Dongle Max (Zigbee/Thread PoE Dongle | Dongle-M) as a Thread adapter, with Home Assistant connecting to it via TCP (network) to create a Thread network, and then add Matter over Thread smart devices.
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.2.0 and later
- OpenThread Border Router App : Version 2.16.5 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 Dongle Max and connect it to LAN via ethernet or Wi-Fi
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.
You can also flash the latest OpenThread RCP firmware onto Dongle Max through its built-in Web UI. On the Web UI -> EFP32MG24 Operation Mode page, enable Thread RCP Mode as shown in the screenshot below.
For instructions on how to connect Dongle Max to LAN (Local area network) and access Dongle Max’s built-in Web UI, please refer to Dongle Max’s official Getting Started guide.
3.3. Optional: Enable Bluetooth integration on HA
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 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. Configure OpenThread Border Router App
On HA -> Settings -> Apps -> OpenThread Border Router -> Configuration page, set the correct Options:
- Enable Show unused optional configuration options.
- Device: Select any device. It will not actually take effect.
- Baudrate: Select
115200. - Hardware flow control: Disabled (false).
- Network Device:
dongle-m.local:6638. dongle-m.local is the IP address or mDNS name of Dongle Max.
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, enable Start on boot, 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.
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 the 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 record 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, enable Start on boot, Watchdog, 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’s 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 screenshots 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 device’s Pairing code to start the process of searching for and adding the device, 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.
