Home Assistant, Matter over Wifi, and isolated VLANs

I wanted to have a setup where I could have my matter-over-wifi devices connected to Home Assistant, while also having them isolated into their own VLAN, along with the matter server — and nothing else. This turned out to be more complicated than I expected.

In case anyone out there finds it useful, here’s how I made it work.

You’ll need the following:

• matter-server installed somewhere HA can talk to it
• The string contained in the QR code of the device
• A python script to decode this string
• An installation of chip-tool on a machine with bluetooth
• Some way of talking to matter-server with a websocket tool – I used websocat

For troubleshooting, it will be handy to be able to run a packet capture on the matter VLAN, probably on the kubernetes node where matter-server is running.

Matter server

You need run run your matter server somewhere HA can talk to it, and it needs to be able to communicate with the matter-over-wifi devices.

In my setup, that is done by having matter-server in its own kubernetes namespace, with a service exposing port 5580 to the rest of the cluster (so HA can access it), and using multus to give the pod a second interface directly connected to the VLAN the matter devices are assigned to. I also use networkPolicy to make sure that the only thing talking to the matter server namespace is HA.

The arguments I’m supplying to the matter server process are the following:

"--storage-path", "/data", "--paa-root-cert-dir", "/data/credentials", "--log-level", "debug", "--primary-interface", "net1"

The --primary-interface argument is described as the “Primary network interface for link-local addresses (optional).” and net1 is the multus interface for talking to the matter devices.

Decoding the QR data

The data in the QR code should be something of the form MT:Yxxxxxxxxxxxxxxxxxx and it includes the information needed for both phases of the commissioning process.

The script you need to decode this is buried in the git repo at https://github.com/project-chip/connectedhomeip — you can check out the whole thing, or you can just extract the SetupPayload.py and Base38.py files under src/setup_payload/python

Once you have the script (and have built a venv or installed enough packages for all of the things it uses) you can run it as follows:

python3 SetupPayload.py parse MT:Yxxxxxxxxxxxxxxxxxx

Which should produce output something like:

Parsing payload: MT:Yxxxxxxxxxxxxxxxxxx
Flow                     :0
Pincode                  :nnnnnnnn
Short Discriminator      :x
Long Discriminator       :yyy
...

The important bits here are the Pincode and Long Discriminator fields.

Joining the matter device to your wifi network

For this, you need a machine with the bluetooth stack and chip-tool installed. I am assuming you already have your network configured in such a way that when the device joins the wireless network, it will end up connected to the isolated matter VLAN.

You will want to get a copy of the production PAA certificates used to verify matter devices. They can be found in the same github repo as above, under credentials/production/paa-root-certs

Once you have them, you need to put them where chip-tool can get at them. If you are using the snap installation, this can be a real problem since it doesn’t have access to most of the filesystem. In the end, I had to copy them into /tmp/snap-private-tmp/snap.chip-tool/tmp/paa (which then allowed them to appear at /tmp/paa to the command). If you are not using the snap installation you can probably put them anywhere you want, adjust the following command appropriately.

Run the following command:

chip-tool pairing ble-wifi 0x0001 <ssid> <password> <pincode> <long_discriminator> --paa-trust-store-path /tmp/paa

where ssid and password are the credentials for your wifi network, and pincode and long_discriminator are from the decoded QR code. The 0x0001 is just an arbitrary ID number you are assigning to the device.

Note that this command will ultimately fail, because you won’t have a connection to the matter VLAN and thus it won’t see the mDNS traffic it expects. However, it should have already succeeded in passing the wifi credentials to the matter device, which is all we need it to do.

Persuade matter-server to commission the device

At this point, we should have both the matter device and the matter-server able to talk to each other in the matter VLAN. We now need to prod the server into commissioning the device, by connecting to the websocket and injecting some json.

In my scenario, that involves running up a websocat container in the same kubernetes namespace as the Home Assistant pod (If you aren’t using network policy you probably don’t need to worry about namespaces or labels):

kubectl run [-n <ha-namespace>] websocat --image=ghcr.io/vi/websocat:nightly [--labels='foo=bar'] -it --rm -- ws://<matter-service-name>.<matter-namespace>.svc.cluster.local:5580/ws

Where ha-namespace is the kubernetes namespace your HA pod is in, the labels are anything you need to satisfy your network policy ingress rules, and matter-service-name and matter-namespace are the name of the service and the namespace associated with your matter-server pod.

Once that has started (you may or may not see anything in the terminal, but you should see a connection in the debug log of matter-server), you should paste in a single line containing the following:

{ "message_id": "1", "command": "commission_with_code", "args": { "code": "MT:Yxxxxxxxxxxxxxxxxxx", "network_only": true } }

where the code is the original data from the QR code.

At this point, you may end up with a message of the form

  { "message_id": "1",   "error_code": 1,   "details": "Commission with code failed for node 5." }

in which case, wait a minute or so and try pasting the command in again. This generally means that your matter device wasn’t responding, or didn’t respond in the correct way. It seems to sometimes take several minutes for a matter device to become ready after it joins the wifi network, and I’ve had at least one case where I had to reset it to factory defaults and re-do the chip-tool phase before it would work.

If it does work, you will get a rather large blob of json which starts something like this:

{ "message_id": "1", "result": { "node_id": 12, "date_commissioned": "2025-09-30T08:25:13.952835"....

and then you should be able to see your device under the integration in Home Assistant.

If it doesn’t work after 10 minutes or so I would suggest attaching tcpdump to the matter VLAN and see if you are getting any traffic – you would expect DHCP requests (which in my setup at least won’t be getting answered, but that is OK) and mDNS traffic on port 5353. If you don’t see traffic, maybe your matter device hasn’t actually joined your wifi.

Good luck.

Most of the info which actually got this working from me comes from https://community.home-assistant.io/t/commissioning-matter-devices-with-the-matter-server-without-smartphone-and-or-matter-add-on/905051/1, https://project-chip.github.io/connectedhomeip-doc/development_controllers/chip-tool/chip_tool_guide.html, and https://github.com/matter-js/python-matter-server/blob/main/docs/websockets_api.md