matterbridge-zigbee2mqtt 2.5.0-dev.2 → 2.5.0-dev.4

package/CHANGELOG.md

@@ -17,9 +17,9 @@ New device types:
 - rainSensor
 - smokeSensor
 
-If your controller has issues detecting the new device type, blacklist these devices, restart, wait 5 minutes, remove the blacklist and restart again. This will create a new endpoint on the controller.
+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.
 
-## [2.5.0] - 2025-05-21
+## [2.5.0] - 2025-05-23
 
 ### Added
 
@@ -27,7 +27,11 @@ If your controller has issues detecting the new device type, blacklist these dev
 - [waterLeak]: Added waterLeakDetector device type for zigbee property "water_leak". Default to false (i.e. no alarm) since is not possible to get the property.
 - [rainSensor]: Added rainSensor device type for zigbee property "rain". Default to false (i.e. no alarm) since is not possible to get the property.
 - [smokeSensor]: Added smokeSensor device type for zigbee property "smoke". Default to false (i.e. no alarm) since is not possible to get the property.
-- [colorTemp]: Added conversion from color temperature to rgb for the devices that doesn't support color temperature.
+- [colorTemp]: Added conversion from color temperature to rgb for the rgb devices that don't support color temperature.
+- [battery]: Set batChargeLevel to warning if battery is less than 40% and the device doesn't expose battery_low.
+- [battery]: Set batChargeLevel to critical if battery is less than 20% and the device doesn't expose battery_low.
+- [retain]: Send retained mqtt states at startup if z2m has retain enabled.
+- [logger]: Added onChangeLoggerLevel() to the platform.
 
 ### Changed
 
@@ -36,6 +40,7 @@ If your controller has issues detecting the new device type, blacklist these dev
 - [plugin]: Requires Matterbridge 3.0.3.
 - [config]: As anticipated in the previous release, the parameter postfixHostname has been removed. Use postfix if needed.
 - [colorRgb]: Changed the default device type from colorTemperatureLight to extendedColorLight to solve the SmartThings issue with colors.
+- [colorTemp]: The min and max mired values are now set in the cluster.
 
 <a href="https://www.buymeacoffee.com/luligugithub">
   <img src="bmc-button.svg" alt="Buy me a coffee" width="80">

package/README.md

@@ -151,7 +151,7 @@ These are the default vules:
   "featureBlackList": [],
   "deviceFeatureBlackList": {},
   "scenesType": "outlet",
-  "scenesPrefix: true,
+  "scenesPrefix": true,
   "postfix": ""
 }
 ```
@@ -180,19 +180,7 @@ If you want to exclude "temperature" and "humidity" for the device "My motion se
 }
 ```
 
-The parameter postfixHostname is deprecated and will be removed in the next release. Use postfix instead if needed.
-By default matterbridge-zigbee2mqtt 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.
+From the release 1.2.14 of Matterbridge you can edit the config file directly in the frontend. I strongly suggest you use the integrated config editor.
 
 You can edit the config file manually if you prefer:
 
@@ -218,11 +206,46 @@ nano matterbridge-zigbee2mqtt.config.json
 
 ## What is supported?
 
-Out of the box, this plugin supports all possible conversion from zigbee2mqtt to Matter 1.1.
+Out of the box, this plugin supports all possible conversion from zigbee2mqtt to Matter 1.4.
+
+It 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.2 specifications, some z2m devices cannot be exposed properly or cannot be exposed at all.
+
+## Scenes in groups and devices
+
+With release 2.5.0 has been added support for scenes in groups and devices.
+
+In the config select what device type you want to use to expose the command that runs the scene: 'light' | 'outlet' | 'switch' | 'mounted_switch'.
+
+Switch is not supported by Alexa. Mounted Switch is not supported by Apple Home.
+
+The virtual device takes the name of the group or device it belongs to, with added the name of scene. If scenesPrefix is disabled, it takes only the name of the scene. Consider that in Matter the node name is 32 characters long. Consider also that each scene name must by unique if scenesPrefix is disabled.
+
+The state of the virtual device is always reverted to off in a few seconds.
+
+It is possibile to disable the feature globally with featureBlackList (add "scenes" to the list) and on a per device/group base with deviceFeatureBlackList (add "scenes" to the list).
+
+## Availability
 
