This is not a tutorial

This is more like a series of notes on how my setup works, partly just so I remember, but if you’re here to find out how to enrol matter devices with GrapheneOS I’ll describe it quickly for you.

• You need a third-party Matter+Thread hub, such as the Aqara Hub M100.
• Enroll the hub to the Aqara app, then generate a third-party Matter Sharing Code.
• Open Home Assistant and add a new Matter Device, but this time choose “Yes, It’s already in use.”. Enter the code from the previous step.
• Then, continue to use the Aqara app to enrol your Alpstuga’s.
• For each one, generate third-party Matter sharing codes and use them to add the devices to Home Assistant.

If successful, the Alpstuga should be communicating through the hub straight to Home Assistant. Apart from relying on the Aqara hub, and its account requirements for enrolment, no internet connectivity is required moving forward.

Opensource Appreciation Disclaimer

I discuss some shortfalls with support and feature sets of various opensource projects in this post.

I appreciate every ounce of effort the developers pour into these projects, I know supporting users is difficult, and feature requests need to be balanced against resources, and you’re mostly working for free, and I love you for it.

Once a project becomes popular enough, like Home Assistant and GrapheneOS have, some users (especially ones not used to interacting with OpenSource software) have a tendency to become arrogant, demanding and selfish, they have no respect or appreciation of the situation, and they might not even realise what they’re using is built by volunteers. Supporting these people is overwhelming, and exhausting.

So, I wish you all the best and thank you for what you’ve built, and any help you provide people <3 <3 <3.

My setup

• I have a custom-built NAS server running TrueNAS Community edition.
• Home Assistant is running on my NAS server as a Docker Container, I’m not using the official Home Assistant operating system that so many of their tutorials want you to.
• My router is a BPI-R4 running OpenWRT. I’m not very good with OpenWRT and many aspects of networking are a mystery to me, such as IPv6. I’m in over my head with this one, but that’s what learning is all about.
• I have a Pixel 9 running GrapheneOS with Google Play Services installed.
• I have the Home Assistant Python Matter Server installed separately from my NAS in a RaspberryPi, for reasons discussed below.

The Home Assistant Python Matter Server

In order to use Matter Devices with Home Assistant (HA), you need to have their Matter Server installed on your network and connected to HA. If you use their official operating system, and even better, the official hardware, then you can install it as an add-on automatically. If you don’t use their OS (like me), then you can set it up yourself, or use the docker container they provide, which I will cover later. They’re very hostile about supporting this docker container, specifying many times that it’s provided without any support. Not that I don’t understand their grievances with such a popular opensource project. I don’t want to ask them how to make it work for me, but I do need their help to decipher what their own errors mean. For example, when trying it out it would crash immediately with the message “Address already in use”, which I assumed to be the port was already in use, but it turns out this wasn’t the port for the matter service itself, but the mDNS service that I didn’t know it includes, being able to ask questions for things like this would be super useful. Despite these claims, when I did need help, I found some threads on their discord of people with similar questions and the devs helping them out, so don’t get too discouraged. This particular project is being re-written to be more stable and easier to use, the current available version is in maintenance mode; so I hope this will get easier in the future anyway.

I was not able to get the Matter Server to work while installed inside a TrueNAS app, I tried various troubleshooting changes involving IPv6 and forwarding, and disabling mDNS, even so it continued to report errors and enrolment failed. The only way I got it working was to install it on a RaspberryPi. If you’d like to try further, I used the following TrueNAS App specification:

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:
      - bind:
          create_host_path: False
          propagation: rprivate
        read_only: False
        source: <you need to enter a path to some persistant storage here, probably mounting a share inside the container.>
        target: /data
        type: bind
      # Create an .env file that sets the USERDIR environment variable.
      #- ${USERDIR:-$HOME}/docker/matter-server/data:/data/
      # Required for Bluetooth via D-Bus
      - /run/dbus:/run/dbus:ro
    environment:
      GID: '568'
      GROUP_ID: '568'
      NVIDIA_VISIBLE_DEVICES: void
      PGID: '568'
      PUID: '568'
      TZ: Europe/London
      UID: '568'
      UMASK: '002'
      UMASK_SET: '002'
      USER_ID: '568'
    group_add:
      - 568      
    # If you adjust command line, make sure to pass the default CMD arguments too:
    #command: --storage-path /data --paa-root-cert-dir /data/credentials --bluetooth-adapter 0

As for the setup on the Raspberry Pi, I’m hosting it in Docker Compose, and used basically the same config as above. It worked perfectly the first time with no troubleshooting.

IPv6

Matter relies on IPv6 to work, I needed to enable it on my home network and ensure my Matter Server had an IPv6 address. Normally, OpenWRT will have this setup by default, in my case it did not, I don’t know why, probably I deleted the interface for some reason. I think you technically don’t need your ISP to support IPv6 and just need local addresses to be issued. Either way, ensure IPv6 is enabled on your router.

