If you are new to Matter, check the official Matter integration docs! Specifically read the Adding a Matter device to Home Assistant which walks you through all the steps necessary to add a device. This post adds some more information and other commissioning options if you have problems or you are seeking for other ways to commission devices.
The recommended commissioning mode for Matter devices is currently through the official Home Assistant companion apps. Both, the Android companion app and the iOS companion app support Matter commissioning and rely on APIs made available by Android and iOS. On Android, that means you need to have the full Android app (and a Android device with Google Play Store services available). The main reason to use the Apps is convince: Matter requires the user to scan a QR code and then Bluetooth during commissioning. QR scanning and Bluetooth is possible directly from phones/tables, so this allows for a sleek user experience.
Note that while this process uses Google/Apple framework capabilities, it ultimately connects the Matter device directly with the Home Assistant Matter controller.
If you on-board a Thread based Matter device, make sure you have the credentials transferred to your phone, especially if you are using the Home Assistant Connect ZBT-1/SkyConnect and/or the OpenThread Border Router add-on. See the Thread integration documentation on how to import the Thread credentials to your phone. For Google or Apple based Thread border routers the credenitals should already be present on your phone.
Note that on Android there are two methods to commission a device:
a) Through the “half-screen pop-up” (which appears directly on the home screen if a commission-able device is nearby)
b) Through the Home Assistant companion app (Settings → Devices & Services → Devices, Add Device → Add Matter device)
If you are seeking for help, please state which method you tried. The two methods use different APIs on the Matter Server end.
The commissioning process through companion apps is a two step process: First the device is connected to the network in a “pre-commissioning” phase.
If you get an error during this phase, the problem is with your phone or it’s connectivity. Make sure that your phone is on the same network the Matter device is supposed to connect to. The SSID the phone is on must be the same as the Matter device. It must support 2.4GHz WiFi for almost all Matter devices.
If the commissioning fails during the second phase, make sure Home Assistant is in that same network as well, so it can find the device through mDNS or link-local IPv6 addressing. Check the Matter Server add-on logs as well, it might have additional insights why the commissioning failed exactly.
Besides the recommended method through the companion apps, it is also possible to ask the Home Assistant Matter Server to commission a device directly. In that scenario, the Matter Server requires a local Bluetooth adapter and the device needs to be in close proximity of that adapter (definitely below 10m, better a couple of meters).
This is experimental/advanced. It is more meant for development and testing.
If you have a local Bluetooth adapter, make sure to disable the Home Assistant Core Bluetooth integration accessing the adapter or use a dedicated Bluetooth adapter for Matter. The Matter Server needs exclusive access for commissioning to work reliable.
With the Matter Server add-on 6.3.0 and newer you have to configure which Bluetooth adapter to use. If you have multiple Bluetooth adapter in your system, check the integration title or the discovery entry for the string hciX, where X is the Bluetooth adapter number. You can use a second adapter dedicated for Matter, e.g. in this case I plugged in an ASUS USB-BT500 and left it unconfigured on Home Assistant Core side
In the Settings ->Add-ons → Matter Server → Configuration I then set the Bluetooth Adapter ID to 1:
Commissioning is also possible through the Matter Server add-on Web UI.
To commission a Thread device through this method you need to have a local OpenThread border router. You then can find the Thread credentials in the Thread panel, in the information pop-up of the Thread network which the OpenThread border router is part of.