-The latest release also supports all clusters in the multi endpoints devices (e.g. DIY devices or the double channel switches/dimmers).
+If the availability is enabled in zigbee2mqtt settings, it is used to set the corresponding device/group reachable or not.
 
-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.
+[Screenshot](https://github.com/user-attachments/assets/7e0d395f-19e4-4e7f-b263-0cae3df70be4)
+
+## Retain
+
+If the retain option is enabled in zigbee2mqtt settings or device setting, at restart all retained states are updated. I suggest to use this option expecially for battery powered devices.
+
+To enable retain globally, stop zigbee2mqtt, add retain: true to device_options and restart zigbee2mqtt.
+
+```
+device_options:
+  retain: true
+```
+
+To enable retain for a single device set it in the device settings.
+
+[Screenshot](https://github.com/user-attachments/assets/5ae09f2a-6cff-4623-92f4-87f7721ee443)
 
 ## Unsupported devices
 
@@ -251,20 +274,6 @@ 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)
 
-## Scenes in groups and devices
-
-With release 2.5.0 has been added support for scenes in groups and devices.
-
-In the config select what device type you want to use to expose the command that runs the scene: 'light' | 'outlet' | 'switch' | 'mounted_switch'.
-
-Switch is not supported by Alexa. Mounted Switch is not supported by Apple Home.
-
-The virtual device takes the name of the group or device it belongs to, with added the name of scene. If scenesPrefix is disabled, it takes only the name of the scene. Consider that in Matter the node name is 32 characters long.
-
-The state of the virtual device is always reverted to off in a few seconds.
-
-It is possibile to disable the feature globally with featureBlackList and on a per device/group base with deviceFeatureBlackList.
-
 # Known issues
 
 For general controller issues check the Matterbridge Known issues section
@@ -279,6 +288,6 @@ For general controller issues check the Matterbridge Known issues section
 
 ## Alexa
 
-In the plugin config add each switch device to the lightList or outletList. Matterbridge uses a modified switch device type without client cluster that Alexa doesn't recognize.
+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.
 
 ## SmartThings

package/dist/entity.js

@@ -86,6 +86,17 @@ export class ZigbeeEntity extends EventEmitter {
                     return;
                 if (key === 'voltage' && this.isDevice && this.device?.power_source === 'Battery')
                     key = 'battery_voltage';
+                if (key === 'battery' && !('battery_low' in payload) && isValidNumber(value, 0, 100) && this.isDevice && this.device?.power_source === 'Battery') {
+                    if (value < 20) {
+                        this.updateAttributeIfChanged(this.bridgedDevice, undefined, PowerSource.Cluster.id, 'batChargeLevel', PowerSource.BatChargeLevel.Critical);
+                    }
+                    else if (value < 40) {
+                        this.updateAttributeIfChanged(this.bridgedDevice, undefined, PowerSource.Cluster.id, 'batChargeLevel', PowerSource.BatChargeLevel.Warning);
+                    }
+                    else {
+                        this.updateAttributeIfChanged(this.bridgedDevice, undefined, PowerSource.Cluster.id, 'batChargeLevel', PowerSource.BatChargeLevel.Ok);
+                    }
+                }
                 const propertyMap = this.propertyMap.get(key);
                 if (propertyMap) {
                     this.log.debug(`Payload entry ${CYAN}${key}${db} => name: ${CYAN}${propertyMap.name}${db} type: ${CYAN}${propertyMap.type === '' ? 'generic' : propertyMap.type}${db} ` +
@@ -143,7 +154,8 @@ export class ZigbeeEntity extends EventEmitter {
                 }
                 if (key === 'color_temp' && 'color_mode' in payload && payload['color_mode'] === 'color_temp') {
                     this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'colorMode', ColorControl.ColorMode.ColorTemperatureMireds);
-                    this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'colorTemperatureMireds', Math.max(147, Math.min(500, typeof value === 'number' ? value : 0)));
+                    const colorTemp = this.propertyMap.get('color_temp');
+                    this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'colorTemperatureMireds', Math.max(colorTemp?.value_min ?? 147, Math.min(colorTemp?.value_max ?? 500, typeof value === 'number' ? value : 0)));
                 }
                 if (key === 'color' && 'color_mode' in payload && payload['color_mode'] === 'hs') {
                     const { hue, saturation } = value;
@@ -201,15 +213,13 @@ export class ZigbeeEntity extends EventEmitter {
         const hardwareVersionString = this.platform.matterbridge.matterbridgeVersion || 'unknown';
         if (this.isDevice && this.device && this.device.friendly_name === 'Coordinator') {
             this.bridgedDevice.createDefaultBridgedDeviceBasicInformationClusterServer(this.device.friendly_name, this.serial, 0xfff1, 'zigbee2MQTT', 'Coordinator', softwareVersion, softwareVersionString, hardwareVersion, hardwareVersionString);
-            return this.bridgedDevice;
         }
         else if (this.isDevice && this.device) {
             this.bridgedDevice.createDefaultBridgedDeviceBasicInformationClusterServer(this.device.friendly_name, this.serial, 0xfff1, this.device.definition ? this.device.definition.vendor : this.device.manufacturer, this.device.definition ? this.device.definition.model : this.device.model_id, softwareVersion, softwareVersionString, hardwareVersion, hardwareVersionString);
-            return this.bridgedDevice;
         }
-        if (!this.group)
-            throw new Error('No group found');
-        this.bridgedDevice.createDefaultBridgedDeviceBasicInformationClusterServer(this.group.friendly_name, this.serial, 0xfff1, 'zigbee2MQTT', 'Group', softwareVersion, softwareVersionString, hardwareVersion, hardwareVersionString);
+        else if (this.isGroup && this.group) {
+            this.bridgedDevice.createDefaultBridgedDeviceBasicInformationClusterServer(this.group.friendly_name, this.serial, 0xfff1, 'zigbee2MQTT', 'Group', softwareVersion, softwareVersionString, hardwareVersion, hardwareVersionString);
+        }
         return this.bridgedDevice;
     }
     addPowerSource() {
@@ -266,6 +276,12 @@ export class ZigbeeEntity extends EventEmitter {
                     this.bridgedDevice?.triggerEvent(DoorLock.Cluster.id, 'lockOperation', { lockOperationType: DoorLock.LockOperationType.Unlock, operationSource: DoorLock.OperationSource.Manual, userIndex: null, fabricIndex: null, sourceNode: null }, this.log);
             }
         }
+        if (this.bridgedDevice?.hasClusterServer(ColorControl.Cluster.id)) {
+            this.log.info(`Configuring ${this.bridgedDevice?.deviceName} ColorControl cluster`);
+            const colorTemp = this.propertyMap.get('color_temp');
+            this.bridgedDevice?.setAttribute(ColorControl.Cluster.id, 'colorTempPhysicalMinMireds', colorTemp?.value_min ?? 147, this.log);
+            this.bridgedDevice?.setAttribute(ColorControl.Cluster.id, 'colorTempPhysicalMaxMireds', colorTemp?.value_max ?? 500, this.log);
+        }
     }
     updateAttributeIfChanged(deviceEndpoint, childEndpointName, clusterId, attributeName, value, lookup) {
         if (value === undefined)
@@ -976,11 +992,11 @@ export class ZigbeeDevice extends ZigbeeEntity {
         if (mainEndpoint.clusterServersIds.includes(ColorControl.Cluster.id)) {
             if (!names.includes('color_hs') && !names.includes('color_xy')) {
                 zigbeeDevice.log.debug(`Configuring device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} ColorControlCluster cluster with CT: ${names.includes('color_temp')} min: ${zigbeeDevice.propertyMap.get('color_temp')?.value_min} max: ${zigbeeDevice.propertyMap.get('color_temp')?.value_max}`);
-                zigbeeDevice.bridgedDevice.createCtColorControlClusterServer(zigbeeDevice.propertyMap.get('color_temp')?.value_max, zigbeeDevice.propertyMap.get('color_temp')?.value_min, zigbeeDevice.propertyMap.get('color_temp')?.value_max);
+                zigbeeDevice.bridgedDevice.createCtColorControlClusterServer();
             }
             else {
                 zigbeeDevice.log.debug(`Configuring device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} ColorControlCluster cluster with HS: ${names.includes('color_hs')} XY: ${names.includes('color_xy')} CT: ${names.includes('color_temp')} min: ${zigbeeDevice.propertyMap.get('color_temp')?.value_min} max: ${zigbeeDevice.propertyMap.get('color_temp')?.value_max}`);
-                zigbeeDevice.bridgedDevice.createDefaultColorControlClusterServer(undefined, undefined, undefined, undefined, zigbeeDevice.propertyMap.get('color_temp')?.value_max, zigbeeDevice.propertyMap.get('color_temp')?.value_min, zigbeeDevice.propertyMap.get('color_temp')?.value_max);
+                zigbeeDevice.bridgedDevice.createDefaultColorControlClusterServer();
             }
             mainEndpoint.clusterServersIds.splice(mainEndpoint.clusterServersIds.indexOf(ColorControl.Cluster.id), 1);
         }

package/dist/platform.js

@@ -34,7 +34,8 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
     z2mBridgeInfo;
     z2mBridgeDevices;
     z2mBridgeGroups;
-    z2mDeviceAvailability = new Map();
+    z2mEntityAvailability = new Map();
+    z2mEntityPayload = new Map();
     availabilityTimer;
     constructor(matterbridge, log, config) {
         super(matterbridge, log, config);
@@ -194,11 +195,14 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
             }
         });
         this.z2m.on('availability', (device, available) => {
-            this.z2mDeviceAvailability.set(device, available);
+            this.z2mEntityAvailability.set(device, available);
             if (available)
-                this.log.info(`zigbee2MQTT device ${device} is ${available ? 'online' : 'offline'}`);
+                this.log.info(`zigbee2MQTT entity ${device} is ${available ? 'online' : 'offline'}`);
             else
-                this.log.warn(`zigbee2MQTT device ${device} is ${available ? 'online' : 'offline'}`);
+                this.log.warn(`zigbee2MQTT entity ${device} is ${available ? 'online' : 'offline'}`);
+        });
+        this.z2m.on('message', (device, payload) => {
+            this.z2mEntityPayload.set(device, payload);
         });
         this.z2m.on('permit_join', async (device, time, status) => {
             this.log.info(`zigbee2MQTT sent permit_join device: ${device} time: ${time} status: ${status}`);
@@ -334,10 +338,6 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
         await super.onConfigure();
         this.log.info(`Requesting update for ${this.zigbeeEntities.length} zigbee entities.`);
         for (const bridgedEntity of this.zigbeeEntities) {
-            if (bridgedEntity.isDevice && bridgedEntity.device)
-                await this.requestDeviceUpdate(bridgedEntity.device);
-            if (bridgedEntity.isGroup && bridgedEntity.group)
-                await this.requestGroupUpdate(bridgedEntity.group);
             await bridgedEntity.configure();
             if (bridgedEntity.isRouter && bridgedEntity.bridgedDevice) {
                 this.log.info(`Configuring router ${bridgedEntity.bridgedDevice?.deviceName}.`);
@@ -352,15 +352,24 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
                         bridgedEntity.bridgedDevice?.triggerEvent(DoorLock.Cluster.id, 'lockOperation', { lockOperationType: DoorLock.LockOperationType.Lock, operationSource: DoorLock.OperationSource.Manual, userIndex: null, fabricIndex: null, sourceNode: null }, this.log);
                 }
             }
+            if (bridgedEntity.isDevice && bridgedEntity.device)
+                await this.requestDeviceUpdate(bridgedEntity.device);
+            if (bridgedEntity.isGroup && bridgedEntity.group)
+                await this.requestGroupUpdate(bridgedEntity.group);
         }
         this.availabilityTimer = setTimeout(() => {
-            for (const [device, available] of this.z2mDeviceAvailability) {
+            this.log.info(`Setting availability for ${this.z2mEntityAvailability.size} entities`);
+            for (const [entity, available] of this.z2mEntityAvailability) {
                 if (available)
-                    this.z2m.emit('ONLINE-' + device);
+                    this.z2m.emit('ONLINE-' + entity);
                 else
-                    this.z2m.emit('OFFLINE-' + device);
+                    this.z2m.emit('OFFLINE-' + entity);
+            }
+            this.log.info(`Setting retained values for ${this.z2mEntityPayload.size} entities`);
+            for (const [entity, payload] of this.z2mEntityPayload) {
+                this.z2m.emit('MESSAGE-' + entity, payload);
             }
-        }, 60 * 1000);
+        }, 10 * 1000).unref();
         if (this.config.injectPayloads) {
             this.injectTimer = setInterval(() => {
                 const data = this.z2m.readConfig(path.join(this.matterbridge.matterbridgeDirectory, this.config.injectPayloads));
@@ -372,6 +381,18 @@ export class ZigbeePlatform extends MatterbridgeDynamicPlatform {
         }
         this.log.info(`Configured zigbee2mqtt dynamic platform v${this.version}`);
     }
+    async onChangeLoggerLevel(logLevel) {
+        this.log.info(`Configuring zigbee2mqtt platform logger level to ${CYAN}${logLevel}${nf}`);
+        this.log.logLevel = logLevel;
+        this.z2m.setLogLevel(logLevel);
+        for (const bridgedDevice of this.bridgedDevices) {
+            bridgedDevice.log.logLevel = logLevel;
+        }
+        for (const entity of this.zigbeeEntities) {
+            entity.log.logLevel = logLevel;
+        }
+        this.log.debug('Changed logger level to ' + logLevel);
+    }
     async onShutdown(reason) {
         await super.onShutdown(reason);
         this.z2m.removeAllListeners();

package/dist/zigbee2mqtt.js

@@ -65,6 +65,9 @@ export class Zigbee2MQTT extends EventEmitter {
     setLogDebug(logDebug) {
         this.log.logLevel = logDebug ? "debug" : "info";
     }
+    setLogLevel(logLevel) {
+        this.log.logLevel = logLevel;
+    }
     async setDataPath(dataPath) {
         try {
             await mkdir(dataPath, { recursive: true });
@@ -80,6 +83,13 @@ export class Zigbee2MQTT extends EventEmitter {
                 this.log.error('Error creating data directory:', error);
             }
         }
+        try {
+            const filePath = path.join(this.mqttDataPath, 'bridge-payloads.txt');
+            fs.unlinkSync(filePath);
+        }
+        catch (error) {
+            this.log.debug(`Error deleting bridge-payloads.txt: ${error}`);
+        }
     }
     getUrl() {
         return 'mqtt://' + this.mqttHost + ':' + this.mqttPort.toString();
@@ -613,6 +623,7 @@ export class Zigbee2MQTT extends EventEmitter {
         else if (service === 'set') {
         }
         else if (service === undefined) {
+            this.emit('message', entity, data);
             this.emit('MESSAGE-' + entity, data);
         }
         else {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "matterbridge-zigbee2mqtt",
-  "version": "2.5.0-dev.2",
+  "version": "2.5.0-dev.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "matterbridge-zigbee2mqtt",
-      "version": "2.5.0-dev.2",
+      "version": "2.5.0-dev.4",
       "license": "Apache-2.0",
       "dependencies": {
         "moment": "2.30.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matterbridge-zigbee2mqtt",
-  "version": "2.5.0-dev.2",
+  "version": "2.5.0-dev.4",
   "description": "Matterbridge zigbee2mqtt plugin",
   "author": "https://github.com/Luligu",
   "license": "Apache-2.0",