Complications with GrapheneOS and HA’s reliance on Google Play Services

Matter is an open protocol, but HA’s implementation of it uses Android’s native Matter “flow”, which makes use of Google’s proprietary Google Play Services. In order to enrol a matter device directly with the Home Assistant app, you need to have installed it from the Google Play Store (not FDroid), and you need to have a Non-GrapheneOS Phone. The FDroid version does not include the Google Play Store dependencies and therefore cannot enrol Matter devices, it will frustratingly just tell you to install the Companion App and link to the Play Store.
In order to work around these limitations, the HA team would need to write their own Matter Enrolment flow, or I guess wait for someone else to create a FOSS library or something. No idea how difficult any of this would be, but that’s the reason for the situation we’re in. I think it’s really disappointing that we’re so close to having a fully open offline smart home protocol, but ’little’ issues like this break up the process.
Further to this problem, GrapheneOS cannot enrol Matter devices because its implementation of the Google Play Services is deliberately achieved as a non-privileged service. Part of the Matter flow involves accessing your Wi-Fi Credentials and passing them to the device, this process requires privileged access, no workaround has been implemented by the GrapheneOS developers, and they have no plans to. But don’t worry, I found a viable workaround discussed below.

Aqara, Matter, and Thread.

Without getting too technical, the ALPSTUGA supports Matter but not Wi-Fi. It uses Thread for connectivity with a Matter Hub. Thread is like a different method of wirelessly connecting devices, very similar to Wi-Fi. This means, in order to connect the Alpstuga to HomeAssistant, your HA server either needs to support Thread natively (which is rare, but I understand there’s some official hardware that does), or you need any Matter/Thread Hub. The one I use was the cheapest one I could find, the Aqara Hub M100.

Aqara are just a Smart Device manufacturer. The Hub 100 is very cheap (£30) and crucially uses the Aqara app which can enrol matter devices without the native Android Matter flow, so it works on GrapheneOS. Unfortunately, the app is proprietary and requires you to sign-up and login for an account, so we’re deviating significantly from FOSS and offline smart home stuff. That said, once set up the devices should not need to connect to the internet, though I haven’t tried isolating them yet. Matter is all about local connectivity. You can use other Matter hubs, but presumably if they make use of the Android Matter flow then they will not help you work around the GrapheneOS limitation.

Alpstuga Compatibility with Home Assistant

Either due to the Matter standard, or simply the brilliance of Home Assistant, the Alpstuga works flawlessly. I can see full technical details, and it polls every few seconds. Including Temperature, Humidity percentage, CO2 ppm, and air quality. I put these in some charts and I can see a great readout of the values throughout the day.

Final thoughts

• Home Assistant’s reliance on Google’s proprietary Matter flow for enrolment is disappointing but understandable.
• GrapheneOS’ stance towards Matter Support is disappointing but understandable.
• Home Assistant’s approach to supporting their Matter Service on anything but their Operating System is disappointing, but understandable.
• TrueNAS has a really weird networking setup that’s poorly documented, doesn’t seem to be any of the standard Linux setups like networkd or NetworkManager that I could find.
• The fact that I was unable to get the Matter Server running inside TrueNAS is really annoying, I don’t like having additional bits of random hardware for individual services in my home; it’s an unnecessary waste of hardware, this is the same reason I don’t use the Home Assistant OS or their official hardware. (but at least I finally found a use for my RPi4 impulse buy tehe).
• In general, I really like the idea of Matter and once I got the entire setup working, enrolling and using the devices is really reliable and easy.
• The ALPSTUGA itself is a great budget air sensor, and I’m enjoying using it.

So extensive is this problem that Microsoft once had a documentation page dedicated entirely to listing and describing Microsoft Rights Management’s many names. Sadly, it’s now removed, further muddying our dry, mouldy bread, I suppose they were embarrassed, luckily you can still find it on archive.org.
Even in this snapshot, there’s a ! Note pop-up desperately clarifying that this is different to “Microsoft Purview Information Protection”, though if you closely examined the feature set you might start to wonder if that slice is from the same loaf.

Anyway, here’s every single name this product has had since its inception:

• Azure Information Protection
• Azure Rights Management
• Azure Rights Management service
• Azure RMS
• Microsoft Entra Rights Management
• AADRM
• Windows Azure Active Directory Rights Management (This one’s my favourite)
• Windows Azure AD Rights Management
• Active Directory Rights Management Services
• AD RMS
• Windows Rights Management Services
• Windows RMS
• Microsoft Rights Management
• Microsoft Rights Management services
• The NEW Microsoft RMS (Second favourite)
• Information Rights Management
• IRM
• Rights Management Online
• RMS Online

Even now, this product’s name is evolving, the old link directs to Azure Rights Management encryption service, is that the same thing? Is this just a subset? Oh but this product is also a part of Purview, so shouldn’t it be called Purview Rights Management Encryption Service?
These questions will not be answered by me or Microsoft, today or tomorrow, good luck.