matterbridge-zigbee2mqtt 2.3.1-dev.2 → 2.3.2

package/dist/entity.js

@@ -1,9 +1,37 @@
+/**
+ * This file contains the classes ZigbeeEntity, ZigbeeDevice and ZigbeeGroup.
+ *
+ * @file entity.ts
+ * @author Luca Liguori
+ * @date 2023-12-29
+ * @version 3.1.0
+ *
+ * Copyright 2023, 2024, 2025 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License. *
+ */
 import { MatterbridgeDevice, airQualitySensor, colorTemperatureSwitch, dimmableSwitch, onOffSwitch, OnOff, LevelControl, ColorControl, ColorControlCluster, TemperatureMeasurement, BooleanState, RelativeHumidityMeasurement, PressureMeasurement, OccupancySensing, IlluminanceMeasurement, PowerSource, ClusterId, WindowCovering, DoorLock, BridgedDeviceBasicInformation, ThermostatCluster, Thermostat, getClusterNameById, powerSource, bridgedNode, AirQuality, TotalVolatileOrganicCompoundsConcentrationMeasurement, CarbonDioxideConcentrationMeasurement, CarbonMonoxideConcentrationMeasurement, FormaldehydeConcentrationMeasurement, Pm1ConcentrationMeasurement, Pm25ConcentrationMeasurement, Pm10ConcentrationMeasurement, electricalSensor, ElectricalEnergyMeasurement, ElectricalPowerMeasurement, onOffLight, dimmableLight, colorTemperatureLight, onOffOutlet, SwitchesTag, NumberTag, coverDevice, thermostatDevice, MatterbridgeEndpoint, dimmableOutlet, doorLockDevice, occupancySensor, lightSensor, contactSensor, temperatureSensor, humiditySensor, pressureSensor, genericSwitch, OnOffCluster, LevelControlCluster, WindowCoveringCluster, DoorLockCluster, } from 'matterbridge';
 import { AnsiLogger, gn, dn, ign, idn, rs, db, debugStringify, hk, zb, or, nf, CYAN, er, YELLOW } from 'matterbridge/logger';
 import { deepCopy, deepEqual, isValidNumber } from 'matterbridge/utils';
 import * as color from 'matterbridge/utils';
 import EventEmitter from 'events';
 import { hostname } from 'os';
