matterbridge-zigbee2mqtt 2.2.2 → 2.2.3-dev.5

package/CHANGELOG.md

@@ -4,6 +4,23 @@ If you like this project and find it useful, please consider giving it a star on
 
 All notable changes to this project will be documented in this file.
 
+## [2.2.3] - 2024-11-XX
+
+### Added
+
+- [matterbridge]: Preliminary update to support Matterbridge edge (matter.js new API).
+- [zigbeeEntity]: Add create async to ZigbeeDevice and ZigbeeGroup.
+
+### Changed
+
+- [package]: Updated dependencies.
+
+### Fixed
+
+<a href="https://www.buymeacoffee.com/luligugithub">
+  <img src="./yellow-button.png" alt="Buy me a coffee" width="120">
+</a>
+
 ## [2.2.2] - 2024-11-26
 
 ### Added

package/dist/entity.d.ts

@@ -20,12 +20,18 @@
  * See the License for the specific language governing permissions and
  * limitations under the License. *
  */
-import { DeviceTypeDefinition, MatterbridgeDevice, ClusterId, Endpoint, AtLeastOne, EndpointOptions } from 'matterbridge';
+import { DeviceTypeDefinition, MatterbridgeDevice, ClusterId, BridgedDeviceBasicInformation, Endpoint, EndpointOptions, ClusterServerObj, ClusterClientObj, Semtag, AtLeastOne } from 'matterbridge';
 import { AnsiLogger } from 'matterbridge/logger';
 import EventEmitter from 'events';
 import { ZigbeePlatform } from './platform.js';
 import { BridgeDevice, BridgeGroup } from './zigbee2mqttTypes.js';
 import { Payload, PayloadValue } from './payloadTypes.js';
+/**
+ * Represents a Zigbee entity: a group or a device.
+ *
+ * @class
+ * @extends {EventEmitter}
+ */
 export declare class ZigbeeEntity extends EventEmitter {
     log: AnsiLogger;
     serial: string;
@@ -52,32 +58,150 @@ export declare class ZigbeeEntity extends EventEmitter {
         value_min?: number;
         value_max?: number;
         unit?: string;
+        category?: string;
+        description?: string;
+        label?: string;
         action?: string;
     }>;
+    protected readonly mutableDevice: Map<string, {
+        tagList: Semtag[];
+        deviceTypes: DeviceTypeDefinition[];
+        clusterServersIds: ClusterId[];
+        clusterServersObjs: ClusterServerObj[];
+        clusterClientsIds: ClusterId[];
+        clusterClientsObjs: ClusterClientObj[];
+    }>;
     colorTimeout: NodeJS.Timeout | undefined;
     thermostatTimeout: NodeJS.Timeout | undefined;
+    protected composedType: string;
     protected hasEndpoints: boolean;
     isRouter: boolean;
     protected noUpdate: boolean;
-    createDevice(definition: DeviceTypeDefinition | AtLeastOne<DeviceTypeDefinition>, includeServerList?: ClusterId[], options?: EndpointOptions, debug?: boolean): MatterbridgeDevice;
-    configure(): void;
     /**
-     * Retrieves the value of the specified attribute from the given endpoint and cluster.
+     * Creates an instance of ZigbeeEntity.
      *
-     * @param {ClusterId} clusterId - The ID of the cluster to retrieve the attribute from.
-     * @param {string} event - The name of the event to trigger.
-     * @param {Record<string, any>} payload - The payload of the event to trigger.
-     * @param {AnsiLogger} [log] - Optional logger for error and info messages.
-     * @param {Endpoint} [endpoint] - Optional the child endpoint to retrieve the attribute from.
+     * @param {ZigbeePlatform} platform - The Zigbee platform instance.
+     * @param {BridgeDevice | BridgeGroup} entity - The bridge device or group instance received from zigbee2mqtt.
      */
-    triggerEvent(clusterId: ClusterId, event: string, payload: Record<string, any>, log?: AnsiLogger, endpoint?: Endpoint): void;
     constructor(platform: ZigbeePlatform, entity: BridgeDevice | BridgeGroup);
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    protected createMutableDevice(definition: DeviceTypeDefinition | AtLeastOne<DeviceTypeDefinition>, options?: EndpointOptions, debug?: boolean): Promise<MatterbridgeDevice>;
+    protected getBridgedDeviceBasicInformation(): ClusterServerObj<BridgedDeviceBasicInformation.Cluster>;
+    protected addBridgedDeviceBasicInformation(): MatterbridgeDevice;
+    protected getPowerSource(): ClusterServerObj<any>;
+    protected addPowerSource(): MatterbridgeDevice;
+    /**
+     * 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.
+     */
+    protected verifyMutableDevice(endpoint: MatterbridgeDevice): boolean;
+    /**
+     * 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.
+     */
+    configure(): Promise<void>;
+    /**
+     * 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.
+     */
     protected updateAttributeIfChanged(deviceEndpoint: Endpoint, childEndpointName: string | undefined, clusterId: number, attributeName: string, value: PayloadValue, lookup?: string[]): void;
+    /**
+     * 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.
+     */
     protected publishCommand(command: string, entityName: string, payload: Payload): void;
+    /**
+     * 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.
+     */
+    protected logPropertyMap(): void;
 }
+/**
+ * Represents a Zigbee group entity.
+ *
+ * @class
+ * @extends {ZigbeeEntity}
+ */
 export declare class ZigbeeGroup extends ZigbeeEntity {
-    constructor(platform: ZigbeePlatform, group: BridgeGroup);
+    /**
+     * Creates an instance of ZigbeeGroup.
+     *
+     * @param {ZigbeePlatform} platform - The Zigbee platform instance.
+     * @param {BridgeGroup} group - The bridge group instance.
+     */
+    private constructor();
+    /**
+     * 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 create(platform: ZigbeePlatform, group: BridgeGroup): Promise<ZigbeeGroup>;
 }
 export interface ZigbeeToMatter {
     type: string;
@@ -90,7 +214,31 @@ export interface ZigbeeToMatter {
     valueLookup?: string[];
 }
 export declare const z2ms: ZigbeeToMatter[];
+/**
+ * Represents a Zigbee device entity.
+ *
+ * @class
+ * @extends {ZigbeeEntity}
+ */
 export declare class ZigbeeDevice extends ZigbeeEntity {
-    constructor(platform: ZigbeePlatform, device: BridgeDevice);
+    /**
+     * Represents a Zigbee device entity.
+     *
+     * @class
+     * @extends {ZigbeeEntity}
+     */
+    private constructor();
+    /**
+     * 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 create(platform: ZigbeePlatform, device: BridgeDevice): Promise<ZigbeeDevice>;
 }
 //# sourceMappingURL=entity.d.ts.map

package/dist/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"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"}