> ## Content Index > Fetch the complete content index at: https://homeoslab.com/llms.txt > Use this file to discover other available public pages before exploring further. # Getting Started with Matter in Home Assistant - URL: https://homeoslab.com/guides/getting-started-matter/ - Published: 2026-08-30T23:45:55.000Z - Updated: 2026-09-03T18:51:26.000Z - Description: Matter promises one setup flow for every smart-home brand. Here's what actually happens the first time you scan the code — and how to get a clean pairing on the first try. - Author: HomeOS Lab - Tags: Guides, Matter, Thread, Getting Started **By HomeOS Lab · Last updated 3 September 2026** > **Difficulty:** Beginner · **Time:** \~20–30 min · **You'll need:** Home Assistant 2026.x, one Matter device, and either a **Thread border router** (for Thread devices) or a Wi-Fi Matter device. Matter promised one thing above all: buy a device with the Matter logo and it just works, locally, with whatever smart-home platform you already run — Home Assistant included. Mostly, it delivers. But "just works" hides a few decisions (Thread vs Wi-Fi, which border router, how to commission a device that's already tied to Apple or Google) that trip up first-timers. This guide walks through adding your **first** Matter device to Home Assistant end to end — what you actually need, the exact steps, the two or three pitfalls that cause 90% of the pain, and how to **confirm you got true local control** rather than a cloud round-trip. --- ## First, the 60-second mental model Matter is the **application/language** devices speak. It rides on top of a **transport**: - **Matter-over-Wi-Fi / Ethernet** — the device joins your normal network. No extra hardware. - **Matter-over-Thread** — the device speaks **Thread**, a low-power mesh (like Zigbee's cousin). Thread devices need a **Thread border router** to reach your IP network. So the one question that determines your shopping list: **is your device Thread or Wi-Fi?** - **Wi-Fi Matter device** (many plugs, some bulbs) → you need nothing extra. - **Thread Matter device** (many sensors, locks, low-power gear) → you need a **Thread border router**. You may already own one: a **Home Assistant Connect ZBT-1** running Thread firmware, an Apple HomePod/TV, a Google Nest Hub, or an Aqara/Eve hub can all serve as border routers. > **Key point for HA users:** Home Assistant can *use* border routers provided by other ecosystems. You don't have to buy Apple's or Google's hardware just for Home Assistant — but if you already have one, HA can share its Thread network. --- ## What you'll need (checklist) - \[ \] **Home Assistant 2026.x** (Matter support is built in; keep HA updated). - \[ \] The **Matter** integration enabled in HA (it uses the Matter Server add-on / built-in service). - \[ \] **One Matter device** with the Matter logo on the box. - \[ \] The device's **Matter setup code** — an 11-digit numeric code and/or a QR code, on the device or in its manual. *Guard this code; it's the pairing secret.* - \[ \] For a **Thread** device: a working **Thread border router** on the same network. - \[ \] Your phone with the **Home Assistant Companion app** (the easiest way to scan the QR code). --- ## Step 1 — Enable the Matter integration in Home Assistant 1. In Home Assistant, go to **Settings → Devices & Services → Add Integration**. 2. Search **Matter** and add it. HA runs a **Matter Server** (as an add-on on HA OS/Supervised, or a container elsewhere) — accept the default local server unless you have a specific reason not to. 3. Confirm the Matter integration shows **connected**. ## Step 2 — (Thread devices only) Confirm you have a Thread border router 1. Go to **Settings → Devices & Services → Thread**. HA lists Thread networks it can see. 2. If you have a **Connect ZBT-1 on Thread firmware**, an **Apple** or **Google** border router, or an **Eve/Aqara** hub, it should appear here. HA can commission Thread devices onto a **preferred** network. 3. If the list is empty and your device is Thread, stop here and set up a border router first — a Thread device cannot be added without one. > **Pitfall #1 — "no Thread networks found."** This is the most common beginner wall. It almost always means you have a Thread *device* but no Thread *border router* yet. Wi-Fi Matter devices skip this entire step. ## Step 3 — Put the device into pairing mode Factory-fresh devices are usually ready to commission out of the box. If the device was **previously paired** to Apple Home, Google Home, or another controller, you must either: - **Reset it** to factory (check the manual — usually a button hold), **or** - Use **multi-admin sharing**: in the other app (e.g. Apple Home → device → *Turn On Pairing Mode* / *Add to other platform*), generate a **new setup code** and use that in Home Assistant. > **Pitfall #2 — the device is already claimed.** A Matter device can belong to several ecosystems at once (that's the point), but each controller needs its **own** setup code. If HA says the code is invalid, you're likely trying to reuse the printed code on a device another app already owns — generate a fresh pairing code from that app instead. ## Step 4 — Commission the device into Home Assistant 1. In HA: **Settings → Devices & Services → Add Integration → Matter → Add Matter device** (easiest from the **Companion app** so you can scan). 2. **Scan the QR code** or enter the 11-digit setup code. 3. For a Thread device, pick the **Thread network** to join when prompted. 4. Wait for commissioning — this can take **1–3 minutes**. The device joins your network, exchanges certificates, and appears in HA. 5. Name it and assign it to an **Area**. Done. ## Step 5 — Confirm you got *local* control (the part people skip) The whole reason to run Home Assistant is local control. Prove you have it: 1. Toggle the device from the HA dashboard — response should be effectively **instant**. 2. **Disconnect your internet** (unplug the WAN, not your LAN) and toggle it again. If it **still works**, you have genuine local control. Matter devices are local by design, so this should pass — and it's a satisfying thing to verify on day one. > **Pitfall #3 — expecting Matter to expose *everything*.** Matter standardizes *core* functions (on/off, brightness, sensor readings). Some vendor-specific features (fancy effects, device settings) may only appear in the vendor's own app or via the device's other integration path (e.g. its Wi-Fi/cloud integration). For most people the Matter feature set is exactly what they want; just don't be surprised if one niche toggle is missing. --- ## Troubleshooting the three things that go wrong | Symptom | Most likely cause | Fix | | -------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | "No Thread networks found" | No Thread border router on the network | Set up a border router (Connect ZBT-1 / HomePod / Nest / Eve / Aqara) first | | "Setup code invalid" | Device already commissioned by another app | Reset the device, or generate a new pairing code via multi-admin in the other app | | Commissioning stalls / times out | Weak Thread signal, or HA too far from device during pairing | Commission near the border router; add a mains-powered Thread router device to strengthen the mesh | | Device pairs but is laggy | Cloud fallback / poor mesh | Verify local control (Step 5); check border-router placement | --- ## Where to go next - **Deep dive on the standards:** [HomeKit vs Matter vs Thread — the 2026 standards landscape](https://homeoslab.com/news/standards-landscape-2026/) - **Choosing a protocol for a new build:** [Zigbee vs Z-Wave vs Thread vs Wi-Fi for Home Assistant](https://homeoslab.com/guides/zigbee-vs-zwave-vs-thread-vs-wifi/) - **The radio that also does Thread:** [Best Zigbee coordinators for Home Assistant (2026)](https://homeoslab.com/best-of/zigbee-coordinators/) — the Connect ZBT-1 doubles as a Thread border router. - **Add more devices:** [How to add a Matter device to Home Assistant](https://homeoslab.com/guides/add-matter-device/) *(companion quick-reference)* --- ## FAQ **Do I need a hub for Matter with Home Assistant?** For **Wi-Fi** Matter devices, no — Home Assistant is the controller. For **Thread** devices, you need a **Thread border router** (which you may already own via Apple/Google/Eve/Aqara, or add via a Connect ZBT-1). **Can a Matter device work with Home Assistant *and* Apple/Google at the same time?** Yes — that's Matter's multi-admin feature. Each controller commissions the device with its own setup code. **Is Matter fully local with Home Assistant?** Yes, Matter control is local by design. Verify it with the internet-off test in Step 5. ---