matterbridge-zigbee2mqtt 2.5.1 → 2.6.0-dev-20250608-0e2d35b

package/CHANGELOG.md

@@ -10,6 +10,8 @@ If you like this project and find it useful, please consider giving it a star on
 
 ### Breaking Changes
 
+The host config option must now start with mqtt:// or mqtts:// to distinguish between unsecure and SSL/TLS connection with the MQTT broker.
+
 New device types:
 
 - extendedColorLight
@@ -19,10 +21,14 @@ New device types:
 
 If your controller has issues detecting the new device type, blacklist these devices, restart, wait 5 minutes that the controller removes them, remove the blacklist and restart again. This will create a new endpoint on the controller and the controllers will likely remove and recreate all the devices so make a backup of configurations (i.e. room assignements) and automations on the controller.
 
-## [2.5.1] - 2025-06-04
+## [2.6.0] - 2025-06-07
 
 ### Added
 
+- [npm]: The dev of matterbridge-zigbee2mqtt is published with tag **dev** on **npm** each day at 00:00 UTC if there is a new commit.
+- [mqtt]: Added MQTT SSL/TLS server authentication. Prefix host with mqtts:// and provide the ca certificate for self-signed server certificates.
+- [mqtt]: Added MQTT SSL/TLS client authentication. Prefix host with mqtts:// and provide the client certificate and key. Provide also the ca certificate for self-signed client certificates.
+
 ### Changed
 
 - [package]: Updated package.
@@ -30,6 +36,8 @@ If your controller has issues detecting the new device type, blacklist these dev
 
 ### Fixed
 
+- [subscribe]: Removed async from handlers.
+
 <a href="https://www.buymeacoffee.com/luligugithub">
   <img src="bmc-button.svg" alt="Buy me a coffee" width="80">
 </a>

package/README.md

@@ -143,12 +143,16 @@ These are the default vules:
 {
   "name": "matterbridge-zigbee2mqtt",
   "type": "DynamicPlatform",
-  "unregisterOnShutdown": false,
-  "host": "localhost",
+  "host": "mqtt://localhost",
   "port": 1883,
+  "protocolVersion": 5,
   "topic": "zigbee2mqtt",
   "username": "",
   "password": "",
+  "ca": undefined,
+  "cert": undefined,
+  "key": undefined,
+  "rejectUnauthorized": true,
   "whiteList": [],
   "blackList": [],
   "switchList": [],

package/dist/entity.js

@@ -1274,7 +1274,7 @@ export class ZigbeeDevice extends ZigbeeEntity {
                     }
                 }
             });
