matterbridge-zigbee2mqtt 3.0.3-dev-20251211-b4188c4 → 3.0.3-dev-20251211-1802e6b

package/CHANGELOG.md

@@ -8,9 +8,21 @@ 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]: Use mqtt+unix:///path for 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

@@ -284,7 +284,7 @@ If one of your devices is not supported out of the box, open an issue and we wil
 
 ## Unix socket (Linux only)
 
-### Create the directory for the socket
+### Create the directory for the Unix socket on the host
 
 ```bash
 # Create the directory for the Unix socket if it doesn't exist
@@ -311,7 +311,7 @@ sudo -u mosquitto ls -ld /var/run/mosquitto
 sudo -u mosquitto ls -l /var/run/mosquitto/mqtt.sock
 ```
 
-### Configure mosquitto to use Unix socket
+### Configure mosquitto to use Unix socket on the host
 
 Add this to your mosquitto.conf
 
@@ -330,19 +330,20 @@ 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).
+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"
 ```
-   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.
+Add the unix socket volume for each service using it (i.e. mosquitto, zigbee2mqtt and matterbridge).
 
-Because of this, there is no need to create /var/run/mosquitto on the host.
+```
+  volumes:
+    - "${HOME}/mosquitto/run:/var/run/mosquitto"
+```
 
 # Known issues
 

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;
@@ -104,20 +104,20 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
             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,7 +17,7 @@
       "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/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.",
+      "description": "MQTT server host (IP address or hostname with mqtt:// or mqtts:// prefix) or mqtt+unix://<SOCKET_PATH> for Unix socket on Linux (e.g. mqtt+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"
     },

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "matterbridge-zigbee2mqtt",
-  "version": "3.0.3-dev-20251211-b4188c4",
+  "version": "3.0.3-dev-20251211-1802e6b",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "matterbridge-zigbee2mqtt",
-      "version": "3.0.3-dev-20251211-b4188c4",
+      "version": "3.0.3-dev-20251211-1802e6b",
       "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-b4188c4",
+  "version": "3.0.3-dev-20251211-1802e6b",
   "description": "Matterbridge zigbee2mqtt plugin",
   "author": "https://github.com/Luligu",
   "license": "Apache-2.0",