+/**
+ * Represents a Zigbee entity: a group or a device.
+ *
+ * @class
+ * @extends {EventEmitter}
+ */
 export class ZigbeeEntity extends EventEmitter {
     log;
     serial = '';
@@ -23,6 +51,7 @@ export class ZigbeeEntity extends EventEmitter {
     ignoreFeatures = [];
     transition = false;
     propertyMap = new Map();
+    // We save the tag list and device types and cluster servers and clients to avoid multiple lookups
     mutableDevice = new Map();
     colorTimeout = undefined;
     thermostatTimeout = undefined;
@@ -30,6 +59,12 @@ export class ZigbeeEntity extends EventEmitter {
     hasEndpoints = false;
     isRouter = false;
     noUpdate = false;
+    /**
+     * Creates an instance of ZigbeeEntity.
+     *
+     * @param {ZigbeePlatform} platform - The Zigbee platform instance.
+     * @param {BridgeDevice | BridgeGroup} entity - The bridge device or group instance received from zigbee2mqtt.
+     */
     constructor(platform, entity) {
         super();
         this.platform = platform;
@@ -47,22 +82,26 @@ export class ZigbeeEntity extends EventEmitter {
             this.en = gn;
             this.ien = ign;
         }
-        this.log = new AnsiLogger({ logName: this.entityName, logTimestampFormat: 4, logLevel: platform.debugEnabled ? "debug" : "info" });
+        this.log = new AnsiLogger({ logName: this.entityName, logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: platform.debugEnabled ? "debug" /* LogLevel.DEBUG */ : "info" /* LogLevel.INFO */ });
         this.log.debug(`Created MatterEntity: ${this.entityName}`);
         this.platform.z2m.on('MESSAGE-' + this.entityName, (payload) => {
+            // Check if the message is a duplicate that can be ingored cause only linkquality and last_seen have changed (action is always passed)
             const now = Date.now();
             if (now - this.lastSeen < 1000 * 60 && deepEqual(this.lastPayload, payload, ['linkquality', 'last_seen', ...this.ignoreFeatures]) && !Object.prototype.hasOwnProperty.call(this.lastPayload, 'action')) {
                 this.log.debug(`Skipping not changed ${platform.z2mDevicesRegistered ? 'MQTT message' : 'State update'} for accessory ${this.entityName}`);
                 return;
             }
             this.lastSeen = Date.now();
+            // Check and deep copy the payload
             if (deepEqual(this.lastPayload, payload, this.ignoreFeatures))
                 return;
             this.lastPayload = deepCopy(payload);
             if (Object.prototype.hasOwnProperty.call(this.lastPayload, 'action'))
                 delete this.lastPayload.action;
+            // Remove each key in ignoreFeatures from the payload copy
             for (const key of this.ignoreFeatures) {
                 if (Object.prototype.hasOwnProperty.call(payload, key)) {
+                    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
                     delete payload[key];
                     this.log.debug(`Removed key ${CYAN}${key}${db} from payload`);
                 }
@@ -76,19 +115,24 @@ export class ZigbeeEntity extends EventEmitter {
                 return;
             }
             this.log.info(`${db}${platform.z2mDevicesRegistered ? 'MQTT message' : 'State update'} for device ${this.ien}${this.entityName}${rs}${db} payload: ${debugStringify(payload)}`);
+            // Parse the payload and update the accessory
             Object.entries(payload).forEach(([key, value]) => {
+                // Skip null and undefined values
                 if (value === undefined || value === null)
                     return;
                 if (this.bridgedDevice === undefined || this.noUpdate)
                     return;
+                // Modify voltage to battery_voltage
                 if (key === 'voltage' && this.isDevice && this.device?.power_source === 'Battery')
                     key = 'battery_voltage';
+                // Modify illuminance and illuminance_lux
                 if (key === 'illuminance' && this.isDevice && this.device && this.device.definition && ['RTCGQ14LM'].includes(this.device.definition.model)) {
                     key = 'illuminance_lux';
                 }
                 if (key === 'illuminance' && typeof value === 'number' && this.isDevice && this.device && this.device.definition && ['ZG-204ZL', 'ZG-205Z/A'].includes(this.device.definition.model)) {
                     value = value * 10;
                 }
+                // Lookup the property in the propertyMap and ZigbeeToMatter table
                 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} ` +
@@ -108,9 +152,11 @@ export class ZigbeeEntity extends EventEmitter {
                 }
                 else
                     this.log.debug(`*Payload entry ${CYAN}${key}${db} not found in propertyMap`);
+                // Switch actions on the endpoints
                 if (key === 'action' && value !== '') {
                     const propertyMap = this.propertyMap.get(('action_' + value));
                     if (propertyMap) {
+                        // this.log.debug(`Payload entry ${CYAN}${value}${db} => name: ${CYAN}${propertyMap.name}${db} endpoint: ${CYAN}${propertyMap.endpoint}${db} action: ${CYAN}${propertyMap.action}${db}`);
                         const child = this.bridgedDevice.getChildEndpointByName(propertyMap.endpoint);
                         if (child && child.number)
                             this.bridgedDevice.triggerSwitchEvent(propertyMap.action, this.log, child);
@@ -118,6 +164,9 @@ export class ZigbeeEntity extends EventEmitter {
                     else
                         this.log.debug(`*Payload entry ${CYAN}${('action_' + value)}${db} not found in propertyMap`);
                 }
+                // WindowCovering
+                // Zigbee2MQTT cover: 0 = open, 100 = closed
+                // Matter WindowCovering: 0 = open 10000 = closed
                 if (key === 'position' && this.isDevice && isValidNumber(value, 0, 100)) {
                     this.updateAttributeIfChanged(this.bridgedDevice, undefined, WindowCovering.Cluster.id, 'currentPositionLiftPercent100ths', value * 100);
                 }
@@ -138,19 +187,34 @@ export class ZigbeeEntity extends EventEmitter {
                         this.updateAttributeIfChanged(this.bridgedDevice, undefined, WindowCovering.Cluster.id, 'targetPositionLiftPercent100ths', position);
                     }
                 }
+                // ColorControl colorTemperatureMired and colorMode
                 if (key === 'color_temp' && 'color_mode' in payload && payload['color_mode'] === 'color_temp') {
-                    this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'colorTemperatureMireds', Math.max(147, Math.min(500, typeof value === 'number' ? value : 0)));
                     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)));
+                }
+                // ColorControl currentHue, currentSaturation and colorMode
+                if (key === 'color' && 'color_mode' in payload && payload['color_mode'] === 'hs') {
+                    const { hue, saturation } = value;
+                    this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'colorMode', ColorControl.ColorMode.CurrentHueAndCurrentSaturation);
+                    this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'currentHue', Math.round((hue / 360) * 254));
+                    this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'currentSaturation', Math.round((saturation / 100) * 254));
                 }
+                // ColorControl currentX, currentY and colorMode
                 if (key === 'color' && 'color_mode' in payload && payload['color_mode'] === 'xy') {
+                    /* not supported by Apple Home so we convert xy to hue and saturation
+                    const { x, y } = value as { x: number; y: number };
+                    this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'colorMode', ColorControl.ColorMode.CurrentXAndCurrentY);
+                    this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'currentX', Math.max(Math.min(Math.round(x * 65536), 65279), 0));
+                    this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'currentY', Math.max(Math.min(Math.round(y * 65536), 65279), 0));
+                    */
                     const { x, y } = value;
                     const hsl = color.xyToHsl(x, y);
                     const rgb = color.xyColorToRgbColor(x, y);
                     this.log.debug(`ColorControl xyToHsl ${CYAN}${x}${db} ${CYAN}${y}${db} => h ${CYAN}${hsl.h}${db} s ${CYAN}${hsl.s}${db} l ${CYAN}${hsl.l}${db}`);
                     this.log.debug(`ColorControl xyToRgb ${CYAN}${x}${db} ${CYAN}${y}${db} => r ${CYAN}${rgb.r}${db} g ${CYAN}${rgb.g}${db} b ${CYAN}${rgb.b}${db}`);
+                    this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'colorMode', ColorControl.ColorMode.CurrentHueAndCurrentSaturation);
                     this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'currentHue', Math.round((hsl.h / 360) * 254));
                     this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'currentSaturation', Math.round((hsl.s / 100) * 254));
-                    this.updateAttributeIfChanged(this.bridgedDevice, undefined, ColorControl.Cluster.id, 'colorMode', ColorControl.ColorMode.CurrentHueAndCurrentSaturation);
                 }
             });
         });
@@ -169,6 +233,13 @@ export class ZigbeeEntity extends EventEmitter {
             }
         });
     }
+    /**
+     * Destroys the ZigbeeEntity instance by clearing any active timeouts.
+     *
+     * @remarks
+     * This method is used to clean up the ZigbeeEntity instance by clearing any active timeouts for color and thermostat operations.
+     * It ensures that no further actions are taken on these timeouts after the entity is destroyed.
+     */
     destroy() {
         if (this.colorTimeout)
             clearTimeout(this.colorTimeout);
@@ -177,6 +248,22 @@ export class ZigbeeEntity extends EventEmitter {
             clearTimeout(this.thermostatTimeout);
         this.thermostatTimeout = undefined;
     }
+    /**
+     * Creates a mutable device with the specified definition and includes the specified server list.
+     *
+     * @param {DeviceTypeDefinition | AtLeastOne<DeviceTypeDefinition>} definition - The device type definition.
+     * @param {ClusterId[]} [includeServerList=[]] - The list of server clusters to include.
+     * @param {EndpointOptions} [options] - Optional endpoint options.
+     * @param {boolean} [debug] - Optional debug flag.
+     * @returns {MatterbridgeDevice} The created mutable device.
+     *
+     * @remarks
+     * This method creates a mutable device based on the provided definition. It adds the specified server clusters
+     * to the device and configures the device with basic information and power source clusters. If the device is a
+     * coordinator, it sets up the basic information cluster with coordinator-specific details. If the device is a
+     * group, it sets up the basic information cluster with group-specific details. The method also configures the
+     * power source cluster based on the device's power source.
+     */
     async createMutableDevice(definition, options, debug) {
         if (this.platform.matterbridge.edge === true) {
             this.bridgedDevice = (await MatterbridgeEndpoint.loadInstance(definition, options, debug));
@@ -189,6 +276,7 @@ export class ZigbeeEntity extends EventEmitter {
     getBridgedDeviceBasicInformation() {
         if (!this.bridgedDevice)
             throw new Error('No bridged device');
+        // Add BridgedDeviceBasicInformation cluster and device type
         const softwareVersion = parseInt(this.platform.z2mBridgeInfo?.version || '1');
         const softwareVersionString = `${this.platform.z2mBridgeInfo?.version} (commit ${this.platform.z2mBridgeInfo?.commit})`;
         const hardwareVersion = parseInt(this.platform.matterbridge.matterbridgeVersion || '1');
@@ -206,6 +294,7 @@ export class ZigbeeEntity extends EventEmitter {
     addBridgedDeviceBasicInformation() {
         if (!this.bridgedDevice)
             throw new Error('No bridged device');
+        // Add BridgedDeviceBasicInformation cluster and device type
         this.bridgedDevice.addDeviceType(bridgedNode);
         this.bridgedDevice.addClusterServer(this.getBridgedDeviceBasicInformation());
         return this.bridgedDevice;
@@ -226,13 +315,26 @@ export class ZigbeeEntity extends EventEmitter {
     addPowerSource() {
         if (!this.bridgedDevice)
             throw new Error('No bridged device');
+        // Add PowerSource device type and cluster
         this.bridgedDevice.addDeviceType(powerSource);
         this.bridgedDevice.addClusterServer(this.getPowerSource());
         return this.bridgedDevice;
     }
+    /**
+     * Verifies that all required server clusters are present on the main endpoint and child endpoints.
+     *
+     * @param {MatterbridgeDevice} endpoint - The device endpoint to verify.
+     * @returns {boolean} True if all required server clusters are present, false otherwise.
+     *
+     * @remarks
+     * This method checks if all required server clusters are present on the main endpoint and its child endpoints.
+     * It logs an error message if any required server cluster is missing and returns false. If all required server
+     * clusters are present, it returns true.
+     */
     verifyMutableDevice(endpoint) {
         if (!endpoint)
             return false;
+        // Verify that all required server clusters are present in the main endpoint and in the child endpoints
         for (const deviceType of endpoint.getDeviceTypes()) {
             for (const clusterId of deviceType.requiredServerClusters) {
                 if (!endpoint.getClusterServerById(clusterId)) {
@@ -241,6 +343,7 @@ export class ZigbeeEntity extends EventEmitter {
                 }
             }
         }
+        // Verify that all required server clusters are present in the child endpoints
         for (const childEndpoint of endpoint.getChildEndpoints()) {
             for (const deviceType of childEndpoint.getDeviceTypes()) {
                 for (const clusterId of deviceType.requiredServerClusters) {
@@ -253,6 +356,17 @@ export class ZigbeeEntity extends EventEmitter {
         }
         return true;
     }
+    /**
+     * Configures the device by setting up the WindowCovering and DoorLock clusters if they are present.
+     *
+     * @returns {Promise<void>} A promise that resolves when the configuration is complete.
+     *
+     * @remarks
+     * This method configures the device by checking for the presence of the WindowCovering and DoorLock clusters.
+     * If the WindowCovering cluster is present, it sets the target as the current position and stops any ongoing
+     * movement. If the DoorLock cluster is present, it retrieves the lock state and triggers the appropriate lock
+     * operation event based on the current state.
+     */
     async configure() {
         if (this.bridgedDevice?.getClusterServerById(WindowCovering.Cluster.id)) {
             this.log.info(`Configuring ${this.bridgedDevice?.deviceName} WindowCovering cluster`);
@@ -269,6 +383,22 @@ export class ZigbeeEntity extends EventEmitter {
             }
         }
     }
+    /**
+     * Updates the attribute of a cluster on a device endpoint if the value has changed.
+     *
+     * @param {Endpoint} deviceEndpoint - The device endpoint to update.
+     * @param {string | undefined} childEndpointName - The name of the child endpoint, if any.
+     * @param {number} clusterId - The ID of the cluster to update.
+     * @param {string} attributeName - The name of the attribute to update.
+     * @param {PayloadValue} value - The new value of the attribute.
+     * @param {string[]} [lookup] - Optional lookup array for converting string values to indices.
+     *
+     * @remarks
+     * This method checks if the specified attribute of a cluster on a device endpoint has changed. If the attribute
+     * has changed, it updates the attribute with the new value. If a lookup array is provided, it converts string
+     * values to their corresponding indices in the lookup array. The method logs the update process and handles any
+     * errors that occur during the update.
+     */
     updateAttributeIfChanged(deviceEndpoint, childEndpointName, clusterId, attributeName, value, lookup) {
         if (childEndpointName && childEndpointName !== '') {
             deviceEndpoint = this.bridgedDevice?.getChildEndpointByName(childEndpointName) ?? deviceEndpoint;
@@ -307,6 +437,18 @@ export class ZigbeeEntity extends EventEmitter {
             this.log.error(`Error setting attribute ${hk}${getClusterNameById(ClusterId(clusterId))}${er}.${hk}${attributeName}${er} to ${value}: ${error}`);
         }
     }
+    /**
+     * Publishes a command to the specified entity with the given payload.
+     *
+     * @param {string} command - The command to execute.
+     * @param {string} entityName - The name of the entity to publish the command to.
+     * @param {Payload} payload - The payload of the command.
+     *
+     * @remarks
+     * This method logs the execution of the command and publishes the command to the specified entity.
+     * If the entity name starts with 'bridge/request', it publishes the payload without a 'set' suffix.
+     * Otherwise, it publishes the payload with a 'set' suffix.
+     */
     publishCommand(command, entityName, payload) {
         this.log.debug(`executeCommand ${command} called for ${this.ien}${entityName}${rs}${db} payload: ${debugStringify(payload)}`);
         if (entityName.startsWith('bridge/request')) {
@@ -316,7 +458,16 @@ export class ZigbeeEntity extends EventEmitter {
             this.platform.publish(entityName, 'set', JSON.stringify(payload));
         }
     }
+    /**
+     * Logs the property map of the Zigbee entity.
+     *
+     * @remarks
+     * This method iterates over the property map of the Zigbee entity and logs each property's details,
+     * including its name, type, values, minimum and maximum values, unit, and endpoint.
+     */
+    // zigbeeDevice.propertyMap.set(property, { name, type, endpoint, category, description, label, unit, value_min, value_max, values: value });
     logPropertyMap() {
+        // Log properties
         this.propertyMap.forEach((value, key) => {
             this.log.debug(`Property ${CYAN}${key}${db} name ${CYAN}${value.name}${db} type ${CYAN}${value.type === '' ? 'generic' : value.type}${db} endpoint ${CYAN}${value.endpoint === '' ? 'main' : value.endpoint}${db} ` +
                 `category ${CYAN}${value.category}${db} description ${CYAN}${value.description}${db} label ${CYAN}${value.label}${db} unit ${CYAN}${value.unit}${db} ` +
@@ -324,10 +475,33 @@ export class ZigbeeEntity extends EventEmitter {
         });
     }
 }
+/**
+ * Represents a Zigbee group entity.
+ *
+ * @class
+ * @extends {ZigbeeEntity}
+ */
 export class ZigbeeGroup extends ZigbeeEntity {
+    /**
+     * Creates an instance of ZigbeeGroup.
+     *
+     * @param {ZigbeePlatform} platform - The Zigbee platform instance.
+     * @param {BridgeGroup} group - The bridge group instance.
+     */
     constructor(platform, group) {
         super(platform, group);
     }
+    /**
+     * Creates a new ZigbeeGroup instance.
+     *
+     * @param {ZigbeePlatform} platform - The Zigbee platform instance.
+     * @param {BridgeGroup} group - The bridge group instance.
+     * @returns {Promise<ZigbeeGroup>} A promise that resolves to the created ZigbeeGroup instance.
+     *
+     * @remarks
+     * This method initializes a new ZigbeeGroup instance, sets up its properties, and configures the device
+     * based on the group members. It also adds command handlers for the group.
+     */
     static async create(platform, group) {
         const zigbeeGroup = new ZigbeeGroup(platform, group);
         if (zigbeeGroup.platform.postfixHostname) {
@@ -347,19 +521,23 @@ export class ZigbeeGroup extends ZigbeeEntity {
         let isCover = false;
         let isThermostat = false;
         if (group.members.length === 0) {
+            // Create a virtual device for the empty group to use in automations
             zigbeeGroup.log.debug(`Group: ${gn}${group.friendly_name}${rs}${db} is a ${CYAN}virtual${db} group`);
-            zigbeeGroup.bridgedDevice = await zigbeeGroup.createMutableDevice([onOffSwitch], { uniqueStorageKey: group.friendly_name }, zigbeeGroup.log.logLevel === "debug");
+            zigbeeGroup.bridgedDevice = await zigbeeGroup.createMutableDevice([onOffSwitch], { uniqueStorageKey: group.friendly_name }, zigbeeGroup.log.logLevel === "debug" /* LogLevel.DEBUG */);
             isSwitch = true;
             zigbeeGroup.propertyMap.set('state', { name: 'state', type: 'switch', endpoint: '' });
         }
         else {
+            // Create a switch or light or outlet device for the group
             group.members.forEach((member) => {
+                // const device = zigbeeGroup.platform.z2m.getDevice(member.ieee_address);
                 const device = zigbeeGroup.platform.z2mBridgeDevices?.find((device) => device.ieee_address === member.ieee_address);
                 if (!device)
                     return;
                 zigbeeGroup.log.debug(`Group ${gn}${group.friendly_name}${db}: member device ${dn}${device.friendly_name}${db}`);
                 device.definition?.exposes.forEach((expose) => {
                     if (expose.features) {
+                        // Specific features with type
                         expose.features?.forEach((feature) => {
                             if (expose.type === 'lock' && feature.name === 'state' && feature.property === 'child_lock') {
                                 expose.type = 'child_lock';
@@ -389,6 +567,7 @@ export class ZigbeeGroup extends ZigbeeEntity {
                         });
                     }
                     else {
+                        // Generic features without type
                         zigbeeGroup.log.debug(`- generic type ${CYAN}${expose.type}${db} expose name ${CYAN}${expose.name}${db} property ${CYAN}${expose.property}${db}`);
                     }
                 });
@@ -434,14 +613,17 @@ export class ZigbeeGroup extends ZigbeeEntity {
             }
             if (!deviceType)
                 return zigbeeGroup;
-            zigbeeGroup.bridgedDevice = await zigbeeGroup.createMutableDevice([deviceType], { uniqueStorageKey: group.friendly_name }, zigbeeGroup.log.logLevel === "debug");
+            zigbeeGroup.bridgedDevice = await zigbeeGroup.createMutableDevice([deviceType], { uniqueStorageKey: group.friendly_name }, zigbeeGroup.log.logLevel === "debug" /* LogLevel.DEBUG */);
         }
         zigbeeGroup.addBridgedDeviceBasicInformation();
         zigbeeGroup.addPowerSource();
         zigbeeGroup.bridgedDevice.addRequiredClusterServers(zigbeeGroup.bridgedDevice);
+        // Verify the device
         if (!zigbeeGroup.bridgedDevice || !zigbeeGroup.verifyMutableDevice(zigbeeGroup.bridgedDevice))
             return zigbeeGroup;
+        // Log properties
         zigbeeGroup.logPropertyMap();
+        // Add command handlers
         if (isSwitch || isLight) {
             if (isSwitch && !isLight)
                 await zigbeeGroup.bridgedDevice.addFixedLabel('type', 'switch');
@@ -449,6 +631,7 @@ export class ZigbeeGroup extends ZigbeeEntity {
                 await zigbeeGroup.bridgedDevice.addFixedLabel('type', 'light');
             zigbeeGroup.bridgedDevice.addCommandHandler('identify', async ({ request: { identifyTime } }) => {
                 zigbeeGroup.log.warn(`Command identify called for ${zigbeeGroup.ien}${group.friendly_name}${rs}${db} identifyTime:${identifyTime}`);
+                // logEndpoint(zigbeeGroup.bridgedDevice!);
             });
             zigbeeGroup.bridgedDevice.addCommandHandler('on', async () => {
                 zigbeeGroup.log.debug(`Command on called for ${zigbeeGroup.ien}${group.friendly_name}${rs}${db}`);
@@ -540,6 +723,7 @@ export class ZigbeeGroup extends ZigbeeEntity {
             zigbeeGroup.bridgedDevice.subscribeAttribute(ThermostatCluster.id, 'systemMode', (newValue, oldValue) => {
                 zigbeeGroup.bridgedDevice?.log.info(`Thermostat systemMode changed from ${oldValue} to ${newValue}`);
                 if (oldValue !== newValue) {
+                    // Thermostat.SystemMode.Heat && newValue === Thermostat.SystemMode.Off
                     zigbeeGroup.bridgedDevice?.log.info(`Setting thermostat systemMode to ${newValue}`);
                     if (newValue === Thermostat.SystemMode.Off) {
                         zigbeeGroup.publishCommand('SystemMode', group.friendly_name, { system_mode: 'off' });
@@ -580,6 +764,7 @@ export class ZigbeeGroup extends ZigbeeEntity {
         return zigbeeGroup;
     }
 }
+// prettier-ignore
 export const z2ms = [
     { type: 'switch', name: 'state', property: 'state', deviceType: onOffSwitch, cluster: OnOff.Cluster.id, attribute: 'onOff', converter: (value) => { return value === 'ON' ? true : false; } },
     { type: 'switch', name: 'brightness', property: 'brightness', deviceType: dimmableSwitch, cluster: LevelControl.Cluster.id, attribute: 'currentLevel', converter: (value) => { return Math.max(1, Math.min(254, value)); } },
@@ -639,19 +824,43 @@ export const z2ms = [
     { type: '', name: 'voltage', property: 'voltage', deviceType: electricalSensor, cluster: ElectricalPowerMeasurement.Cluster.id, attribute: 'voltage', converter: (value) => { return value * 1000; } },
     { type: '', name: 'current', property: 'current', deviceType: electricalSensor, cluster: ElectricalPowerMeasurement.Cluster.id, attribute: 'activeCurrent', converter: (value) => { return value * 1000; } },
 ];
+/**
+ * Represents a Zigbee device entity.
+ *
+ * @class
+ * @extends {ZigbeeEntity}
+ */
 export class ZigbeeDevice extends ZigbeeEntity {
+    /**
+     * Represents a Zigbee device entity.
+     *
+     * @class
+     * @extends {ZigbeeEntity}
+     */
     constructor(platform, device) {
         super(platform, device);
     }
+    /**
+     * Creates a new ZigbeeDevice instance.
+     *
+     * @param {ZigbeePlatform} platform - The Zigbee platform instance.
+     * @param {BridgeDevice} device - The bridge device instance.
+     * @returns {Promise<ZigbeeDevice>} A promise that resolves to the created ZigbeeDevice instance.
+     *
+     * @remarks
+     * This method initializes a new ZigbeeDevice instance, sets up its properties, and configures the device
+     * based on the device definition and options. It also adds command handlers for the device.
+     */
     static async create(platform, device) {
         const zigbeeDevice = new ZigbeeDevice(platform, device);
         zigbeeDevice.serial = `${device.ieee_address}`;
         if (zigbeeDevice.platform.postfixHostname) {
             zigbeeDevice.serial = `${zigbeeDevice.serial}_${hostname}`.slice(0, 32);
         }
+        // Set Coordinator and dedicated routers
         if (device.friendly_name === 'Coordinator' || (device.model_id === 'ti.router' && device.manufacturer === 'TexasInstruments') || (device.model_id.startsWith('SLZB-') && device.manufacturer === 'SMLIGHT')) {
             zigbeeDevice.isRouter = true;
-            zigbeeDevice.bridgedDevice = await zigbeeDevice.createMutableDevice([doorLockDevice], { uniqueStorageKey: device.friendly_name }, zigbeeDevice.log.logLevel === "debug");
+            zigbeeDevice.bridgedDevice = await zigbeeDevice.createMutableDevice([doorLockDevice], { uniqueStorageKey: device.friendly_name }, zigbeeDevice.log.logLevel === "debug" /* LogLevel.DEBUG */);
             zigbeeDevice.addBridgedDeviceBasicInformation();
             zigbeeDevice.addPowerSource();
             zigbeeDevice.bridgedDevice.addRequiredClusterServers(zigbeeDevice.bridgedDevice);
@@ -669,6 +878,7 @@ export class ZigbeeDevice extends ZigbeeEntity {
             });
             return zigbeeDevice;
         }
+        // Get types and properties
         const types = [];
         const endpoints = [];
         const names = [];
@@ -682,6 +892,7 @@ export class ZigbeeDevice extends ZigbeeEntity {
         const values = [];
         device.definition?.exposes.forEach((expose) => {
             if (expose.features) {
+                // Specific features with type
                 expose.features?.forEach((feature) => {
                     if (expose.type === 'lock' && feature.name === 'state' && feature.property === 'child_lock')
                         feature.name = 'child_lock';
@@ -699,10 +910,17 @@ export class ZigbeeDevice extends ZigbeeEntity {
                 });
             }
             else {
+                // Generic features without type
+                // Change voltage to battery_voltage for battery powered devices
                 if (device.power_source === 'Battery' && expose.name === 'voltage')
                     expose.name = 'battery_voltage';
                 if (device.power_source === 'Battery' && expose.property === 'voltage')
                     expose.property = 'battery_voltage';
+                // Fix illuminance and illuminance_lux for light sensors:
+                // illuminance is raw value (use like it is)
+                // illuminance_lux is in lux (convert with log10)
+                // illuminance has description "Raw measured illuminance"
+                // illuminance_lux has description "Measured illuminance in lux"
                 if (expose.description === 'Raw measured illuminance') {
                     expose.name = 'illuminance';
                     expose.property = 'illuminance';
@@ -763,6 +981,16 @@ export class ZigbeeDevice extends ZigbeeEntity {
             zigbeeDevice.ignoreFeatures = [...zigbeeDevice.ignoreFeatures, ...platform.featureBlackList];
         if (platform.deviceFeatureBlackList[device.friendly_name])
             zigbeeDevice.ignoreFeatures = [...zigbeeDevice.ignoreFeatures, ...platform.deviceFeatureBlackList[device.friendly_name]];
+        /*
+        zigbeeDevice.log.debug(`Device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} - types[${types.length}]: ${debugStringify(types)}`);
+        zigbeeDevice.log.debug(`Device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} - endpoints[${endpoints.length}]: ${debugStringify(endpoints)}`);
+        zigbeeDevice.log.debug(`Device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} - names[${names.length}]: ${debugStringify(names)}`);
+        zigbeeDevice.log.debug(`Device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} - properties[${properties.length}]: ${debugStringify(properties)}`);
+        zigbeeDevice.log.debug(`Device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} - categories[${categories.length}]: ${debugStringify(categories)}`);
+        zigbeeDevice.log.debug(`Device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} - descriptions[${descriptions.length}]: ${debugStringify(descriptions)}`);
+        zigbeeDevice.log.debug(`Device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} - labels[${labels.length}]: ${debugStringify(labels)}`);
+        zigbeeDevice.log.debug(`Device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} - units[${units.length}]: ${debugStringify(units)}`);
+        */
         for (const [index, name] of names.entries()) {
             if (platform.featureBlackList.includes(name)) {
                 zigbeeDevice.log.debug(`Device ${zigbeeDevice.en}${device.friendly_name}${db} feature ${name} is globally blacklisted`);
@@ -791,6 +1019,7 @@ export class ZigbeeDevice extends ZigbeeEntity {
                 zigbeeDevice.log.debug(`Device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} endpoint: ${zb}${endpoint}${db} type: ${zb}${type}${db} property: ${zb}${name}${db} => deviceType: ${z2m.deviceType?.name} cluster: ${z2m.cluster} attribute: ${z2m.attribute}`);
                 zigbeeDevice.propertyMap.set(property, { name, type, endpoint, category, description, label, unit, value_min, value_max, values: value });
                 if (endpoint === '') {
+                    /* prettier-ignore */
                     if (!zigbeeDevice.mutableDevice.has(endpoint)) {
                         zigbeeDevice.mutableDevice.set(endpoint, { tagList: [], deviceTypes: [z2m.deviceType], clusterServersIds: [...z2m.deviceType.requiredServerClusters, ClusterId(z2m.cluster)], clusterServersObjs: [], clusterClientsIds: [], clusterClientsObjs: [] });
                     }
@@ -814,6 +1043,7 @@ export class ZigbeeDevice extends ZigbeeEntity {
                     if (endpoint === 'l6')
                         tagList.push({ mfgCode: null, namespaceId: NumberTag.Six.namespaceId, tag: NumberTag.Six.tag, label: 'endpoint ' + endpoint });
                     tagList.push({ mfgCode: null, namespaceId: SwitchesTag.Custom.namespaceId, tag: SwitchesTag.Custom.tag, label: 'endpoint ' + endpoint });
+                    /* prettier-ignore */
                     if (!zigbeeDevice.mutableDevice.has(endpoint)) {
                         zigbeeDevice.mutableDevice.set(endpoint, { tagList, deviceTypes: [z2m.deviceType], clusterServersIds: [...z2m.deviceType.requiredServerClusters, ClusterId(z2m.cluster)], clusterServersObjs: [], clusterClientsIds: [], clusterClientsObjs: [] });
                     }
@@ -827,13 +1057,16 @@ export class ZigbeeDevice extends ZigbeeEntity {
                 }
             }
             else {
+                // zigbeeDevice.log.debug(`Device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} endpoint: ${zb}${endpoint}${db} type: ${zb}${type}${db} property: ${zb}${name}${db} => no mapping found`);
             }
+            // Map actions to switches
             if (name === 'action' && zigbeeDevice.actions.length) {
                 zigbeeDevice.log.info(`Device ${zigbeeDevice.ien}${device.friendly_name}${rs}${nf} has actions mapped to these switches on sub endpoints:`);
                 zigbeeDevice.log.info('   controller events      <=> zigbee2mqtt actions');
                 if (!zigbeeDevice.bridgedDevice)
-                    zigbeeDevice.bridgedDevice = await zigbeeDevice.createMutableDevice([bridgedNode], { uniqueStorageKey: device.friendly_name }, zigbeeDevice.log.logLevel === "debug");
+                    zigbeeDevice.bridgedDevice = await zigbeeDevice.createMutableDevice([bridgedNode], { uniqueStorageKey: device.friendly_name }, zigbeeDevice.log.logLevel === "debug" /* LogLevel.DEBUG */);
                 zigbeeDevice.hasEndpoints = true;
+                // Mapping actions
                 const switchMap = ['Single Press', 'Double Press', 'Long Press  '];
                 const triggerMap = ['Single', 'Double', 'Long'];
                 let count = 1;
@@ -866,16 +1099,19 @@ export class ZigbeeDevice extends ZigbeeEntity {
                     zigbeeDevice.composedType = 'button';
             }
         }
+        // Add battery properties
         if (device.power_source === 'Battery') {
             zigbeeDevice.propertyMap.set('battery', { name: 'battery', type: '', endpoint: '' });
             zigbeeDevice.propertyMap.set('battery_low', { name: 'battery_low', type: '', endpoint: '' });
             zigbeeDevice.propertyMap.set('battery_voltage', { name: 'battery_voltage', type: '', endpoint: '' });
         }
+        // Handle when the device has only child endpoints
         if (!zigbeeDevice.mutableDevice.has(''))
             zigbeeDevice.mutableDevice.set('', { tagList: [], deviceTypes: [bridgedNode, powerSource], clusterServersIds: [], clusterServersObjs: [], clusterClientsIds: [], clusterClientsObjs: [] });
         const mainEndpoint = zigbeeDevice.mutableDevice.get('');
         if (!mainEndpoint)
             return zigbeeDevice;
+        // Remove duplicates and superset device Types on all endpoints
         for (const device of zigbeeDevice.mutableDevice.values()) {
             const deviceTypesMap = new Map();
             device.deviceTypes.forEach((deviceType) => {
@@ -891,17 +1127,22 @@ export class ZigbeeDevice extends ZigbeeEntity {
                 deviceTypesMap.delete(onOffLight.code);
             if (deviceTypesMap.has(dimmableLight.code) && deviceTypesMap.has(colorTemperatureLight.code))
                 deviceTypesMap.delete(dimmableLight.code);
-            device.deviceTypes = Array.from(deviceTypesMap.values());
+            device.deviceTypes = Array.from(deviceTypesMap.values()); /* .sort((a, b) => b.code - a.code);*/
         }
-        zigbeeDevice.bridgedDevice = await zigbeeDevice.createMutableDevice(mainEndpoint.deviceTypes, { uniqueStorageKey: device.friendly_name }, zigbeeDevice.log.logLevel === "debug");
+        // Create the mutable device for the main endpoint
+        zigbeeDevice.bridgedDevice = await zigbeeDevice.createMutableDevice(mainEndpoint.deviceTypes, { uniqueStorageKey: device.friendly_name }, zigbeeDevice.log.logLevel === "debug" /* LogLevel.DEBUG */);
+        // Configure BridgedDeviceBasicInformation cluster
         mainEndpoint.clusterServersObjs.push(zigbeeDevice.getBridgedDeviceBasicInformation());
+        // Configure PowerSource cluster
         mainEndpoint.clusterServersObjs.push(zigbeeDevice.getPowerSource());
+        // Configure ColorControlCluster
         if (mainEndpoint.clusterServersIds.includes(ColorControl.Cluster.id)) {
             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')}`);
             if (!names.includes('color_hs') && !names.includes('color_xy')) {
                 mainEndpoint.clusterServersObjs.push(zigbeeDevice.bridgedDevice.getCtColorControlClusterServer());
             }
         }
