How to configure an open source Matter bridge at Home

If you are an Apple HomeKit user, you must have heard of the open-source project Homebridge, which is software that can bridge supported third-party devices to Apple Home locally. As Matter grows, an alternative based on Matter.js is available and well-maintained on GitHub.

This week’s project is to guide you through installing Luligu/Matterbridge on Docker and configuring Zigbee2MQTT and Shelly devices to the major Matter platforms via the Matter bridge.

Before you start, you will need:

• Internet access
• Docker on an always-powered device
• Home Assistant (Optional)

Install Docker

Docker provides a simple way to virtualize and manage software environments and is a part of Home Assistant Supervised and Home Assistant Operating System. If you already have Docker installed on a Linux environment, feel free to skip this section.

1. Open Terminal and enter the following command:

curl -sSL https://get.docker.com/ | sh

Enter your password if prompted for administration permissions.

2. Test the installation by running the Hello World image:

sudo docker run hello-world

This command should display a confirmation message indicating that Docker is installed correctly. You can find more instructions on installing Docker on their official documents.

Install Luligu/Matterbridge

Let's install Matterbridge now.

For Linux:

Run the following command in the terminal. Remember to replace <USER> with your system username. You can use ls /home to find your username.

sudo docker run --name matterbridge \
  -v /home/<USER>/Matterbridge:/root/Matterbridge \
  -v /home/<USER>/.matterbridge:/root/.matterbridge \
  --network host --restart always -d luligu/matterbridge:latest

Wait until it's started, then visit the following URLs in your browser:

• http://localhost:8283
• http://IP-Address:8283

For Home Assistant:

1. Access your dashboard:
   • Navigate to Settings > Add-ons > Add-on Store.
2. Add Matterbridge repository:
   • Click on the three-dot menu button in the top right corner.
   • Select Repositories.
   • Enter the following URL:
     https://github.com/Luligu/matterbridge-home-assistant-addon
   • Click Add.
3. Install Matterbridge add-on:
   • Refresh the page.
   • Scroll down to find the Matterbridge add-on in your store.
   • 
   • Select it and click Install (or Build).
   • 
   • Home Assistant will download and build the image. Wait until the button changes from Install to Start.
4. Start the add-on:
   • Once fully started, click Open WebUI.
   • For quick access, toggle on Show in sidebar.
   • You can enable Start on boot and Watchdog options later to ensure it runs continuously.

Configuration

The main user interface is straightforward:

• Top left: The Matter onboarding code. You can use any Matter-enabled platform to add it first, but it's recommended to do this later.
• Below the QR code: Basic information about your Matterbridge instance.
• Right grid: Contains the plugins or integrations you installed and live logs.

Installing plugins: Zigbee2MQTT and Shelly

1. Access plugins:
   • Click on the three-dot button next to the text box.
   • A list of available plugins will appear.
   • 

Zigbee2MQTT

1. Install the plugin:
   • Select Zigbee2MQTT from the list.
   • Click Install.
   • Wait until you see a green prompt indicating success.
   • Click the Restart button in the top right to complete the installation.
2. Configure MQTT server:
   • For Home Assistant users:
     • Navigate to Settings > Add-ons > Mosquitto broker > Configuration.
     • Under the Login field, add:

       - username: matterbridge
         password: SetYourPassword

     • Ensure the format matches exactly – no extra or missing spaces.
     • Click Save and allow the MQTT server to restart if prompted.
3. Configure the Zigbee2MQTT plugin:
   • Return to Matterbridge's WebUI.
   • Locate the Zigbee2MQTT plugin on the main interface.
   • Click the gear icon to configure it.
   • 
   • Enter the MQTT account information you set earlier.
     • Host: Use the IP address if Matterbridge and the MQTT server are on different devices or localhost if they share one.
   • Whitelist devices:
     • Click the plus button under the Whitelist section.
     • Select the devices you want to include.
     • 
   • Click Confirm.
   • Restart Matterbridge by clicking the Restart button in the top right.
4. Finalize setup:
   • Once reloaded, use your Matter-enabled app to scan the QR code and add the devices.

Shelly

1. Install the plugin:
   • From the Matterbridge main interface, find the Plugins section.
   • Select Shelly from the plugins list by clicking the three-dot button next to the text box.
   • Click Install.
   • Wait for the green prompt indicating successful installation.
   • Click Restart in the top right to finish the installation.
2. Configure the Shelly plugin:
   • Locate the newly installed Shelly plugin.
   • Click the gear icon next to it to configure.
   • 
   • For newer Shelly devices:
     • Add them to the whitelist as they are discovered locally.
   • For older Shelly devices:
     • Enter your Shelly account information to retrieve them.
   • Click Confirm after selecting devices.
   • Restart Matterbridge by clicking the Restart button in the top right.

Add the Matterbridge to Matter platforms

1. Add to Matter platforms:
   • Use your phone or smart home app to scan the Matter onboarding QR code.
   • If you receive a warning about uncertification, proceed anyway.
   • Once added, you should see a bridge or gateway device with all child devices attached to it.
2. Share with other platforms:
   • Enable pair mode from a previously added platform to share the bridge with other platforms.
3. Troubleshooting for Home Assistant users:
   • If you're having trouble adding the device or it's stuck at connecting: 
     • Go to Home Assistant Settings > System > Network.
     • Find the network adapter Home Assistant is using (e.g., end0) and copy its name.
     • 
     • Access Matterbridge WebUI, navigate to Settings, and paste the network adapter name into the mDNS Interface field.
     • Restart Matterbridge.
   • Final steps:
     • Set the add-on to auto boot on start.
     • Enable Watchdog to ensure it restarts if it crashes.

Here's a look at it on Home Assistant. You can see that it is exposed as a bridge device, with multiple deivces I added from Zigbee2MQTT and Shelly. Usually devices like switches from Aqara would also contain temperature sensors -- such entities would also be ported to Matter via the Matterbridge. You can also set power-on states on Home Assistant like other Matter devices.

On SmartThings, some devices may miss control, but energy monitor features works on the platform like my Tuya Zigbee plug. Feel free to try out other plug-ins and all the configuration they provide, like switch or light device type maping options.

(Source: Luligu/matterbridge)