Matter devices talk over your existing IP network. Wi-Fi and Ethernet Matter plugs and bulbs join the same LAN as Home Assistant. Thread Matter sensors and locks join a low-power mesh, and a Thread border router bridges that mesh to your LAN. In both cases Home Assistant runs its own Matter controller: the Matter Server app on Home Assistant OS.

This guide follows the official Home Assistant Matter and Thread documentation. It covers what you need before the first device, how to commission a new one from the Companion app, how to share a device that already lives in Apple Home or Google Home, and the network mistakes that make commissioning fail.

Matter, Thread and Bluetooth

Matter is a control protocol. It does not invent its own radio. Devices either use Wi-Fi (or Ethernet) or Thread for transport, and they speak Matter on top. Thread alone does not control a device; Matter or Apple HomeKit does. Do not assume Matter support from a Thread logo on the box. Look for the Matter logo, or a clear statement from the manufacturer.

Commissioning (Matter's word for pairing) uses Bluetooth on almost every device. That Bluetooth link is only for the first setup: your phone sends network credentials to the device. After that, control runs over Wi-Fi or Thread. Home Assistant does not use a Bluetooth adapter on the server for this. You need the Companion app on a phone close to the device.

Multi-fabric is the other important idea. The same physical device can join several controllers at once. The standard says each device should support at least five fabrics. You can run a bulb in Google Home, Apple Home and Home Assistant without choosing one ecosystem. For products that already have a native Home Assistant integration with a local API, Matter is often the thinner option. Philips Hue is the docs' example: Matter gives basic light control, while the Hue integration keeps scenes and entertainment mode.

What you need before adding a device

Home Assistant. Use Home Assistant OS. That is the supported path for the Matter Server app. Other installs can run a Matter Server container, but Home Assistant marks that as unsupported and at your own risk. Install the Matter integration under Settings > Devices & services. On a normal Home Assistant OS setup, leave the checkbox for the official Matter Server app enabled and select Submit. The official app is not supported on 32-bit platforms.

The device. Check the packaging for the Matter logo and for either Wi-Fi or Thread. Keep the QR code or numeric setup code. After a factory reset you will need it again. If the code is only in the paper booklet, photograph it and store it somewhere safe.

Your phone. Bluetooth must be on.

  • Android: version 8.1 at minimum, 12 or higher recommended. Install the full Companion app from the Play Store. Set the app's Location permission to Allow all the time. During commissioning Google's Matter UI comes to the foreground and the Companion app runs in the background; with Location set to "While using the app", Android can block Wi-Fi SSID access and commissioning fails. For Thread you need a border router on the network: Nest Hub (2nd gen), Nest Wi-Fi Pro, or Home Assistant with the OpenThread Border Router app.
  • iPhone: iOS 16 or higher, latest Companion app. For Thread you need a HomePod mini or HomePod (2nd gen), an Apple TV 4K, or Home Assistant with the OpenThread Border Router app.

Keep the phone near both the device and, for Thread, the border router. For a Wi-Fi Matter device, put the phone on the same 2.4 GHz network the device will use. Many Matter Wi-Fi devices only join 2.4 GHz.

IPv6. Matter depends on local IPv6 and mDNS. You do not need an IPv6 internet connection or a DHCPv6 server, but IPv6 must be enabled on Home Assistant: Settings > System > Network, set IPv6 to Automatic or a static address. Keep Matter Wi-Fi devices and Thread border routers on the same LAN or VLAN as Home Assistant. Enterprise tricks that "optimize" multicast, filter IGMP, or segment everything into VLANs regularly break discovery.

Add a new device on iPhone

  1. Open the Home Assistant Companion app.
  2. Go to Settings > Connectivity > Matter.
  3. Select Add device.
  4. When asked whether the device is already in use, select No. It's new.
  5. Scan the QR code, or choose More options… and type the commission code.
  6. Select Add to Home Assistant. Commissioning can take a few minutes.
  7. For a test board or beta device you may see Uncertified Accessory. Select Add Anyway.
  8. If iOS asks for an Accessory Name, enter anything you like. That name is internal to iOS and does not appear in Home Assistant.
  9. When the phone shows Done, Home Assistant opens the Device added dialog. Optionally set a name and area, then Finish.

Add a new device on Android

  1. Open the Companion app and power the device (or insert batteries). Most devices enter pairing mode on first power. Some need an explicit pairing gesture; check the manufacturer's sheet.
  2. Some phones show a system pop-up to scan the QR code. Scan it, choose Home Assistant when asked which app to use, then finish and select Add device.
  3. If there is no pop-up, go to Settings > Connectivity > Matter, select Add device, choose No. It's new., and scan the code or use Setup without QR-code.
  4. After Done, set the name and area in Home Assistant the same way as on iOS.

Share a device that already lives in Apple or Google Home

If the device is already on another fabric and you want Home Assistant as well:

  1. Open the Companion app and go to Settings > Connectivity > Matter.
  2. Select Add device, then Yes. It's already in use. and pick the controller (for example Google Home).
  3. Follow the on-screen steps from that ecosystem. When it succeeds, you control the device from both places.

You can also go the other way: share from Home Assistant into Apple or Google Home. Open the device under Settings > Connectivity > Matter > Devices, select Share device, confirm, then scan the QR code or enter the sharing code in the other app. You do not need to press a hardware button on the device. Under the three-dot menu, Manage fabrics lists every fabric the device belongs to.

Matter bridges

Some hubs expose non-Matter devices over Matter: SwitchBot Hub 2, Aqara Hub M2, IKEA Dirigera and the Philips Hue Bridge are examples in the docs. You commission the bridge itself as a Matter device, and selected child devices appear in Home Assistant. Not every device type on a bridge is exposed. SwitchBot Hub 2 V1.5, for example, can bridge curtains, locks and blinds, but not lights.

Bridging is not always a win. The Hue Bridge supports Matter, but Matter only covers a limited feature set. The native Hue integration already runs locally and keeps the Hue-specific features, so the docs advise against bridging Hue into Home Assistant via Matter.

Home Assistant is a Matter controller, not a bridge. It cannot turn your existing Zigbee or Wi-Fi devices into Matter devices for other ecosystems.

Thread border routers

A Thread Matter device needs a border router nearby. Supported third-party ones that work with Home Assistant include Nest Hub (2nd gen), Nest Hub Max, Nest Wifi Pro, Nest Wifi, Google TV Streamer (4K), HomePod (2nd gen), HomePod mini, and Apple TV 4K (2nd and 3rd gen Wi-Fi + Ethernet models). Nanoleaf and Amazon also ship products with border router capability.

Home Assistant Connect ZBT-1, Connect ZBT-2 and Yellow ship with Zigbee firmware. Enabling Thread means installing the OpenThread Border Router app and following the hardware-specific guide. The Thread docs still describe the integration of that Home Assistant border router with Matter as work in progress, so many people start with an Apple or Google border router they already own.

If you create a Home Assistant Thread network (ha-thread-xxxx), sync its credentials to the phone before commissioning:

  • Android: Companion app Settings > Companion app > Troubleshooting > Sync Thread credentials.
  • iPhone: Companion app Settings > Connectivity > Thread, then Send credentials to phone on the preferred network.

Without those credentials on the phone you get errors such as this device requires a border router.

When commissioning fails

"You need to use the Home Assistant Companion app." Adding a new Matter device only works in the phone app, not in a desktop browser. On the phone, check the OS and app requirements above. Android Automotive is not supported. The Mac Companion app cannot commission Matter devices; use an iPhone or iPad. iOS or iPadOS needs 16.4 or higher for this path.

"Matter is unavailable" on Android. Google Play Services may still be downloading Matter modules. Wait up to 24 hours, keep Play Services updated, use a normal Google-account Android build (not an alternative ROM), and confirm Settings > Google > Devices & Sharing lists Matter devices. Reinstalling the Companion app, or installing the Google Home app to nudge the modules, are steps the docs list next.

Stuck at "Checking network connectivity". Re-check the Android version, Play Services, and that the phone sits on the same 2.4 GHz SSID for Wi-Fi devices, or near the border router for Thread.

Random failures or devices that vanish. Flatten the network. Put Home Assistant, Wi-Fi Matter devices and Thread border routers on the same LAN. Avoid multicast filtering and over-segmented VLANs. Start with one Wi-Fi Matter device or an ESP32 Matter example from Nabu Casa's matter-example-apps page before you scale up.

OTA updates on Thread with Apple border routers. Home Assistant can offer Matter OTA updates when the manufacturer publishes them to the CSA Distributed Compliance Ledger (Eve and Nanoleaf are named in the docs). Those updates currently fail for Thread devices when any Apple border router is on the network, with Target node did not process the update file. Apple border routers do not forward the mDNS packets needed to find Home Assistant's update provider. Use Apple's own update path, add a non-Apple border router, or temporarily power down Apple border routers for at least 30 minutes and retry.