matterbridge-zigbee2mqtt 3.0.2 → 3.0.3-dev-20251211-b4188c4

package/CHANGELOG.md

@@ -2,10 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
-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.
+If you like this project and find it useful, please consider giving it a star on [GitHub](https://github.com/Luligu/matterbridge-zigbee2mqtt) and sponsoring it.
 
 <a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
 
+## [3.0.3] - 2025-12-12
+
+### Changed
+
+- [package]: Updated dependencies.
+
+<a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/bmc-button.svg" alt="Buy me a coffee" width="80"></a>
+
 ## [3.0.2] - 2025-12-01
 
 ### Added

package/README.md

@@ -23,43 +23,25 @@ No cloud: all is local and fast.
 
 Interested in super fast and autonomous **[automations for zigbee2mqtt](https://github.com/Luligu/zigbee2mqtt-automations)**? 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.
+If you like this project and find it useful, please consider giving it a star on [GitHub](https://github.com/Luligu/matterbridge-zigbee2mqtt) and sponsoring it.
 
-<a href="https://www.buymeacoffee.com/luligugithub">
-  <img src="bmc-button.svg" alt="Buy me a coffee" width="120">
-</a>
+<a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
 
 ## Introduction
 
 Matterbridge enables non-Matter devices (Zigbee devices) to integrate with the Matter communication protocol. Bridges allow platforms that use other protocol standards to interoperate with the Matter ecosystem by integrating a Matter server into, or between, existing smart gateways, controllers, and hubs. Many commercial smart gateways provide a built-in Matter bridge that translates Matter to Zigbee or other protocols, making it possible for other ecosystems to communicate with them.
 
-The Matterbridge zigbee2mqtt plugin acts as a Matter Bridge, exposing all Zigbee devices and groups from [Zigbee2MQTT](https://github.com/Koenkk/zigbee2mqtt/blob/master/README.md) as Matter devices to third-party Matter controllers like Apple Home, Google Home, Amazon Alexa, and SmartThings, all while remaining local on the user's network. This allows fast, secure, and cloud-free control of Zigbee2MQTT-connected Zigbee devices from all major voice assistants as well as other third-party Matter clients.
+The Matterbridge zigbee2mqtt plugin acts as a Matter Bridge, exposing all Zigbee devices, groups and scenes from [Zigbee2MQTT](https://github.com/Koenkk/zigbee2mqtt/blob/master/README.md) as Matter devices to third-party Matter controllers like Apple Home, Google Home, Amazon Alexa, and SmartThings, all while remaining local on the user's network. This allows fast, secure, and cloud-free control of Zigbee2MQTT-connected Zigbee devices from all major voice assistants as well as other third-party Matter clients.
 
 ## 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 and macOS (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.
+See the guidelines on [Matterbridge](https://matterbridge.io/README.html) 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.
+See the guidelines on [zigbee2mqtt](https://www.zigbee2mqtt.io/) for more information.
 
 ## How to install the plugin
 
@@ -300,20 +282,70 @@ If one of your devices is not supported out of the box, open an issue and we wil
 
 ![See the screenshot here](https://github.com/Luligu/matterbridge-zigbee2mqtt/blob/main/screenshot/Smart%20button.png)
 
-# Known issues
+## Unix socket (Linux only)
 
-For general controller issues check the Matterbridge Known issues section
+### Create the directory for the socket
+
+```bash
+# Create the directory for the Unix socket if it doesn't exist
+sudo mkdir -p /var/run/mosquitto
+
+# Make sure the mosquitto user can access the socket
+sudo chown mosquitto:mosquitto /var/run/mosquitto
 
-[See the known issues here](https://github.com/Luligu/matterbridge?tab=readme-ov-file#known-issues)
+# Allow group users (e.g. matterbridge) to access the socket
+sudo chmod 750 /var/run/mosquitto
 
-## Apple Home
+# Optional: Add your user to the mosquitto group to access the socket without sudo
+# sudo usermod -aG mosquitto $USER
 
-## Home Assistant
+# If matterbridge runs like user matterbridge, add the matterbridge user to the mosquitto group to access the socket without sudo
+# sudo usermod -aG mosquitto matterbridge
+```
+
+Log out and back in after running usermod -aG for the group changes to take effect.
+
+```bash
+# Check the appropriate permissions for the directory
+sudo -u mosquitto ls -ld /var/run/mosquitto
+sudo -u mosquitto ls -l /var/run/mosquitto/mqtt.sock
+```
 
-## Google Home
+### Configure mosquitto to use Unix socket
 
-## Alexa
+Add this to your mosquitto.conf
 
-In the plugin config add each switch device to the lightList or outletList. Matterbridge uses a switch device type without client cluster that Alexa doesn't recognize.
+```
+# Unix socket listener
+listener 0 /var/run/mosquitto/mqtt.sock
+protocol mqtt
+allow_anonymous false
+```
+
+Restart mosquitto.
+
+```bash
+sudo systemctl restart mosquitto
+```
+
+### Configure docker to use Unix socket
+
+Add the unix socket volume for each service using it (i.e. mosquitto, zigbee2mqtt and matterbridge).
+
+```
+   volumes:
+      # Share the same run directory (anonymous volume)
+      - /var/run/mosquitto
+```
+
+Docker does NOT bind the host directory /var/run/mosquitto.
+
+That internal volume lives inside Docker’s own storage, not on your host filesystem.
+
+Because of this, there is no need to create /var/run/mosquitto on the host.
+
+# Known issues
+
+For general controller issues check the Matterbridge Known issues section
 
-## SmartThings
+[See the known issues here](https://github.com/Luligu/matterbridge?tab=readme-ov-file#known-general-issues)

package/dist/module.js

@@ -97,7 +97,7 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
         this.z2m.setLogDebug(config.debug);
         this.z2m.setDataPath(path.join(matterbridge.matterbridgePluginDirectory, 'matterbridge-zigbee2mqtt'));
         if (isValidString(this.mqttHost) && isValidNumber(this.mqttPort, 1, 65535)) {
-            this.log.info(`Connecting to MQTT broker: ${this.mqttHost + ':' + this.mqttPort.toString()}`);
+            this.log.info(`Connecting to MQTT broker: ${this.z2m.getUrl()}`);
             this.z2m.start();
         }
         else {

package/matterbridge-zigbee2mqtt.schema.json

@@ -17,12 +17,12 @@
       "ui:widget": "hidden"
     },
     "host": {
-      "description": "MQTT server host (IP address or hostname with mqtt:// or mqtts:// prefix) or unix://<SOCKET_PATH> for Unix socket on Linux (e.g. unix:///var/run/mqtt.sock). For secure connections, use the mqtts:// prefix and ensure your certificates are configured. If you use a hostname, make sure that the hostname is resolvable by the system running matterbridge.",
+      "description": "MQTT server host (IP address or hostname with mqtt:// or mqtts:// prefix) or unix://<SOCKET_PATH> for Unix socket on Linux (e.g. unix:///var/run/mosquitto/mqtt.sock). For secure connections, use the mqtts:// prefix and ensure your certificates are configured. If you use a hostname, make sure that the hostname is resolvable by the system running matterbridge.",
       "type": "string",
       "default": "mqtt://localhost"
     },
     "port": {
-      "description": "MQTT server port (i.e. 1883 for mqtt:// and 8883 for mqtts://).",
+      "description": "MQTT server port (i.e. 1883 for mqtt:// and 8883 for mqtts://). For Unix socket, this value is ignored.",
       "type": "number",
       "default": 1883
     },

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "matterbridge-zigbee2mqtt",
-  "version": "3.0.2",
+  "version": "3.0.3-dev-20251211-b4188c4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "matterbridge-zigbee2mqtt",
-      "version": "3.0.2",
+      "version": "3.0.3-dev-20251211-b4188c4",
       "license": "Apache-2.0",
       "dependencies": {
         "moment": "2.30.1",
@@ -32,18 +32,18 @@
       }
     },
     "node_modules/@types/node": {
-      "version": "24.10.1",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.10.1.tgz",
-      "integrity": "sha512-GNWcUTRBgIRJD5zj+Tq0fKOJ5XZajIiBroOF0yvj2bSU1WvNdYS/dn9UxwsujGW4JX06dnHyjV2y9rRaybH0iQ==",
+      "version": "25.0.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.0.0.tgz",
+      "integrity": "sha512-rl78HwuZlaDIUSeUKkmogkhebA+8K1Hy7tddZuJ3D0xV8pZSfsYGTsliGUol1JPzu9EKnTxPC4L1fiWouStRew==",
       "license": "MIT",
       "dependencies": {
         "undici-types": "~7.16.0"
       }
     },
     "node_modules/@types/readable-stream": {
-      "version": "4.0.22",
-      "resolved": "https://registry.npmjs.org/@types/readable-stream/-/readable-stream-4.0.22.tgz",
-      "integrity": "sha512-/FFhJpfCLAPwAcN3mFycNUa77ddnr8jTgF5VmSNetaemWB2cIlfCA9t0YTM3JAT0wOcv8D4tjPo7pkDhK3EJIg==",
+      "version": "4.0.23",
+      "resolved": "https://registry.npmjs.org/@types/readable-stream/-/readable-stream-4.0.23.tgz",
+      "integrity": "sha512-wwXrtQvbMHxCbBgjHaMGEmImFTQxxpfMOR/ZoQnXxB1woqkUbdLGFDgauo00Py9IudiaqSeiBiulSV9i6XIPig==",
       "license": "MIT",
       "dependencies": {
         "@types/node": "*"
@@ -91,9 +91,9 @@
       "license": "MIT"
     },
     "node_modules/bl": {
-      "version": "6.1.5",
-      "resolved": "https://registry.npmjs.org/bl/-/bl-6.1.5.tgz",
-      "integrity": "sha512-XylDt2P3JBttAwLpORq/hOEX9eJzP0r6Voa46C/WVvad8D1J0jW5876txB8FnzKtbdnU6X4Y1vOEvC6PllJrDg==",
+      "version": "6.1.6",
+      "resolved": "https://registry.npmjs.org/bl/-/bl-6.1.6.tgz",
+      "integrity": "sha512-jLsPgN/YSvPUg9UX0Kd73CXpm2Psg9FxMeCSXnk3WBO3CMT10JMwijubhGfHCnFu6TPn1ei3b975dxv7K2pWVg==",
       "license": "MIT",
       "dependencies": {
         "@types/readable-stream": "^4.0.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matterbridge-zigbee2mqtt",
-  "version": "3.0.2",
+  "version": "3.0.3-dev-20251211-b4188c4",
   "description": "Matterbridge zigbee2mqtt plugin",
   "author": "https://github.com/Luligu",
   "license": "Apache-2.0",