Skip to content

HA Add Matter Thread Device

Jump to bottom
guoping.liu edited this page Aug 13, 2026 · 1 revision

How to Add a Matter over Thread Device to LinuxBox

Note: Adding Matter over Thread devices is more complex than WiFi. The Companion App operations on Android phones are especially important — do not skip them!

Add via Home Assistant App

  1. The app can automatically discover Home Assistant on the local network.
  2. If you have previously connected to another HA instance, delete the old configuration first.
  3. (Android only) In the app, go to Menu → Companion App → Troubleshooting → Sync Thread credentials, and complete the sync.
image image image image
  1. In the app, go to Menu → Settings → Devices & Services → Add Integration → Add Matter device → "No, it's new".
image
  1. Put the Matter device into pairing mode first.
  2. Choose "Open Camera here" or "Setup without QR code" to scan the QR code or enter the manual code.
image
  1. Follow the app prompts to complete device addition.

Add via WebView (Advanced)

⚠️ This is not a standard method and may not work for all Matter devices. If it fails after one retry, use the Home Assistant App. If possible, contact the device manufacturer for support.

Get the Thread Dataset

In your browser, enter http://<ip_address>:8123 → Settings → Devices & Services → Thread → CONFIGURE → Click the "!" on "Preferred network" → Copy the string next to "Active dataset TLVs:".

image

Or use command line on the device:

ot-ctl dataset active -x

Commission the Device

  1. In your browser, enter http://<ip_address>:5580 to access the Python Matter Server.
  2. Click "Commission node" → "Commission new Thread device".
  3. Paste the Thread dataset and click "Set Thread Dataset".
image
  1. Put the Matter device into pairing mode.
  2. Enter the device's manual code and click "Commission".
image
  1. Wait for commissioning to complete.

Clone this wiki locally