Connecting to Home Assistant via OTBR App(formerly Add-on)

Introduction #



Preparation #


  1. First, the Dongle, serving as the Thread adapter, must be pre-flashed with the OpenThread RCP firmware.
  2. Second, please ensure that Home Assistant has been installed and that the Dongle is inserted into the host's USB port. If not yet installed, please follow the Home Assistant installation guide.


Note: If you plan to use the Matter Server to add Matter over Thread devices, the Bluetooth integration must be enabled on HA. This can be done by navigating to HA → Settings → Devices & services → Integrations page to check whether the Bluetooth integration has been discovered and enabled.


Step 1: Install OTBR APP and Set Up a Thread Network #


If you want to set up a Thread network via Home Assistant, you need to install the OTBR APP. In addition, to add Matter over Thread devices, you can do so by adding the Matter Server APP or the Home Assistant Companion APP.

  • OpenThread Border Router APP
  • Matter Server APP / Home Assistant Companion APP

Install and Configure OTBR APP #

Go to HA homepage → Settings → Apps → Install app → App store → OpenThread Border Router, find OTBR APP and install

Configure the OTBR APP as described below.
HA → Settings → Apps → OpenThread Border Router → Configuration

  • Device: Select the Dongle running the OpenThread RCP firmware.
  • Baudrate: Select the device as ZBDongle‑E, ZBDongle‑P, Dongle‑LMG21, Dongle‑PMG24, or Dongle‑M. Options: 460800, 115200 (Select the device as Dongle‑PP10. Options: 460800, 921600).
  • Hardware flow control: Disable.


Enable the OTBR APP and set up the Thread network: In the OTBR APP, enable "Start on boot"/ "Watchblog", then click "Start".

When the OTBR starts successfully for the first time, HA will automatically enable the Thread integration. You can view the Thread network created by OTBR as follows:

HA → Settings → Devices & services → Integrations → Thread


Note: When adding a Matter over Thread device via the Matter Server APP for the first time, you need the "Active datasets TLVs". Click the "!" to the right of the Thread network name to view the "Active datasets TLVs".


Install and Configure Matter Server APP #

Follow the steps below to find and download the Matter Server APP.

HA → Settings → Apps → Install app → App store → Matter Server Install

After downloading, go to the Matter Server APP configuration and set the following:

  • Enable "Show unused optional configuration options".
  • Bluetooth Adapter ID: Default is 0 (i.e., hci0). If there are multiple Bluetooth adapters in the Bluetooth integration, select the HCI number corresponding to the Bluetooth adapter used for adding Matter over Thread devices.

Go to the Matter Server APP, enable "Start on boot"/ "Watchblog", then click "Start"to launch.
If you navigate to HA → Settings → Apps → Matter Server → Log and see the following message, it indicates a successful start.

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


Step 2: Add Matter over Thread Devices #



Method 1: Add Device via Matter Server APP #

Refer to the product manual of the Matter over Thread smart device, find and record the device's pairing code (11‑ or 21‑digit number near the Matter pairing QR code).

Open the Matter Server APP interface by following: HA → Settings → Apps → Matter Server → Info. The operation for adding a device is shown in the figure below:


Method 2: Add Device via Home Assistant Companion APP #


In the Thread integration, click the icon at the bottom‑right corner of the Thread network, then select Used for Android + iOS credential.

Refer to the product manual of the Matter over Thread device to find the Matter pairing QR code or pairing code.

Open the Home Assistant Companion APP on your phone, scan the device's Matter pairing QR code, or manually enter the pairing code as described below to add the device.

If you are using an Android phone, you must manually synchronise the Thread network credentials before adding a Matter over Thread device, as shown in the figure below.
Home Assistant Companion App → Settings → Companion app → Troubleshooting

What are your feelings

Updated on November 2, 2026