Be Smart, Go Local.

Exposing Home Assistant Entities as Matter Devices

Guide for exposing all supported Home Assistant entities as Matter devices, allowing you to pair them to other ecosystems via the Matter Bridge Addon.

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.

Exposing Home Assistant Devices as Matter Devices: Featured Image

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.

Matter Bridge Github Repo

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.

Exposing Home Assistant Devices as Matter Devices: Matterbridge addon start

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.

Exposing Home Assistant Devices as Matter Devices: Matterbridge addon web interface
Matterbridge web interface

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.

Exposing Home Assistant Devices as Matter Devices: Matterbridge addon devices list
Matterbridge device list

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
    • Automations (automation.) are mapped to Switches and currently only support on-off control
    • Binary Sensor entities (binary_sensor.) provide their state (e.g. on / off)
    • Cover Devices (cover.) are currently all mapped to “Window Covering”
    • Fan Devices (fan.) are currently mapped to Dimmable Plugin Units, because most of the Matter controllers do not support fans.
    • Input-Boolean entities (input_boolean.) including on-off control
    • Light entities (light.) including on-off, brightness and hue & saturation control
    • Lock Devices (lock.) including Locking and Unlocking. Some Matter controllers (like Alexa) do not allow unlocking locks by default. It needs to be enabled in the Alexa App for each Lock.
    • Media Players (media_player.) are mapped to Switches and currently only support on-off control
    • 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
    • Switch entities (switch.) including on-off control

31 thoughts on “Exposing Home Assistant Entities as Matter Devices”

      • as of me writing this, although matterbridge itself is updated to 1.3, the HA addon implementation is not updated to 1.3.

        Also I hope you can add an explanation to the article on a topic that may not be clear to me and probably many others:

        Does this allow us to add HA devices and entities to Google Home without exposing HA to the internet and without going through the annoying convoluted process of connecting to Google Home manually?

        • owner of the repo here 🙋‍♂️

          i’ve just merged v1.3 to the main project (https://github.com/t0bst4r/matterbridge-home-assistant).
          i’ll release this to the HA addon in the next one or two days.

          and yes, entities from Home Assistant are published as matter devices by one bridge. You can pair it with Alexa or Google Home. Since Matter is a fully local protocol, you don’t need any port forwarding. It even works when internet is down (if the voice assistant is still able to understand voice commands).

  1. This is such an interesting article. This could come in handy with the Flic twist and buttons. The controller they provide has limited devices it can natively control – perhaps using this method we can expose more devices to their proprietary controller via Matter and make their buttons / switches / dials more useful?

    Thank you for this article

  2. Very interesting, I have one question. I have one switch that only alexa can control. Is there a way to see that switch from google home and home assistant as well?

    Natively that switch can only be accessed through alexa, no way to pair it directly to google or home assistant, but I’m wondering if somehow a bridge between alexa and home assistant could solve my issue?

          • This is the same for Amazon Smart Plugs. In theory the custom component “alexa-media-player” is capable to control those devices from within home assistant. In practice this does not really work – devices are not even found.

          • Ok, I was wondering if I understood correctly, this matterbridge only gives control to home assistant entities from Alexa/Google. Not the other way, for example it can’t bind a zigbee button to trigger an action in Alexa…

    • As has been mentioned previously the matter bridge allows control of HA entities but not vice-versa.

      There is however a way to control Amazon-only devices using Alexa Media Player and emulated Hue (in theory the matter bridge could be used instead of emulated Hue). You basically create an input boolean to represent your device and expose it to Alexa using the emulated Hue. You then set up an automation to send custom commands to the Alexa using Alexa Media player when the input boolean is turned on or off. Finally you create an Alexa routine that’s triggered by the custom commands to control your Alexa-only device.

      Thus your input boolean represents your switch (or whatever it is) in both HA and Alexa and the real device (which shows only in Alexa) has its status “synced” to the input boolean using the automation described. I use this to control an Amazon-only smart plug from HA.

    • That’s a good idea, but at the moment only a limited amount of entity types are supported.
      At the moment i have added the feature to expose scripts or automations as “on-off-plugin-units”. With that you could create an automation which starts the vacuum, and the automation can be triggered by saying “turn [automation name] on”. Just make sure to include them in the config.

  3. If exposed as Matter devices, one could dispense with the Nabu Casa cloud integration with Google and Alexa, right?

    Other than not having the remote access when away from home, Alexa would/should still be able to controll all my stuff as it does now with Nabu Casa…

    • @Dave,

      Just an FYI:

      Alexa/Echo devices can still control your entities, even without a Nabu Casa subscription, and even without following this guide.

      You can look it up on YouTube, although, most creators are not as clear in their steps. Still, it’s feasible and I guarantee it works.

  4. Interesting, but I’m trying to figure out why would someone do this? are there any advantages on exposing each entity via matter to other controllers (eg Google Home) rather than just adding that entire Home Assistant as a Google Home service?

    • There are several advantages actually:

      1. Works completely locally over Matter
      2. Much easier setup process (one pairing code for all devices)
      3. Do not need to do it indivudlaly for Google Home, Alexa, Apple Home.
      4. Great for exposing unsupported devices e.g. DIY Devices

    • Hey,

      Thanks for showing up! Your work is awesome and much appreciated!
      Let me know when you merge Matter 1.3.
      Could we also get a list of all supported entity types?

      • Thanks for your feedback. Matter 1.3 was merged some days ago.

        You can find a list of supported entities in the main project’s readme:
        https://github.com/t0bst4r/matterbridge-home-assistant?tab=readme-ov-file#supported-entities

        Since i only have lights and switches at home to control with matter, i only have limited possibilities to actually test all the entity types. I am working with some virtual devices, but thats not covering all features and domains. Additionally new entity types need to be implemented one by one. Just because matter supports it (in theory), it doesn’t mean my project automatically knows what service to call in home assistant and vice versa.

        I am always dependent on the help of users. That’s why i need everyone to create issues (preferably in the main project) if additional entity types are needed. Including attributes and services from home assistant, and as much details about the device as possible.

  5. hello
    I have problem with connect to Google Home, in GH i add matter device and….. nothing after few minuts i have only msg that cant find matter device 🙁
    I tryed generate new QR code but still the same efect – cant conect to GH

    any ide?

  6. To @t0bst4r

    Thanks for creating such useful tool! I see that Covers (blinds/door/gate) aren’t supported currently. Is this something on your roadmap?

    Cheers

  7. I have a garge door opener device by konnected.io. It’s showing in matter bridge as MA-windowcovering and in Apple Home it’s “not responding” and does not work. 🙁
    It uses ESPHome in HA.

Comments are closed.