-            zigbeeDevice.bridgedDevice.subscribeAttribute(ThermostatCluster.id, 'systemMode', async (value) => {
+            zigbeeDevice.bridgedDevice.subscribeAttribute(ThermostatCluster.id, 'systemMode', (value) => {
                 if (isValidNumber(value, Thermostat.SystemMode.Off, Thermostat.SystemMode.FanOnly) && zigbeeDevice.thermostatSystemModeLookup[value] !== '') {
                     const system_mode = zigbeeDevice.thermostatSystemModeLookup[value];
                     zigbeeDevice.log.debug(`Subscribe systemMode called for ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} with ${value} => ${system_mode}`);
@@ -1286,7 +1286,7 @@ export class ZigbeeDevice extends ZigbeeEntity {
                 }
             }, zigbeeDevice.log);
             if (zigbeeDevice.bridgedDevice.hasAttributeServer(ThermostatCluster.id, 'occupiedHeatingSetpoint'))
-                zigbeeDevice.bridgedDevice.subscribeAttribute(ThermostatCluster.id, 'occupiedHeatingSetpoint', async (value) => {
+                zigbeeDevice.bridgedDevice.subscribeAttribute(ThermostatCluster.id, 'occupiedHeatingSetpoint', (value) => {
                     zigbeeDevice.log.debug(`Subscribe occupiedHeatingSetpoint called for ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} with:`, value);
                     if (zigbeeDevice.propertyMap.has('current_heating_setpoint'))
                         zigbeeDevice.publishCommand('OccupiedHeatingSetpoint', device.friendly_name, { current_heating_setpoint: Math.round(value / 100) });
@@ -1298,7 +1298,7 @@ export class ZigbeeDevice extends ZigbeeEntity {
                     }, 5 * 1000);
                 }, zigbeeDevice.log);
             if (zigbeeDevice.bridgedDevice.hasAttributeServer(ThermostatCluster.id, 'occupiedCoolingSetpoint'))
-                zigbeeDevice.bridgedDevice.subscribeAttribute(ThermostatCluster.id, 'occupiedCoolingSetpoint', async (value) => {
+                zigbeeDevice.bridgedDevice.subscribeAttribute(ThermostatCluster.id, 'occupiedCoolingSetpoint', (value) => {
                     zigbeeDevice.log.debug(`Subscribe occupiedCoolingSetpoint called for ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} with:`, value);
                     if (zigbeeDevice.propertyMap.has('current_heating_setpoint'))
                         zigbeeDevice.publishCommand('OccupiedCoolingSetpoint', device.friendly_name, { current_heating_setpoint: Math.round(value / 100) });

package/dist/platform.js

@@ -12,7 +12,7 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
     zigbeeEntities = [];
     injectTimer;
     namePostfix = 1;
-    mqttHost = 'localhost';
+    mqttHost = 'mqtt://localhost';
     mqttPort = 1883;
     mqttTopic = 'zigbee2mqtt';
     mqttUsername = undefined;
@@ -45,8 +45,10 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
         this.debugEnabled = config.debug;
         this.shouldStart = false;
         this.shouldConfigure = false;
-        if (config.host)
+        if (config.host && typeof config.host === 'string') {
             this.mqttHost = config.host;
+            this.mqttHost = !this.mqttHost.startsWith('mqtt://') && !this.mqttHost.startsWith('mqtts://') ? 'mqtt://' + this.mqttHost : this.mqttHost;
+        }
         if (config.port)
             this.mqttPort = config.port;
         if (config.topic)
@@ -55,8 +57,12 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
             this.mqttUsername = config.username;
         if (config.password)
             this.mqttPassword = config.password;
-        if (config.protocolVersion && typeof config.protocolVersion === 'number' && config.protocolVersion >= 3 && config.protocolVersion <= 5)
+        if (config.protocolVersion && typeof config.protocolVersion === 'number' && config.protocolVersion >= 3 && config.protocolVersion <= 5) {
             this.mqttProtocol = config.protocolVersion;
+        }
+        else {
+            this.mqttProtocol = 5;
+        }
         if (config.switchList)
             this.switchList = config.switchList;
         if (config.lightList)
@@ -67,8 +73,9 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
             this.featureBlackList = config.featureBlackList;
         if (config.deviceFeatureBlackList)
             this.deviceFeatureBlackList = config.deviceFeatureBlackList;
-        if (config.postfix)
+        if (config.postfix && typeof config.postfix === 'string') {
             this.postfix = config.postfix;
+        }
         this.postfix = this.postfix.trim().slice(0, 3);
         config.host = this.mqttHost;
         config.port = this.mqttPort;
@@ -87,19 +94,13 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
             config.scenesType = 'outlet';
         if (config.scenesPrefix === undefined)
             config.scenesPrefix = true;
-        if (config.type === 'MatterbridgeExtension') {
-            this.z2m = new Zigbee2MQTT(this.mqttHost, this.mqttPort, this.mqttTopic, this.mqttUsername, this.mqttPassword, this.mqttProtocol, this.debugEnabled);
-            this.z2m.setLogDebug(this.debugEnabled);
-            this.log.debug('Created ZigbeePlatform as Matterbridge extension');
-            return;
-        }
         this.log.info(`Initializing platform: ${CYAN}${this.config.name}${nf} version: ${CYAN}${this.config.version}${rs}`);
         this.log.info(`Loaded zigbee2mqtt parameters from ${CYAN}${path.join(matterbridge.matterbridgeDirectory, 'matterbridge-zigbee2mqtt.config.json')}${rs}`);
-        this.z2m = new Zigbee2MQTT(this.mqttHost, this.mqttPort, this.mqttTopic, this.mqttUsername, this.mqttPassword, this.mqttProtocol, this.debugEnabled);
+        this.z2m = new Zigbee2MQTT(this.mqttHost, this.mqttPort, this.mqttTopic, this.mqttUsername, this.mqttPassword, this.mqttProtocol, this.config.ca, this.config.rejectUnauthorized, this.config.cert, this.config.key, this.debugEnabled);
         this.z2m.setLogDebug(this.debugEnabled);
         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: ${'mqtt://' + this.mqttHost + ':' + this.mqttPort.toString()}`);
+            this.log.info(`Connecting to MQTT broker: ${this.mqttHost + ':' + this.mqttPort.toString()}`);
             this.z2m.start();
         }
         else {

package/dist/zigbee2mqtt.js

@@ -2,10 +2,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import * as util from 'node:util';
 import * as crypto from 'node:crypto';
-import { connectAsync } from 'mqtt';
 import { EventEmitter } from 'node:events';
-import { AnsiLogger, rs, db, dn, gn, er, zb, hk, id, idn, ign, REVERSE, REVERSEOFF } from 'node-ansi-logger';
 import { mkdir } from 'node:fs/promises';
+import { connectAsync } from 'mqtt';
+import { AnsiLogger, rs, db, dn, gn, er, zb, hk, id, idn, ign, REVERSE, REVERSEOFF } from 'node-ansi-logger';
 const writeFile = util.promisify(fs.writeFile);
 export class Zigbee2MQTT extends EventEmitter {
     log;
@@ -32,9 +32,9 @@ export class Zigbee2MQTT extends EventEmitter {
     z2mGroups;
     loggedEntries = 0;
     options = {
-        clientId: 'classZigbee2MQTT_' + crypto.randomBytes(8).toString('hex'),
+        clientId: 'matterbridge_' + crypto.randomBytes(8).toString('hex'),
         keepalive: 60,
-        protocolId: 'MQTT',
+        protocol: 'mqtt',
         protocolVersion: 5,
         reconnectPeriod: 5000,
         connectTimeout: 60 * 1000,
@@ -42,8 +42,9 @@ export class Zigbee2MQTT extends EventEmitter {
         password: undefined,
         clean: true,
     };
-    constructor(mqttHost, mqttPort, mqttTopic, mqttUsername = undefined, mqttPassword = undefined, protocolVersion = 5, debug = false) {
+    constructor(mqttHost, mqttPort, mqttTopic, mqttUsername, mqttPassword, protocolVersion = 5, ca, rejectUnauthorized, cert, key, debug = false) {
         super();
+        this.log = new AnsiLogger({ logName: 'Zigbee2MQTT', logTimestampFormat: 4, logLevel: debug ? "debug" : "info" });
         this.mqttHost = mqttHost;
         this.mqttPort = mqttPort;
         this.mqttTopic = mqttTopic;
@@ -52,6 +53,54 @@ export class Zigbee2MQTT extends EventEmitter {
         this.options.username = mqttUsername !== undefined && mqttUsername !== '' ? mqttUsername : undefined;
         this.options.password = mqttPassword !== undefined && mqttPassword !== '' ? mqttPassword : undefined;
         this.options.protocolVersion = protocolVersion;
+        if (mqttHost.startsWith('mqtts://')) {
+            this.log.debug('Using mqtts:// protocol for secure MQTT connection');
+            if (!ca) {
+                this.log.info('When using mqtts:// protocol, you must provide the ca certificate for SSL/TLS connections with self-signed certificates.');
+            }
+            else {
+                try {
+                    fs.accessSync(ca, fs.constants.R_OK);
+                    this.options.ca = fs.readFileSync(ca);
+                }
+                catch (error) {
+                    this.log.error(`Error reading the CA certificate from ${ca}:`, error);
+                }
+            }
+            this.options.rejectUnauthorized = rejectUnauthorized !== undefined ? rejectUnauthorized : true;
+            this.options.protocol = 'mqtts';
+            if (cert && key) {
+                try {
+                    fs.accessSync(cert, fs.constants.R_OK);
+                    this.options.cert = fs.readFileSync(cert);
+                }
+                catch (error) {
+                    this.log.error(`Error reading the client certificate from ${cert}:`, error);
+                }
+                try {
+                    fs.accessSync(key, fs.constants.R_OK);
+                    this.options.key = fs.readFileSync(key);
+                }
+                catch (error) {
+                    this.log.error(`Error reading the client key from ${key}:`, error);
+                }
+            }
+        }
+        else if (mqttHost.startsWith('mqtt://')) {
+            this.log.debug('Using mqtt:// protocol for non-secure MQTT connection');
+            if (ca) {
+                this.log.warn('You are using mqtt:// protocol, but you provided a CA certificate. It will be ignored.');
+            }
+            if (cert) {
+                this.log.warn('You are using mqtt:// protocol, but you provided a certificate. It will be ignored.');
+            }
+            if (key) {
+                this.log.warn('You are using mqtt:// 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.z2mIsAvailabilityEnabled = false;
         this.z2mIsOnline = false;
         this.z2mPermitJoin = false;
@@ -59,7 +108,6 @@ export class Zigbee2MQTT extends EventEmitter {
         this.z2mVersion = '';
         this.z2mDevices = [];
         this.z2mGroups = [];
-        this.log = new AnsiLogger({ logName: 'Zigbee2MQTT', logTimestampFormat: 4, logLevel: debug ? "debug" : "info" });
         this.log.debug(`Created new instance with host: ${mqttHost} port: ${mqttPort} protocol ${protocolVersion} topic: ${mqttTopic} username: ${mqttUsername !== undefined && mqttUsername !== '' ? mqttUsername : 'undefined'} password: ${mqttPassword !== undefined && mqttPassword !== '' ? '*****' : 'undefined'}`);
     }
     setLogDebug(logDebug) {
@@ -92,7 +140,7 @@ export class Zigbee2MQTT extends EventEmitter {
         }
     }
     getUrl() {
-        return 'mqtt://' + this.mqttHost + ':' + this.mqttPort.toString();
+        return this.mqttHost + ':' + this.mqttPort.toString();
     }
     async start() {
         this.log.debug(`Starting connection to ${this.getUrl()}...`);
@@ -156,7 +204,7 @@ export class Zigbee2MQTT extends EventEmitter {
                 catch (error) {
                     this.log.error('Error publishing keepalive MQTT message:', error);
                 }
-            }, (this.options.keepalive ?? 60) * 1000);
+            }, (this.options.keepalive ?? 60) * 1000).unref();
         })
             .catch((error) => {
             this.log.error(`Error connecting to ${this.getUrl()}: ${error.message}`);

package/matterbridge-zigbee2mqtt.schema.json

@@ -17,36 +17,53 @@
       "ui:widget": "hidden"
     },
     "host": {
-      "description": "MQTT server host (IP address or hostname without mqtt://)",
+      "description": "MQTT server host (IP address or hostname with mqtt:// or mqtts:// prefix). 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": "localhost"
+      "default": "mqtt://localhost"
+    },
+    "port": {
+      "description": "MQTT server port (i.e. 1883 for mqtt:// and 8883 for mqtts://).",
+      "type": "number",
+      "default": 1883
+    },
+    "protocolVersion": {
+      "description": "MQTT server protocol version 3, 4 or 5 (default 5). Version 5 is recommended for most modern MQTT brokers.",
+      "type": "number",
+      "default": 5
     },
     "username": {
-      "description": "MQTT server authentication user",
+      "description": "MQTT server authentication user. Only required if the MQTT server requires authentication (i.e allow_anonymous false)",
       "type": "string"
     },
     "password": {
-      "description": "MQTT server authentication password",
+      "description": "MQTT server authentication password. Only required if the MQTT server requires authentication (i.e allow_anonymous false)",
       "type": "string",
       "ui:widget": "password"
     },
-    "port": {
-      "description": "MQTT server port (default 1883)",
-      "type": "number",
-      "default": 1883
+    "ca": {
+      "description": "Absolute path to the SSL/TLS CA certificate used to sign both the server and client certificates (PEM format). Required for secure connections (i.e. mqtts://) with self-signed certificates.",
+      "type": "string"
     },
-    "protocolVersion": {
-      "description": "MQTT server protocol version 3, 4 or 5 (default 5)",
-      "type": "number",
-      "default": 5
+    "rejectUnauthorized": {
+      "description": "Reject unauthorized MQTT server. Only used for secure connections (i.e. mqtts://).",
+      "type": "boolean",
+      "default": true
+    },
+    "cert": {
+      "description": "Absolute path to the SSL/TLS MQTT client certificate (PEM format). Only required if the MQTT server requires a client certificate for authentication (i.e. require_certificate true).",
+      "type": "string"
+    },
+    "key": {
+      "description": "Absolute path to the SSL/TLS MQTT client private key (PEM format). Only required if the MQTT server requires a client certificate for authentication (i.e. require_certificate true).",
+      "type": "string"
     },
     "topic": {
-      "description": "MQTT base topic for Zigbee2MQTT MQTT messages",
+      "description": "MQTT base topic for Zigbee2MQTT MQTT messages. This should match the base_topic in your Zigbee2MQTT configuration.yaml file.",
       "type": "string",
       "default": "zigbee2mqtt"
     },
     "zigbeeFrontend": {
-      "description": "Zigbee frontend host to prefix the configUrl (i.e. http://192.168.1.100:8080)",
+      "description": "Zigbee frontend host to prefix the configUrl from matterbridge frontend (i.e. http://192.168.1.100:8080)",
       "type": "string",
       "default": "http://localhost:8080"
     },

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "matterbridge-zigbee2mqtt",
-  "version": "2.5.1",
+  "version": "2.6.0-dev-20250608-0e2d35b",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "matterbridge-zigbee2mqtt",
-      "version": "2.5.1",
+      "version": "2.6.0-dev-20250608-0e2d35b",
       "license": "Apache-2.0",
       "dependencies": {
         "moment": "2.30.1",
@@ -23,18 +23,18 @@
       }
     },
     "node_modules/@babel/runtime": {
-      "version": "7.27.4",
-      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.27.4.tgz",
-      "integrity": "sha512-t3yaEOuGu9NlIZ+hIeGbBjFtZT7j2cb2tg0fuaJKeGotchRjjLfrBA9Kwf8quhpP1EUuxModQg04q/mBwyg8uA==",
+      "version": "7.27.6",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.27.6.tgz",
+      "integrity": "sha512-vbavdySgbTTrmFE+EsiqUTzlOr5bzlnJtUv9PynGCAKvfQqjIXbvFdumPM/GxMDfyuGMJaJAU6TO4zc1Jf1i8Q==",
       "license": "MIT",
       "engines": {
         "node": ">=6.9.0"
       }
     },
     "node_modules/@types/node": {
-      "version": "22.15.29",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.15.29.tgz",
-      "integrity": "sha512-LNdjOkUDlU1RZb8e1kOIUpN1qQUlzGkEtbVNo53vbrwDg5om6oduhm4SiUaPW5ASTXhAiP0jInWG8Qx9fVlOeQ==",
+      "version": "22.15.30",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.15.30.tgz",
+      "integrity": "sha512-6Q7lr06bEHdlfplU6YRbgG1SFBdlsfNC4/lX+SkhiTs0cpJkOElmWls8PxDFv4yY/xKb8Y6SO0OmSX4wgqTZbA==",
       "license": "MIT",
       "dependencies": {
         "undici-types": "~6.21.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matterbridge-zigbee2mqtt",
-  "version": "2.5.1",
+  "version": "2.6.0-dev-20250608-0e2d35b",
   "description": "Matterbridge zigbee2mqtt plugin",
   "author": "https://github.com/Luligu",
   "license": "Apache-2.0",