Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/luligu/matterbridge-zigbee2mqtt
Matterbridge zigbee2mqtt plugin
https://github.com/luligu/matterbridge-zigbee2mqtt
alexa bridge connectedthings google-home homeassistant homekit iot matter matterbridge matterprotocol plugin siri smarthome zigbee zigbee2mqtt
Last synced: 1 day ago
JSON representation
Matterbridge zigbee2mqtt plugin
- Host: GitHub
- URL: https://github.com/luligu/matterbridge-zigbee2mqtt
- Owner: Luligu
- License: apache-2.0
- Created: 2024-02-25T10:12:39.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-12-12T15:25:52.000Z (10 days ago)
- Last Synced: 2024-12-15T15:57:53.800Z (7 days ago)
- Topics: alexa, bridge, connectedthings, google-home, homeassistant, homekit, iot, matter, matterbridge, matterprotocol, plugin, siri, smarthome, zigbee, zigbee2mqtt
- Language: TypeScript
- Homepage: https://github.com/Luligu/matterbridge-zigbee2mqtt/blob/main/README.md
- Size: 1.03 MB
- Stars: 82
- Watchers: 3
- Forks: 9
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# 
Matterbridge zigbee2mqtt plugin
[](https://www.npmjs.com/package/matterbridge-zigbee2mqtt)
[](https://www.npmjs.com/package/matterbridge-zigbee2mqtt)
[](https://hub.docker.com/r/luligu/matterbridge)
[](https://hub.docker.com/r/luligu/matterbridge)
[](https://www.npmjs.com/package/matterbridge)
[](https://www.npmjs.com/package/matter-history)
[](https://www.npmjs.com/package/node-ansi-logger)
[](https://www.npmjs.com/package/node-persist-manager)
---
Matterbridge zigbee2mqtt is a matterbridge production-level plugin that expose all zigbee2mqtt devices and groups to Matter.
No hub or dedicated hardware needed.
Interested in super fast and autonomous automations for zigbee2mqtt? Try this: https://github.com/Luligu/zigbee2mqtt-automations
If you like this project and find it useful, please consider giving it a star on GitHub at https://github.com/Luligu/matterbridge-zigbee2mqtt and sponsoring it.
## Prerequisites
### Matterbridge
Follow these steps to install or update Matterbridge if it is not already installed and up to date:
on Windows:
```
npm install -g matterbridge --omit=dev
```
on Linux (you need the necessary permissions):
```
sudo npm install -g matterbridge --omit=dev
```
See the complete guidelines on [Matterbridge](https://github.com/Luligu/matterbridge/blob/main/README.md) for more information.
### Zigbee2mqtt
A fully working installation of zigbee2MQTT is required.
See the guidelines on [zigbee2mqtt](https://github.com/Koenkk/zigbee2mqtt/blob/master/README.md) for more information.
## How to install the plugin
### With the frontend (preferred method)
Just open the frontend, select the matterbridge-zigbee2mqtt plugin and click on install. If you are using Matterbridge with Docker (I suggest you do it), all plugins are already loaded in the container so you just need to select and add it.
### Without the frontend
On windows:
```
cd $HOME\Matterbridge
npm install -g matterbridge-zigbee2mqtt --omit=dev
matterbridge -add matterbridge-zigbee2mqtt
```
On linux:
```
cd ~/Matterbridge
sudo npm install -g matterbridge-zigbee2mqtt --omit=dev
matterbridge -add matterbridge-zigbee2mqtt
```
Then start Matterbridge
```
matterbridge
```
## If you want to contribute to the plugin
On windows:
```
cd $HOME\Matterbridge
git clone https://github.com/Luligu/matterbridge-zigbee2mqtt
cd matterbridge-zigbee2mqtt
npm ci
npm run dev:link
npm run build
matterbridge -add .\
```
On linux:
```
cd ~/Matterbridge
git clone https://github.com/Luligu/matterbridge-zigbee2mqtt
cd matterbridge-zigbee2mqtt
npm ci
npm run dev:link
npm run build
matterbridge -add ./
```
Then start Matterbridge
```
matterbridge -bridge
```
# Config file
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:
```json
{
"name": "matterbridge-zigbee2mqtt",
"type": "DynamicPlatform",
"unregisterOnShutdown": false,
"host": "localhost",
"port": 1883,
"topic": "zigbee2mqtt",
"username": "",
"password": "",
"whiteList": [],
"blackList": [],
"switchList": [],
"lightList": [],
"outletList": [],
"featureBlackList": [],
"deviceFeatureBlackList": {},
"postfixHostname": true
}
```
If you want to exclude "device_temperature" for all the devices, add to the config
```json
{
...
"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
```json
{
...
"deviceFeatureBlackList": {
"My motion sensor": ["temperature", "humidity"],
"My climate sensor": ["device_temperature"]
}
...
}
```
By default matterbridge uses hostname in order to make entities unique, however in some cases
you may not want this behavior. You can use "postfixHostname" boolean flag to disable this behavior:
```json
{
...
"postfixHostname": false
...
}
```
From the release 1.2.14 of Matterbridge you can edit the config file directly in the frontend.
You can edit the config file manually if you prefer:
- shutdown Matterbridge before: if you use docker send docker stop matterbridge;
- edit and save the config;
- start Matterbridge: if you use docker send docker start matterbridge.
On windows:
```
cd $HOME\.matterbridge
notepad matterbridge-zigbee2mqtt.config.json
```
On linux:
```
cd ~/.matterbridge
nano matterbridge-zigbee2mqtt.config.json
```
# Frequently Asked Questions
## What is supported?
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 sometimes 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 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).
## Unsupported devices
If one of your devices is not supported out of the box, open an issue and we will try to support it if possible.
## Conversion strategies between zigbee2MQTT and Matter ecosystems
- The Coordinator and the dedicated routers (Texas.Instruments and SMLIGHT) are exposed like DoorLock. They change state when permitJoin is changed from z2m and turn on or off permitJoin when they are opened or closed from the controller. If you don't want to see them in the controller app just add them to the blackList.
- Scene buttons are now fully exposed (all actions). The actions are mapped in groups of 3, with each group on a sub endpoint. This is because the controllers expose event in group of single, double, long press.
In the log you will find the mapping schema like this one:
```
[16:25:14.321] [Smart button] Device Smart button has actions mapped to these switches on sub endpoints:
[16:25:14.321] [Smart button] controller events <=> zigbee2mqtt actions
[16:25:14.322] [Smart button] -- Button 1: Single Press <=> single
[16:25:14.323] [Smart button] -- Button 1: Double Press <=> double
[16:25:14.323] [Smart button] -- Button 1: Long Press <=> hold
[16:25:14.323] [Smart button] -- Button 2: Single Press <=> brightness_move_to_level
[16:25:14.324] [Smart button] -- Button 2: Double Press <=> color_temperature_move
[16:25:14.324] [Smart button] -- Button 2: Long Press <=> brightness_step_up
[16:25:14.324] [Smart button] -- Button 3: Single Press <=> brightness_step_down
[16:25:14.324] [Smart button] -- Button 3: Double Press <=> on
[16:25:14.325] [Smart button] -- Button 3: Long Press <=> off
```
# Known issues
For general controller issues check the Matterbridge Known issues section
[See the known issues here](https://github.com/Luligu/matterbridge?tab=readme-ov-file#known-issues)
## Apple Home
## Home Assistant (Matter Server is still in Beta)
## Google Home
## Alexa
In the plugin config add each switch device to the lightList or outletList if they don't show up like switch (Matterbridge uses a modified switch device type without client cluster that Alexa doesn't recognize).
## SmartThings
## eWeLink
## Tuya/Smart Life