matterbridge-zigbee2mqtt 3.0.3-dev-20251211-d87d63c → 3.0.3-dev-20251211-ab441ae

package/CHANGELOG.md

@@ -8,9 +8,20 @@ If you like this project and find it useful, please consider giving it a star on
 
 ## [3.0.3] - 2025-12-12
 
+### Added
+
+- [mqtt]: Added a guide to setup Unix socket on the host.
+- [mqtt]: Added a guide to setup Unix socket with docker.
+
 ### Changed
 
 - [package]: Updated dependencies.
+- [mqtt]: Clarified in the schema that the mqtt port is not used with Unix socket.
+- [mqtt]: Removed options.protocol.
+
+### Fixed
+
+- [mqtt]: Fixed wrong log messages with Unix socket.
 
 <a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/bmc-button.svg" alt="Buy me a coffee" width="80"></a>
 

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,6 +282,69 @@ 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)
 
+## Unix socket (Linux only)
+
+### Create the directory for the Unix socket on the host
+
+```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
+
+# Allow group users (e.g. matterbridge) to access the socket
+sudo chmod 750 /var/run/mosquitto
+
+# Optional: Add your user to the mosquitto group to access the socket without sudo
+# sudo usermod -aG mosquitto $USER
+
+# 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
+```
+
+### Configure mosquitto to use Unix socket on the host
+
+Add this to your mosquitto.conf
+
+```
+# 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
+
+Create the directory on the host
+
+```bash
+mkdir -p "$HOME/mosquitto/run"
+sudo chown 1883:1883 "$HOME/mosquitto/run"
+sudo chmod 770 "$HOME/mosquitto/run"
+```
+
+Add the unix socket volume for each service using it (i.e. mosquitto, zigbee2mqtt and matterbridge).
+
+```
+  volumes:
+    - "${HOME}/mosquitto/run:/var/run/mosquitto"
+```
+
 # Known issues
 
 For general controller issues check the Matterbridge Known issues section

package/dist/module.js

@@ -12,7 +12,7 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
     config;
     bridgedDevices = [];
     zigbeeEntities = [];
-    connectTimeout = 30000;
+    connectTimeout = 90000;
     availabilityTimeout = 10000;
     injectTimer;
     mqttHost = 'mqtt://localhost';
@@ -49,7 +49,7 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
         if (config.host && typeof config.host === 'string') {
             this.mqttHost = config.host;
             this.mqttHost =
-                !this.mqttHost.startsWith('mqtt://') && !this.mqttHost.startsWith('mqtts://') && !this.mqttHost.startsWith('unix://') ? 'mqtt://' + this.mqttHost : this.mqttHost;
+                !this.mqttHost.startsWith('mqtt://') && !this.mqttHost.startsWith('mqtts://') && !this.mqttHost.startsWith('mqtt+unix://') ? 'mqtt://' + this.mqttHost : this.mqttHost;
         }
         if (config.port)
             this.mqttPort = config.port;
@@ -97,27 +97,27 @@ 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 {
             this.log.error(`Invalid MQTT broker host: ${this.mqttHost} or port: ${this.mqttPort}`);
         }
         this.z2m.on('mqtt_connect', () => {
-            this.log.info(`MQTT broker at ${this.z2m.mqttHost}:${this.z2m.mqttPort} connected`);
+            this.log.info(`MQTT broker at ${this.z2m.getUrl()} connected`);
             this.z2m.subscribe(this.z2m.mqttTopic + '/#');
         });
         this.z2m.on('mqtt_subscribed', () => {
-            this.log.info(`MQTT broker at ${this.z2m.mqttHost}:${this.z2m.mqttPort} subscribed to: ${this.z2m.mqttTopic + '/#'}`);
+            this.log.info(`MQTT broker at ${this.z2m.getUrl()} subscribed to: ${this.z2m.mqttTopic + '/#'}`);
         });
         this.z2m.on('close', () => {
-            this.log.warn(`MQTT broker at ${this.z2m.mqttHost}:${this.z2m.mqttPort} closed the connection`);
+            this.log.warn(`MQTT broker at ${this.z2m.getUrl()} closed the connection`);
         });
         this.z2m.on('end', () => {
-            this.log.warn(`MQTT broker at ${this.z2m.mqttHost}:${this.z2m.mqttPort} ended the connection`);
+            this.log.warn(`MQTT broker at ${this.z2m.getUrl()} ended the connection`);
         });
         this.z2m.on('mqtt_error', (error) => {
-            this.log.error(`MQTT broker at ${this.z2m.mqttHost}:${this.z2m.mqttPort} error:`, error);
+            this.log.error(`MQTT broker at ${this.z2m.getUrl()} error:`, error);
         });
         this.z2m.on('online', () => {
             this.log.info('zigbee2MQTT is online');

package/dist/zigbee2mqtt.js

@@ -33,7 +33,6 @@ export class Zigbee2MQTT extends EventEmitter {
     options = {
         clientId: 'matterbridge_' + crypto.randomBytes(8).toString('hex'),
         keepalive: 60,
-        protocol: 'mqtt',
         protocolVersion: 5,
         reconnectPeriod: 5000,
         connectTimeout: 60 * 1000,
@@ -99,20 +98,20 @@ export class Zigbee2MQTT extends EventEmitter {
                 this.log.warn('You are using mqtt:// protocol, but you provided a key. It will be ignored.');
             }
         }
-        else if (mqttHost.startsWith('unix://')) {
-            this.log.debug('Using unix:// protocol for MQTT connection over Unix socket');
+        else if (mqttHost.startsWith('mqtt+unix://')) {
+            this.log.debug('Using mqtt+unix:// protocol for MQTT connection over Unix socket');
             if (ca) {
-                this.log.warn('You are using unix:// protocol, but you provided a CA certificate. It will be ignored.');
+                this.log.warn('You are using mqtt+unix:// protocol, but you provided a CA certificate. It will be ignored.');
             }
             if (cert) {
-                this.log.warn('You are using unix:// protocol, but you provided a certificate. It will be ignored.');
+                this.log.warn('You are using mqtt+unix:// protocol, but you provided a certificate. It will be ignored.');
             }
             if (key) {
-                this.log.warn('You are using unix:// protocol, but you provided a key. It will be ignored.');
+                this.log.warn('You are using mqtt+unix:// protocol, but you provided a key. It will be ignored.');
             }
         }
         else {
-            this.log.warn('You are using an unsupported MQTT protocol. Please use mqtt:// or mqtts://.');
+            this.log.warn('You are using an unsupported MQTT protocol. Please use mqtt:// or mqtts:// or mqtt+unix://.');
         }
         this.z2mIsAvailabilityEnabled = false;
         this.z2mIsOnline = false;
@@ -168,7 +167,7 @@ export class Zigbee2MQTT extends EventEmitter {
         }
     }
     getUrl() {
-        return this.mqttHost.startsWith('unix://') ? this.mqttHost : this.mqttHost + ':' + this.mqttPort.toString();
+        return this.mqttHost.includes('unix://') ? this.mqttHost : this.mqttHost + ':' + this.mqttPort.toString();
     }
     async start() {
         this.log.debug(`Starting connection to ${this.getUrl()}...`);

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.3-dev-20251211-d87d63c",
+  "version": "3.0.3-dev-20251211-ab441ae",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "matterbridge-zigbee2mqtt",
-      "version": "3.0.3-dev-20251211-d87d63c",
+      "version": "3.0.3-dev-20251211-ab441ae",
       "license": "Apache-2.0",
       "dependencies": {
         "moment": "2.30.1",

package/package.json

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