Blog

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

Recently I bought a CoolerMaster “HAF Stacker 915R” case for a new mini-ITX server I’m building, based around the ASRock AM1H-ITX board. I bought mostly because it was cheap, but also because it claimed you could mount a lot of fans (6x 120mm or 4x 140mm) on the side panels. What I didn’t realize until I was installing drives in it was that you can’t have the side panel fans and the drive cage installed at the same time:

As delivered, the case has the drive bay mounted at the front cooled by a 92mm fan in the front panel – but that didn’t work for me, partly because the fan cable for the front fan doesn’t reach back as far as the motherboard! In addition, the motherboard I am using has the option of being driven by a 19V external DC power supply, at which point it supplies power to the drives from a SATA power socket on the board – and that cable couldn’t reach the drive bays either.

So I decided that instead of mounting the drives across the case, I’d rotate the bay 90% and run them front-to-back. 4 small holes later..

Now there is room for the fan at the side:

You can still get the drives in and out of the bays without having to remove it from the case:

There’s plenty of clearance for the fan:

There is only just clearance between the front edge of the motherboard and the rear of the drive. Note that because I’m using the DC input on this board, I don’t need to use the ATX power connector, so potentially fouling that isn’t an issue for this build.

I’m now much more confident that the drives will get the cooling they need.

Rasbian on the Raspberry Pi is great, but the official image is large and includes all sorts of stuff I don’t need (my Pis don’t generally have screens as I use them for playing music, or being GPS NTP time servers, or collecting data on my power usage – not things which need, for example, a screen and a gui!). I did manage to cobble together a base install using the Debian installer on a Pi, but it took a loooong time, and cloning this image every time I want to do a new one is a bit of a pain; for one thing the image is quite old now so apt-get has to update a lot of packages to bring it up to current, and for another the machines all get the same ssh keys, and the filesystems all have the same ‘unique’ IDs (which tends to confuse things if you simultaneously plug 2 of the resulting SD cards into the same PC!).

So I’ve been mucking around with a better way to generate basic Rasbian installs for the Pi. I’ve discovered that the combination of multistrap and qemu-static allows the building of a complete up-to-date installation tree on my x86-64 Ubuntu desktop in a tiny fraction of the time it would take to do the same thing on a Pi. For my base install (which is indeed very basic) my machine takes about 5 minutes (with the packages files already in my apt-cacher-ng cache). Sometimes the longest step is copying all the data to the SD card!

One of the nice things about using multistrap to do this is the ability to make cascaded configurations – so I can define a base configuration which works for me, and then have other configurations which build on top of it for specific applications. If I make improvements to the base, then regenerating one of the cascaded configurations will incorporate the improvements automatically. It also means I don’t have to remember or document what I did to the base image to get the application-specific image, because it is all there in the configuration file and associated scripts.

The resulting trees are still proper Rasbian installs and can be updated and managed with apt-get etc just like a normal install.

I’ve put a small collection of multistrap configuration bits and attached shell scripts up on github if anyone else wants to have a play with it. It includes one configuration file for a base install, and one for a customized install including MPD. There’s a handful of shell scripts which do most of the work beyond getting the packages extracted – these will almost certainly need customizing for your environment. You will definitely want to read the README. Oh, and you’ll need a Debian-derived (eg Ubuntu) machine to do the work, since multistrap relies on apt to do all the package work.

There’s a rather nice article about timezones and how wrong they can be, which shows clearly just how broken the South Australian timezone (+9:30) is. If you look at the beautiful map, you’ll notice that all of South Australia (and Northern Territory if it comes to that) is in red; that is, behind the timezone. At 15° of longitude per hour (360° in 24 hours), the +9:30 timezone would be centred at 142.5° E. South Australia extends from 129° E to 141° E (see wikipedia).

If you look closely at the map, you’ll see part of Indonesia (West Papua) which is on the +9:00 timezone. You can see that the white coloured section (the centre of the timezone, 135° E) is roughly in line with the centre of South Australia. Surely this would make more sense? All that broken software which assumes that timezone offsets from GMT are always a whole number of hours would just work!!

(I recently came across broken software which did in fact have non-integer timezones available. Well, sort of. They had a special case for India on +5:30, but that was all. ARRGGHH!).

Got my 2nd raspberry pi today. Coinciding with the discovery that pin 10 on the arduino board I was going to use to submit data from the currentcost cc128 meter to mqtt seems to have a duff pin 10 (which makes it rather hard to use the ethernet shield), I decided to see if I could instead have the 3.3v RS232 from the cc128 drive the 3.3v RS232 on the raspberry pi (through 2 gates of a CD4049 running from the rPi 3.3V rail to protect the rPi if something went wrong). After finding an old floppy cable to rip apart and bodging together a LEGO case (based on the design by Biz but hacked because of the  over-sized connector I’ve used for the i/o port), it was a matter of “apt-get install mosquitto-clients python-serial”, copy the script over from the server currently doing the job (which has a long unreliable USB cable to the cc128), hack it to send the data to the server rather than localhost, and voila! works first time.

Disturbingly this actually costs less than an arduino + ethernet shield. The form factor is a little more awkward though (ports at both ends of the board, no screw holes), so getting it into a case along with other bits and pieces will be somewhat more awkward; ideally it would be good to have a tall case with enough room in the upper part to hold a pcb for additional components.