Matterbridge zigbee2mqtt is a matterbridge production-level plugin that expose all zigbee2mqtt devices and groups to Matter.
No hub or dedicated hardware needed.
Follow these steps to install or update Matterbridge if it is not already installed and up to date:
on Windows:
npm install -g matterbridge
on Linux (you need the necessary permissions):
sudo npm install -g matterbridge
See the complete guidelines on Matterbridge for more information.
A fully working installation of zigbee2MQTT is required.
See the guidelines on zigbee2mqtt for more information.
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
Then start Matterbridge
matterbridge -bridge
On windows:
cd $HOME\Matterbridge
git clone https://github.com/Luligu/matterbridge-zigbee2mqtt
cd matterbridge-zigbee2mqtt
npm install
npm run build
matterbridge -add .\
On linux:
cd ~/Matterbridge
git clone https://github.com/Luligu/matterbridge-zigbee2mqtt
cd matterbridge-zigbee2mqtt
npm install
npm run build
matterbridge -add ./
Then start Matterbridge
matterbridge -bridge
If needed you can configure the mqtt host, port, topic, username and password.
If the whiteList is defined only the devices included are exposed to Matter.
If the blackList is defined the devices included will not be exposed to Matter.
If any device creates issues put it in the blackList.
The switchList, lightList and outletList are used if you want to expose the z2m device like switch, light or outlet.
The featureBlackList allows to globally (for all devices) blacklist a z2m feature if you don't want to expose it (e.g. device_temperature).
The deviceFeatureBlackList allows to blacklist a z2m feature for a single device if you don't want to expose it (e.g. temperature for a motion sensor).
The unregisterOnShutdown option allows to remove from the bridge all z2m devices when you shut down Matterbridge.
These are the default vules:
{
"name": "matterbridge-zigbee2mqtt",
"type": "DynamicPlatform",
"unregisterOnShutdown": false,
"host": "localhost",
"port": 1883,
"topic": "zigbee2mqtt",
"username": "",
"password": "",
"whiteList": [],
"blackList": [],
"switchList": [],
"lightList": [],
"outletList": [],
"featureBlackList": [],
"deviceFeatureBlackList": {}
}
If you want to exclude "device_temperature" for all the devices, add to the config
{
...
"featureBlackList": ["device_temperature"]
...
}
If you want to exclude "temperature" and "humidity" for the device "My motion sensor" and "device_temperature" only for the device "My climate sensor", add to the config
{
...
"deviceFeatureBlackList": {
"My motion sensor": ["temperature", "humidity"],
"My climate sensor": ["device_temperature"]
}
...
}
You can edit the config file (shutdown Matterbridge before):
On windows:
cd $HOME\.matterbridge
notepad matterbridge-zigbee2mqtt.config.json
On linux:
cd ~/.matterbridge
nano matterbridge-zigbee2mqtt.config.json
Out of the box, this plugin supports all possible conversion from zigbee2mqtt to Matter 1.1.
The latest release also supports all clusters in the multi endpoints devices (e.g. DIY devices or the double channel switches/dimmers).
Since the Matter support in the available ecosystems (controllers) is very limited and, when available, only covers Matter 1.1 specifications, some z2m devices cannot be exposed properly or cannot be exposed at all.
We discoverd that Matter support in Home Assistant is instead advanced and includes some clusters not supported by other ecosystems. These clusters like EveHistory have been added so with HA you can see Voltage, Current, Consumption and TotalConsumption (screenshot https://github.com/Luligu/matterbridge/blob/main/screenshot/Screenshot%20HA%20sm-dc-power-m.png).
If one of your devices is not supported out of the box, open an issue and we will try to support it if possible.
- Scene buttons are exposed correctly only when they send "single", "double" and "hold" actions (this is due to the Home app supporting only these 3 events.) In the next releases the scene buttons with more actions will be mapped to different endpoints like in my plugin homebridge-mqtt-accessories.
The HomePods, being a WiFi devices, create some message trasmission errors sometimes. The Apple TV with network cable is more reliable (but also more expensive).
The DoorLock cluster in the Home app takes a while to get online. The Home app shows no response for 1 or 2 seconds but then the accessory goes online. With the Eve app or the Controller app this issue is not present.