The supported user-facing Matter commissioning process, as of this writing, is entirely smartphone-based, and utilizes native smart device onboarding flows. In order to use these features, your device must be either decently modern iOS, or an Android phone with Google Play and a signed-in Google account.
Alternatively, if you don’t have a compatible device or don’t want Apple/Google to know your business, it is possible to go to the Matter add-on page within HAOS/HASS Supervised to commission a device through the server directly. This process is a bit more involved but is also pretty straightforward and easy to do in most setups, though it is not officially supported and is intended for developer use.
So what can you do if you don’t have a compatible smartphone, or the server can’t start the commissioning process due to issues communicating with the device? Or what if you are running the python-matter-server container yourself instead of under the Supervisor as an add-on, and as such don’t have the add-on interface to kick off a manual commission?
Prerequisite knowledge
Before we dive in, let’s first consider what Matter device commissioning even is. Make sure you read and understand this thread:
Of particular note is this image:
You should be very aware that getting a device to join a specific network essentially commissions the device, but to a temporary fabric. This is important since there are some steps below where the two commissioning steps are split between multiple devices.
Non-add-on server-only commissioning with Bluetooth to Matter over Thread
GitHub user @darrida wrote a script to communicate with the python-matter-server to commission Bluetooth devices into a Matter over Thread (MoT) fabric:
This sort of setup would be necessary if you don’t run the Matter add-on, and don’t have a Matter-compatible smartphone, since there is no other way to commission devices with Home Assistant.
I don’t particularly like the dependencies and complexity of the original script, so I shortened it. This version uses the official matter_server client instead of opening the WebSocket. As such, you need to either run this on the python-matter-server container, or install matter_server into a Python venv. I leave the former as an exercise for the reader/up to personal preference.
import asyncio
import aiohttp
import logging
import coloredlogs
from matter_server.client.client import MatterClient
if __name__ != "__main__":
exit()
async def main():
logging.basicConfig(level=logging.DEBUG)
coloredlogs.install(level=logging.DEBUG)
async with aiohttp.ClientSession() as session:
# NOTE: change to non-loopback IP if not running in container
async with MatterClient("http://127.0.0.1:5580/ws", session) as client:
# connect the client and wait for success
e = asyncio.Event()
asyncio.create_task(client.start_listening(e))
await e.wait()
# set Thread credentials to use for commissioning
await client.set_thread_dataset("<dataset-tlv-here>")
# use Bluetooth to search for a device, validate it, send credentials, and join it to the MoT fabric
await client.commission_with_code('MT:ABC123.ABC123ABC123')
Split commissioning with a Linux device
If your server can’t communicate over the initial protocol or network the Matter device uses (e.g. Bluetooth, different IP network or behind VLAN), you can use a third device to connect your Matter device to a network the server can see/use. This is normally the responsibility of the smartphone and its native Matter integration, but if that isn’t an option, you can use a Linux machine with BlueZ installed instead.
On the Linux machine, you will need to install a CLI tool to communicate with the Matter device. Matter used to be called CHIP, so the tool to interface with Matter devices is called chip-tool.
Before you start, consider opening the official documentation to have handy:
https://project-chip.github.io/connectedhomeip-doc/development_controllers/chip-tool/chip_tool_guide.html
For your reference, here is the source repo too:
The documentation offers tips on building/installing the tools, including an easy Snap-based option, so I will not cover getting everything set up here.
Docker alternative
If you have issues with the official installation methods, there is also a container that has the command built and ready:
https://hub.docker.com/r/atios/chip-toolYou will need to replace the
chip-toolcommand in the examples below with this:docker run --rm -it atios/chip-toolIf you need to use Bluetooth, make sure Docker can see your D-Bus socket by adding
-v /run/dbus:/run/dbus:roor similar to your argument list.
Preparing credentials (certificates)
As part of the Matter certification process, every device will have an attestation certificate generated for it (PAA) that will be validated during commissioning. You have two options here:
- Get the certificates and pass them to
chip-tool - Ignore verification entirely (not recommended)
If you have already started python-matter-server once, it should have downloaded the PAA certs already for you. Check the credentials directory where your Matter server saves its data. Where this directory is varies depending on your installation method, and may be user-configured, so finding it should be an exercise for the user.
Once you have the certificates, put them in a place where chip-tool can read them.
- For Docker, add
-v /path/to/your/credentials:/credentialsto your argument list. You will also need to add--paa-trust-store-path /credentialsto the end of anypairingcommands you run. - For other platforms, e.g. Snap and native binaries, give the full path to your credentials directory as the value to
--paa-trust-store-pathinstead.
If you don’t have the PAA certs, and your Matter device doesn’t use the default test certificates, you’ll need to ignore attestation. Do not do this. All certified Matter devices should be able to pass attestation. But if you must, you can bypass verification failures with --bypass-attestation-verifier true.
Getting a device’s discriminator and PIN
The discriminator-PIN pair is used to uniquely identify a Matter device. It is used in some of the below steps where a QR code payload or manual pairing code won’t work due to API constraints. In particular, the payloads are usually used for full-stack commissioning i.e. getting a device from an initial default state to fully joined to the Home Assistant fabric; discriminators and PINs are used for specific operations, such as commissioning a device by IP address.
You can use chip-tool to parse a Matter QR code or manual pairing code:
$ chip-tool payload-parse-setup-payload MT:ABC123.ABC123ABC123
Commission a Bluetooth device to a Wi-Fi network
This command will connect a device to a specific Wi-Fi network:
$ chip-tool pairing ble-wifi <any-number> <ssid> <password> <pin-code> <discriminator>
--paa-trust-store-pathat the end of the command, after all other arguments!
Refer to the official documentation for more information on command structure, supported options, and argument formats.
Once the device is connected to the network, wait a moment. I have found that generally it can take anywhere from a few seconds to a minute or two for the device to begin advertising over mDNS. Aside from the fact that it takes a moment for mDNS to propagate and for listeners to receive the broadcasts, it may take a moment for the device to give up waiting on your Linux box to send it messages on the new network, depending on the device, since technically it is still in the commissioning state. Or it may work straightaway.
Furthermore, if your Linux device is not on the destination network, chip-tool will report commissioning as failed, since it won’t be able to find the Matter device once it connects to Wi-Fi. However, even if this is the case, the Matter device should still be able to connect, and you can verify if it did by checking connections and/or DHCP reservations on the router. The device will, at this point, stop advertising itself as a CHIP device over Bluetooth, or turn off Bluetooth altogether—this is generally normal, since it should only be talking Matter over Wi-Fi now.
Afterwards, you can either use the matter_server client or the add-on interface to complete the final commission and get the device joined to the fabric. With the client, copy the script above but replace the client functions with this:
# set wifi creds
await client.set_wifi_credentials('<ssid>', '<password>')
# use Bluetooth to search for a device, validate it, send credentials, and join it to the HA fabric
# OPTION 1: use QR payload. this will attempt to search for the device using mDNS.
# the second argument forces network search instead of Bluetooth, even if the Matter device advertises support for it.
# you can also use Matter pairing code instead of QR payload here.
await client.commission_with_code('MT:ABC123.ABC123ABC123', True)
# OPTION 2: use direct IP address connection instead of full mDNS lookup.
# do this if you experience problems with the above, though mDNS will still be used for some operations.
await client.commission_on_network(20675194, '<ip-address>')
If it fails to connect, just wait a moment, and try again. I’ve had varying success getting devices added myself, just keep trying it until it works. That is, if you have already verified your network is functional.
Other matter_server client actions
If you want to do other actions that those covered in this guide, you can find documentation for the HASS Matter server API here:
The API commands will generally pair up with functions available in the client module here:
You can thus pick whatever client function you want, and use the above code as a boilerplate to inject your own functionality. This is much easier than doing a bare connection to the WebSocket.
Note that normally, these functions are run via the add-on interface, so if you’re running the Matter server addon, you probably shouldn’t actually need to connect like this. Just look for the right buttons in the web interface. There are plenty of threads here going over just that if you need help figuring out what to do.