+        // Configure ThermostatCluster: Auto or Heating only or Cooling only. Set also min and max if available
         if (mainEndpoint.clusterServersIds.includes(Thermostat.Cluster.id)) {
             const heat = zigbeeDevice.propertyMap.get('occupied_heating_setpoint') || zigbeeDevice.propertyMap.get('current_heating_setpoint');
             const cool = zigbeeDevice.propertyMap.get('occupied_cooling_setpoint') || zigbeeDevice.propertyMap.get('current_cooling_setpoint');
@@ -912,18 +1153,20 @@ export class ZigbeeDevice extends ZigbeeEntity {
             zigbeeDevice.log.debug(`Configuring device ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} Thermostat cluster with heating ${CYAN}${heat ? 'supported' : 'not supported'}${db} cooling ${CYAN}${cool ? 'supported' : 'not supported'}${db} ` +
                 `minHeating ${CYAN}${minHeating}${db} maxHeating ${CYAN}${maxHeating}${db} minCooling ${CYAN}${minCooling}${db} maxCooling ${CYAN}${maxCooling}${db}`);
             if (heat && !cool) {
-                zigbeeDevice.propertyMap.delete('running_state');
+                zigbeeDevice.propertyMap.delete('running_state'); // Remove running_state if only heating is supported cause it's not supported by the cluster without AutoMode
                 mainEndpoint.clusterServersObjs.push(zigbeeDevice.bridgedDevice.getDefaultHeatingThermostatClusterServer(undefined, undefined, minHeating, maxHeating));
             }
             else if (!heat && cool) {
-                zigbeeDevice.propertyMap.delete('running_state');
+                zigbeeDevice.propertyMap.delete('running_state'); // Remove running_state if only cooling is supported cause it's not supported by the cluster without AutoMode
                 mainEndpoint.clusterServersObjs.push(zigbeeDevice.bridgedDevice.getDefaultCoolingThermostatClusterServer(undefined, undefined, minCooling, maxCooling));
             }
             else if (heat && cool) {
                 mainEndpoint.clusterServersObjs.push(zigbeeDevice.bridgedDevice.getDefaultThermostatClusterServer(undefined, undefined, undefined, undefined, minHeating, maxHeating, minCooling, maxCooling));
             }
         }
+        // Filter out duplicate clusters and clusters objects
         for (const [endpoint, device] of zigbeeDevice.mutableDevice) {
+            // Filter out duplicate server clusters and server clusters objects. Remove the cluster server id when a cluster server object is present.
             const deviceClusterServersMap = new Map();
             device.clusterServersIds.forEach((clusterServer) => {
                 deviceClusterServersMap.set(clusterServer, clusterServer);
@@ -935,6 +1178,7 @@ export class ZigbeeDevice extends ZigbeeEntity {
             });
             device.clusterServersIds = Array.from(deviceClusterServersMap.values());
             device.clusterServersObjs = Array.from(deviceClusterServersObjMap.values());
+            // Filter out duplicate client clusters and client clusters objects. Remove the cluster client id when a cluster client object is present.
             const deviceClusterClientsMap = new Map();
             device.clusterClientsIds.forEach((clusterClient) => {
                 deviceClusterClientsMap.set(clusterClient, clusterClient);
@@ -949,27 +1193,36 @@ export class ZigbeeDevice extends ZigbeeEntity {
             zigbeeDevice.log.debug(`Device ${zigbeeDevice.ien}${zigbeeDevice.device?.friendly_name}${rs}${db} endpoint: ${ign}${endpoint === '' ? 'main' : endpoint}${rs}${db} => ` +
                 `${nf}tagList: ${debugStringify(device.tagList)} deviceTypes: ${debugStringify(device.deviceTypes)} clusterServersIds: ${debugStringify(device.clusterServersIds)}`);
         }
+        // Add the cluster objects to the main endpoint
         mainEndpoint.clusterServersObjs.forEach((clusterServerObj) => {
             zigbeeDevice.bridgedDevice?.addClusterServer(clusterServerObj);
         });
+        // Add the cluster ids to the main endpoint
         zigbeeDevice.bridgedDevice.addClusterServerFromList(zigbeeDevice.bridgedDevice, mainEndpoint.clusterServersIds);
         zigbeeDevice.bridgedDevice.addRequiredClusterServers(zigbeeDevice.bridgedDevice);
+        // Add the Fixed Label cluster to the main endpoint
         if (zigbeeDevice.composedType !== '')
             await zigbeeDevice.bridgedDevice.addFixedLabel('composed', zigbeeDevice.composedType);
+        // Create the child endpoints
         for (const [endpoint, device] of zigbeeDevice.mutableDevice) {
             if (endpoint === '')
                 continue;
-            const child = zigbeeDevice.bridgedDevice?.addChildDeviceTypeWithClusterServer(endpoint, device.deviceTypes, device.clusterServersIds, { tagList: device.tagList }, zigbeeDevice.log.logLevel === "debug");
+            const child = zigbeeDevice.bridgedDevice?.addChildDeviceTypeWithClusterServer(endpoint, device.deviceTypes, device.clusterServersIds, { tagList: device.tagList }, zigbeeDevice.log.logLevel === "debug" /* LogLevel.DEBUG */);
             device.clusterServersObjs.forEach((clusterServerObj) => {
                 child.addClusterServer(clusterServerObj);
             });
         }
+        // Verify the device
         if (!zigbeeDevice.verifyMutableDevice(zigbeeDevice.bridgedDevice))
             return zigbeeDevice;
+        // Clear the mutable device from memory
         zigbeeDevice.mutableDevice.clear();
+        // Log properties
         zigbeeDevice.logPropertyMap();
+        // Add command handlers
         zigbeeDevice.bridgedDevice.addCommandHandler('identify', async (data) => {
             zigbeeDevice.log.debug(`Command identify called for ${zigbeeDevice.ien}${device.friendly_name}${rs}${db} endpoint: ${data.endpoint.number} request identifyTime:${data.request.identifyTime} `);
+            // logEndpoint(zigbeeDevice.bridgedDevice!);
         });
         if (zigbeeDevice.bridgedDevice.getClusterServerById(OnOffCluster.id) || zigbeeDevice.hasEndpoints) {
             for (const child of zigbeeDevice.bridgedDevice.getChildEndpoints()) {
@@ -1241,3 +1494,4 @@ export class ZigbeeDevice extends ZigbeeEntity {
         return zigbeeDevice;
     }
 }
+//# sourceMappingURL=entity.js.map