Matterbridge is a matter.js plugin manager.
It allows you to have all your Matter devices up and running in a couple of minutes without having to deal with the pairing process of each single device.
The developer just focuses on the device development extending the provided classes.
Just pair Matterbridge once, and it will load all your registered plugins.
This project aims to allow the porting of homebridge plugins to matterbridge plugins without recoding everything.
It creates a device to pair in any ecosystem like Apple Home, Google Home, Amazon Alexa, or any other ecosystem supporting Matter like Home Assistant.
You don't need a hub or a dedicated new machine.
No complex setup just copa paste the installation scripts.
Matterbridge is light weight and run also on slow Linux machine with 512MB of memory.
It runs perfectly on Windows too.
The project is build on top of https://github.com/project-chip/matter.js.
A special thank to Apollon77 for his incredible work.
Follow these steps to install Matterbridge:
on Windows:
npm install -g matterbridge
on Linux (you need the necessary permissions):
sudo npm install -g matterbridge
Test the installation with:
matterbridge -bridge
Now it is possible to open the frontend at the link provided (default: http://localhost:3000)
matterbridge -bridge
Matterbridge only exposes itself, and you have to pair it scanning the QR code shown in the frontend or in the console.
matterbridge -childbridge
Matterbridge exposes each registered plugins, and you have to pair each one by scanning the QR code shown in the frontend or in the console.
matterbridge -help
Matterbridge has a frontend available on http://localhost:3000
You can change the default port by adding the frontend parameter when you launch it.
Here's how to specify a different port number:
matterbridge -bridge -frontend [port number]
matterbridge -childbridge -frontend [port number]
Home page:
Devices page:
This an example of an accessory platform plugin.
It exposes a virtual cover device that continuously moves position and shows how to use the command handlers (you can control the device).
An Accessory platform plugin only exposes one device.
This an example of a dynamic platform plugin.
It exposes a switch with onOff, a light with onOff-levelControl-colorControl, an outlet with onOff and a WindoweCovering device.
All these virtual devices continuously change state and position. The plugin also shows how to use all the command handlers (you can control all the devices).
A Dynamic platform plugin exposes as many devices as you need (the limit for the Home app is 150 accessories for bridge).
Matterbridge can run as many plugins as you want.
The history works in both bridge and childbridge mode.
The Eve app only shows the history when the plugins run like an AccessoryPlatform in childbridge mode (this means the plugin is paired directly).
To install i.e. https://github.com/Luligu/matterbridge-zigbee2mqtt
On windows:
cd $HOME\Matterbridge
npm install -g matterbridge-zigbee2mqtt
matterbridge -add matterbridge-zigbee2mqtt
On linux:
cd ~/Matterbridge
sudo npm install -g matterbridge-zigbee2mqtt
matterbridge -add matterbridge-zigbee2mqtt
To install i.e. https://github.com/Luligu/matterbridge-example-accessory-platform
On windows:
cd $HOME\Matterbridge
On linux:
cd ~/Matterbridge
then clone the plugin
git clone https://github.com/Luligu/matterbridge-example-accessory-platform
cd matterbridge-example-accessory-platform
npm install
npm run build
then add the plugin to Matterbridge
matterbridge -add .\
matterbridge -add [plugin path or plugin name]
matterbridge -remove [plugin path or plugin name]
matterbridge -disable [plugin path or plugin name]
matterbridge -enable [plugin path or plugin name]
The easiest way is to clone:
-
https://github.com/Luligu/matterbridge-example-accessory-platform if you want to create an Accessory Platform Plugin.
-
https://github.com/Luligu/matterbridge-example-dynamic-platform if you want to create a Dynamic Platform Plugin.
Then change the name, version, description and author in the package.json.
Add your plugin logic in platform.ts.
The plugin name.
The plugin platform type.
The plugin config (loaded before the platform constructor is called and saved after onShutdown() is called). Here you can store your plugin configuration (see matterbridge-zigbee2mqtt for example)
The method onStart() is where you have to create your MatterbridgeDevice and add all needed clusters and command handlers.
The MatterbridgeDevice class has the create cluster methods already done and all command handlers needed (see plugin examples).
The method is called when Matterbridge load the plugin.
The method onConfigure() is where you can configure or initialize your device.
The method is called when the platform is commissioned.
The method onShutdown() is where you have to eventually cleanup some resources.
The method is called when Matterbridge is shutting down.
After you created your device, add it to the platform.
You can unregister one or more device.
You can unregister all devices you added.
It can be useful to call this method from onShutdown() if you don't want to keep all the devices during development.
Create a systemctl configuration file for Matterbridge
sudo nano /etc/systemd/system/matterbridge.service
Add the following to this file, replacing twice USER with your user name (e.g. pi):
[Unit]
Description=matterbridge
After=network.target
[Service]
Type=simple
ExecStart=/usr/bin/matterbridge -bridge
WorkingDirectory=/home/<USER>/Matterbridge
StandardOutput=inherit
StandardError=inherit
Restart=always
RestartSec=10s
TimeoutStopSec=30s
User=<USER>
[Install]
WantedBy=multi-user.target
If you modify it after, then run:
sudo systemctl daemon-reload
sudo systemctl start matterbridge
sudo systemctl stop matterbridge
sudo systemctl status matterbridge.service
sudo journalctl -u matterbridge.service -f --output cat
sudo systemctl enable matterbridge.service
sudo systemctl disable matterbridge.service
Thank you for your interest in contributing to my project!
I warmly welcome contributions to this project! Whether it's reporting bugs, proposing new features, updating documentation, or writing code, your help is greatly appreciated.
- Fork this repository to your own GitHub account and clone it to your local device.
- Make the necessary changes and test them out
- Commit your changes and push to your forked repository
- Create a new pull request from my repository and I'll be glad to check it out
- Be sure to follow the existing code style
- Add unit tests for any new or changed functionality if possible
- In your pull request, do describe what your changes do and how they work
We believe in a welcoming and respectful community for all. Please make sure to follow our Code of Conduct in all your interactions with the project.
If you find this project helpful and you wish to support the ongoing development, you can do so by buying me a coffee. Click on the badge below to get started:
Thank you for your support!