Adding Matter Support to my Home Assistant Installation

Matter is a new protocol that should finally unify the smart home. I recently bought some Matter-compatible smart plugs and wanted to integrate them in Home Assistant natively.

Yes, I did make this graphic in Microsoft Paint.

What's the Matter?

Matter is a local protocol for controlling smart home products - lights, plugs, locks. It can run using WiFi or a specialty protocol for Matter called Thread.

Home Assistant

I'm a huge Home Assistant fan - it was one of the first things I installed on my server. It's great at bringing disparate ecosystems together into one usable dashboard. It's also just really fun to tinker with.

I run my install in a Docker container (surprise!). That has introduced additional complications in the past - the recommended home assistant install is either bare metal on something like a Raspberry Pi or buying something like a Home Assistant Green to run Home Assistant OS.

Matter Server

I used the documentation from the python-matter-server package's GitHub to install in a Docker container. This process was relatively simple:

services:
  # python-matter-server
  matter-server:
    image: ghcr.io/matter-js/python-matter-server:stable
    container_name: matter-server
    restart: unless-stopped
    # Required for mDNS to work correctly
    network_mode: host
    security_opt:
      # Needed for Bluetooth via dbus
      - apparmor:unconfined
    volumes:
      - /home/user/docker/matter-server/data:/data/
      # Required for Bluetooth via D-Bus
      - /run/dbus:/run/dbus:ro

Right after starting the server, Home Assistant discovered Matter as an available integration:

I left the WebSocket configuration as the default:

I received this message to show Matter was successfully set up in Home Assistant. Easy peasy - just following some simple docs.

Pairing My Smart Switch

Now it was time to pair these new smart switches to Home Assistant using Matter.

I went within the Home Assistant app in my phone, and navigated to this new Matter section:

I tapped Add Device. It asked if this device was already in use or if it was new:

I selected new. There was a QR code on a sticker on the side of the smart outlet - I scanned that:

It attempted to check my network:

Bonus points if you can recognize the game my WiFi network is referencing. Leave a comment on this post … oh wait…

I got the follow error - the Matter setup wizard couldn’t find my device.

I tried again, and it continued to error out with a generic “Something went wrong” message:

Home Assistant reported error code 1 when adding the device. Obnoxious.

I tried restarting my Home Assistant install, and my matter server container. I even tried temporarily disabling the 5 GHz band on my WiFi after I read that matter devices prefer to connect over just 2.4 GHz.

I already had the TP-Link Kasa app installed to control some of my other smart bulbs and switches. I was hoping to avoid the Kasa app and completely use just Matter, but with the luck I had so far, it seemed like a necessity. The native app detected and paired the switches instantly - no futzing around with WiFi settings. Kasa immediately prompted for a switch firmware update.

Finally, after a firmware update, a factory reset, and trying to pair again in Home Assistant, I finally added the switch to Home Assistant using Matter.

Disappointment

This was a very frustrating experience. A fresh out-of-the-box smart switch with a Matter compatible sticker ideally should pair, no problem. Once in Home Assistant, I was also disappointed with my options to control the switch.

I simply had the opportunity to turn the plug on and off, with only one sensor that detects if the firmware is up to date.

This is that same switch using the native TP-Link integration:

So many more options! Energy management sensors, timers, options to turn off the indicator LED, WiFi signal strength - all things that the switch supports in the native app but absent from the Matter integration.

In theory, Matter 1.3 supports energy management features. I bought these specific smart plugs because I saw they had energy readouts in addition to Matter support - I just didn’t read reviews or specs to verify that the energy management features were Matter energy management features. Confused yet? Clearly, so was I.

Matter fully supports controlling the same device in two places - I have the switch paired via Matter and the Kasa app. I'm able to keep it paired directly to HASS while still using the fuller feature set of the local Kasa integration. It's just frustrating that Matter support feels like an afterthought.

Matter, in theory, is something I've very excited about. It's a good thing to strive for consistency across vendors and have one protocol that Amazon, Google Home, Apple all support natively. However, Matter is moving at a glacial pace. It seems like every year there’s an announcement with a few new supported device types in the standard, then there’s a wait for smart home gadget makers to manufacture devices compatible with the standard.

Hope

For the vast majority of people, a smart outlet just needs to be able to be turned on or off in Google Home. Matter meets those needs, assuming the firmware hiccups are ironed out. Home Assistant is great for tinkerers like me, but I'm not your average consumer.

There are some very cool things coming down the pike for Matter. IKEA just announced a whole slew of affordable Matter-compatible smart home products. The 1.5 version of the spec is supposed to finally support cameras. Plus, as Matter becomes the expectation as the primary smart-home standard, the growing pains should subside.

One last note for my one reader - Hi mom! - I'm going to try to write a blog post a week until the end of 2025. It's been a while since I've done this type of writing for fun on a consistent basis, and I think it will help me keep my creative writing skills honed. Expect something shortly about the process of implementing a comment system for this blog.