How to Add a Matter Device to Home Assistant

The short version of how to add a Matter device to Home Assistant is: open the companion app on your phone, go to Settings > Matter > Add device, scan the QR code, wait. The long version is everything that has to be true before that works. This guide covers the prerequisites, the Wi-Fi and Thread steps, pulling in a device that already belongs to Apple Home or Google Home, and which failures are the network’s fault.

Who this is for, and who should stop here

You need Home Assistant OS. The Matter integration docs say running the Matter Server app on Home Assistant OS “is currently the only supported option”, and it is not supported on 32-bit platforms. Container installs can run the server image by hand, unsupported. Still choosing an install type? The HAOS versus Container comparison makes the case for HAOS, and Matter is one of the strongest reasons.

You also need a phone. Commissioning uses the companion app’s Bluetooth, and even if the host has an adapter, “Home Assistant does not use that adapter.”

The checklist before you scan anything

1. IPv6 on the host. Settings > System > Network, set IPv6 to Automatic or static. The docs ask you to make sure “IPv6 (multicast) traffic travels freely from your network to the Home Assistant host.”
2. The phone. Android 8.1 minimum, 12 or newer recommended, the full Play Store build, and Location set to “Allow all the time” so the app can read the Wi-Fi SSID. iPhone needs iOS 16 or newer.
3. The right Wi-Fi. For a Wi-Fi device, the phone must be on the same 2.4 GHz network the device will join.
4. The logos. The box needs the Matter logo plus a Wi-Fi or Thread logo. The docs put it bluntly: “Thread devices don’t necessarily support Matter.”
5. Photograph the QR code. After a factory reset “you’ll need the QR code or numeric setup code to commission that device again.”

Adding a new Wi-Fi Matter device

On iPhone: Settings > Matter, Add device, “No, it’s new”, scan the QR code (or “More options” to type the 11-digit code), then Add to Home Assistant. An “uncertified accessory” prompt on a new product is fine to “Add Anyway”.

On Android: power the device up so it enters pairing mode. Android may offer a scan prompt on its own; pick Home Assistant. Otherwise go to Settings > Matter, Add device, Add Matter device, “No, it’s new”, then scan or choose “Setup without QR-code”. Either platform ends by asking for a name and an area.

Adding a Thread Matter device

A Thread device cannot reach your IP network on its own. It needs a border router, and your phone needs that border router’s Thread credentials before commissioning starts. The Matter docs list what qualifies: HomePod mini, HomePod (2nd gen) or Apple TV 4K; Nest Hub (2nd gen) or Nest Wi-Fi Pro; or Home Assistant’s own OpenThread Border Router add-on on a Connect ZBT-1, ZBT-2, SkyConnect or Yellow. Thread needs HAOS version 10 or later.

The Thread integration appears automatically once a border router is detected and stores the credentials “similar to a Wi-Fi password”. On Android, open Settings > Companion app > Troubleshooting > Sync Thread credentials. On iPhone, open Settings > Devices & services > Thread > Configure, then Send credentials to phone in the preferred network box. Import credentials from an existing Apple or Google Thread network before choosing it as preferred; the Thread documentation gives the steps for each ecosystem.

One honest warning: the OTBR add-on docs say the radio must be on “a reliable link such as UART or SPI”; a network-attached radio will “leave stale routes in your network” when it drops, stranding every Thread device. The Thread border router guide covers placement. With credentials on the phone, the steps are identical to Wi-Fi.

Adding a device that already lives in Apple Home or Google Home

No factory reset needed. Multi-admin lets one device hold several fabrics, so Home Assistant can control a bulb Apple Home still owns. In the app, Add device, then “Yes, it’s already in use”, pick the controller it belongs to and follow the prompts.

The other side has to hand over a code. In Google Home, per Google’s Matter help page, open the device, go to Settings > Linked Matter apps & services > Link apps & services, or tap “Use pairing code” or “Share with QR code” for a temporary code. Apple Home does the same from the accessory’s settings.

It works in reverse. Settings > Matter > Devices, pick the device, Share device, and Home Assistant produces a code for another platform without touching the hardware. The same page’s Manage fabrics menu is how you evict a controller later; the controller explainer covers what a fabric is.

Doing it without a phone

The Matter Server add-on docs list a ble_proxy option that will “expose the BLE proxy endpoint so the Home Assistant Matter integration can drive BLE commissioning through Home Assistant’s bluetooth stack”, replacing the older bluetooth_adapter_id setting. That covers the host’s own adapter or an ESPHome Bluetooth proxy. The integration page still documents the companion app as the supported route, so treat it as opt-in.

When it fails, it is usually the network

“Matter is unavailable” on Android means Google Play Services is still pulling the Matter modules, which can take up to 24 hours. For “Checking network connectivity”, check the documented Android prerequisites and updated Google Play Services; for Thread, bring the phone close to both the device and border router. “Device requires a border router” means a Thread device with no reachable border router or credentials that never synced. Random failures point at blocked IPv6 or mDNS.

Matter needs local IPv6 and mDNS traffic to reach the host. Check network filtering against Matter Homelab’s IPv6 requirements for Matter and Thread; use its pairing failures guide to identify the commissioning stage. Download diagnostics from Settings > Devices & services > Matter when collecting information for a support request.

When Matter is the wrong door

Philips Hue over Matter gives basic controls only; the native Hue integration keeps dynamic scenes and entertainment mode, both local. And Matter OTA updates “currently do not work for Thread devices on a Thread network with (any) Apple border routers”, so a HomePod-only mesh means firmware updates happen in the vendor app or not at all.

Add the device, name it, then leave the network alone. Most of the pain here is clever networking, not Matter.

Related on this site

• Home Assistant hardware: what to run it on
• Home Assistant OS vs Container vs Core
• Write Home Assistant automations in YAML

Related across the network

• Thread border router guide — matterhomelab.com
• Matter multi-admin sharing explained — matterhomelab.com