Exposing Home Assistant Entities as Matter Devices

Short Intro

If you’ve been following Matter development, you are familiar with the communication protocols it supports: Wi-Fi, Ethernet, Thread and Bluetooth, primarily used for pairing and onboarding. While Wi-Fi and Ethernet devices will work with your Matter server by simply adding them to your local network, you need a Thread Border Router (like the SLZB-06M) to form a Thread network.

Since Zigbee is not part of the Matter specification and it’s basically succeeded by Thread, your Zigbee devices cannot be paired to a Matter controller directly. Which makes things really confusing when you come across a Zigbee device that says it supports Matter (Aqara being one example).

What this essentially means is that you need to pair your Zigbee device with the company hub and expose it as a Matter device through their app/platform. I recently did this with the SwitchBot Lock Pro and some Zigbee devices, and it works great. However, it does require you to use the company’s hub and proprietary app, which is something we, as Open Home enthusiasts, are trying to avoid at all costs.

In this article, I’m sharing a way to expose devices you have paired in Home Assistant as a Matter device. In other words, if it works with Home Assistant without proprietary hubs and bridges, it can be exposed as a Matter device and be used with other Matter controllers like Google Home, Apple Homekit or Amazon Alexa.

About Matter Bridge

This guide is based on Matter Bridge, a project that allows you to share all your Matter devices with other Matter controllers without re-pairing and sharing them invidiously. Matter Bridge is based on matter.js, the TypeScript/JavaScript implementation of the complete Matter protocol.

You can setup and deploy Matter Bridge as an LXC, docker container or simply install it in Windows. It’s functionality can be expanded by also installing one of the supported plugins. It comes with a web UI that’s very easy to use and navigate, allowing you to change settings and check the status of Matter Bridge.

In this guide, I’m deploying a Matter Bridge Add-on directly in Home Assistant, designed to effortlessly expose entities as Matter devices. This is by far the easiest way to achieve this, but it does require Home Assistant OS installed and running.

Props to the awesome people who made this possible. Liligu | t0bst4r

Who is this for?

Ever since I installed it, I thought about uses cases of this Matter Bridge add-on. Even though it’s primarily an experimental tool, it does bring some practical benefits and enables certain use cases. These are best explained through examples.

Let’s say you have a Zigbee device that’s not going to get Matter support. It works with Home Assistant either through ZHA or Zigbee2MQTT, but it cannot be shared between Matter controllers. Even using the proprietary brand hub will not allow you to share it as a Matter device, as the company chose not to include your particular model in the Matter-supported devices.

Well, with the Matter Bridge addon you can expose it as Matter device in any ecosystem you want to. This process does not care which communication protocol this device uses, as Home Assistant acts as a bridge between your Zigbee device and other Matter controllers.

As another example, let’s say you do have a Zigbee device that can be bridged to Matter but it requires you use the company hub. The device already works with Home Assistant via Z2M or ZHA, but you want to share it via Matter to other controllers. So, deploying the Matterbridge add-on will allow to do just that and skip over the need to use the proprietary brand hub.

But perhaps the most interesting use case of all is the ability to bridge the gap to Matter for your DIY devices. For example, ESPHome devices can be exposes as Matter device through the addon and shared between controllers like Google Home, Apple HomeKit or Amazon Alexa.

There are probably other use cases I’m overlooking right now, but hopefully I’ve made my point across: Your Home Assistant devices/entities are converted to Matter devices with the Matterbridge add-on.

Installing the Matter Bridge HA Add-on

To install the Matter Bridge Add-on, you need to add the custom repository in Home Assistant first. Navigate to Settings > Add-ons > Add-on store > Three dots in corner > Repositories and add the following repo:

https://github.com/t0bst4r/matterbridge-home-assistant-addon

Refresh the page and you will see the Matter Bridge Add-on appear at the bottom. Install it and select the Configuration tab. Here you can tweak which entity domains or blobs you want exposed as Matter devices. If the field is left empty, everything will be included by default.

Go back to the Info tab and start the add-on, while also toggling the Start on boot and Watchdog handles. Press Start. I would advise not enabling the Auto update toggle as this is a Beta project and bugs are possible. As with all things Home Assistant, always check the changelog when there is a new release.

Accessing the Matter Bridge Web UI

The add-on can be accessed by using the Open Web UI button in Home Assistant or by typing in your Home Assistant IP address with port 8283 (e.g. 192.168.30:8283) in a web browser. For a beta project, Matterbridge has a very clean and user-friendly interface. You will notice the matterbridge-home-assistant plugin is already installed and running, this is done automatically with the add-on installation and setup.

If you click the three dots under the Add/remove plugin card, you will see there are already several plugins available: zigbee2mqtt, shelly, somfy-tahoma, eve, and some others. These can be used to bridge the gap to Matter for that particular software, but since this addon is a fork made to work for Home Assistant only, you won’t be able to install any of them. And there is no need to, as the add-on exposes everything you have paired to Home Assistant as a Matter device, including Zigbee2MQTT.

If you want to setup Matterbridge for Zigbee2MQTT only, you can deploy it as a docker container or an LXC and simply install the required plugin. The Matterbridge Github repo does a great job of explaining this process.

If you click the Devices tab in the top left corner, you will see a list of devices already added bridged as Matter devices. Remember, you can configure which devices/domains you want enabled as Matter devices in the Configuration tab of the addon.

Adding the Matter Bridge to Google Home

With the QR code Matterbridge generates, you can pair it to any smart ecosystem you want to, just like a standard Matter device. This includes Google Home, Apple HomeKit, Amazon Alexa and anything else that works as a Matter controller. Here’s how the pairing looks like with the Google Home App:

The pairing process remains the same, just like with any other Matter device. During the onboarding setup, you will get an Uncertified device warning that you need to agree to (Step 4). Once paired, Google Home will display every entity you’ve selected to be exposed as a Matter device, including Automations which are shown as lights.

Limitations and bugs

Since this is all very much still experimental, you may encounter some bugs and limitations of the Matter Bridge. Here’s a few things I’ve personally encountered and some I found reported by other users in the community forums:

• Alexa doesn’t pair when you have over 100 devices (Apple and Google do)
• Not all device and entity types are supported (Matter limitation)
• It’s possible some devices will be displayed as the incorrect device type in other third party Matter controllers
• If you encounter issues during initial pairing, the first QR code Matter Bridge generated will not work again. You can navigate to Settings and click Reset Matterbridge Commissioning to generate a new one.
• Matter specs 1.3 is still not merged in the Matter Bridge Add-on Merged 17.06.2024
• Supported entity types
  • Light entities (light.) including on-off, brightness and hue & saturation control
  • Switch entities (switch.) including on-off control
  • Input-Boolean entities (input_boolean.) including on-off control
  • Media Players (media_player.) are mapped to Switches and currently only support on-off control
  • Climate Devices (climate.) currently work in progress, not released yet.
  • Scenes (scene.) are mapped to Switches and currently only support on-off control
  • Scripts (script.) are mapped to Switches and currently only support on-off control
  • Automations (automation.) are mapped to Switches and currently only support on-off control