matterbridge 3.2.0 → 3.2.1-dev-20250802-516a522

package/dist/matterbridgePlatform.js

@@ -1,82 +1,32 @@
-/**
- * This file contains the class MatterbridgePlatform.
- *
- * @file matterbridgePlatform.ts
- * @author Luca Liguori
- * @created 2024-03-21
- * @version 1.2.1
- * @license Apache-2.0
- *
- * Copyright 2024, 2025, 2026 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.
- */
-// Node.js modules
 import path from 'node:path';
-// Node AnsiLogger module
+import { Descriptor } from '@matter/main/clusters/descriptor';
+import { BridgedDeviceBasicInformation } from '@matter/main/clusters/bridged-device-basic-information';
 import { CYAN, db, er, nf, wr } from 'node-ansi-logger';
-// Node Storage module
 import { NodeStorageManager } from 'node-persist-manager';
 import { checkNotLatinCharacters } from './matterbridgeEndpointHelpers.js';
+import { bridgedNode } from './matterbridgeDeviceTypes.js';
 import { isValidArray, isValidObject, isValidString } from './utils/export.js';
-/**
- * Represents the base Matterbridge platform. It is extended by the MatterbridgeAccessoryPlatform and MatterbridgeServicePlatform classes.
- *
- */
 export class MatterbridgePlatform {
-    /** The Matterbridge instance of this Platform. */
     matterbridge;
-    /** The logger instance for this platform. */
     log;
-    /** The configuration for this platform. */
     config = {};
-    /** The name of the platform. Will be set by the loadPlugin() method using the package.json value. */
     name = '';
-    /** The type of the platform. Will be set by the extending classes. */
     type = '';
-    /** The version of the platform. Will be set by the loadPlugin() method using the package.json value */
     version = '1.0.0';
-    /** Platform node storage manager. */
     storage;
-    /** Platform context storage. */
     context;
-    // Device and entity select in the plugin config UI
     selectDevice = new Map();
     selectEntity = new Map();
-    // Promises for storage
     _contextReady;
     _selectDeviceContextReady;
     _selectEntityContextReady;
-    /** The ready promise for the platform, which resolves when the platform is fully initialized. */
     ready;
-    /** Registered MatterbridgeEndpoint Map by uniqueId */
     _registeredEndpoints = new Map();
-    /** Registered MatterbridgeEndpoint Map by deviceName */
     _registeredEndpointsByName = new Map();
-    /**
-     * Creates an instance of the base MatterbridgePlatform.
-     * It is extended by the MatterbridgeAccessoryPlatform and MatterbridgeServicePlatform classes.
-     * Each plugin must extend the MatterbridgeAccessoryPlatform and MatterbridgeServicePlatform classes.
-     *
-     * @param {Matterbridge} matterbridge - The Matterbridge instance.
-     * @param {AnsiLogger} log - The logger instance.
-     * @param {PlatformConfig} config - The platform configuration.
-     */
     constructor(matterbridge, log, config) {
         this.matterbridge = matterbridge;
         this.log = log;
         this.config = config;
-        // create the NodeStorageManager for the plugin platform
         if (!isValidString(this.config.name, 1))
             throw new Error('Platform: the plugin name is missing or invalid.');
         this.log.debug(`Creating storage for plugin ${this.config.name} in ${path.join(this.matterbridge.matterbridgeDirectory, this.config.name)}`);
@@ -87,14 +37,12 @@ export class MatterbridgePlatform {
             logging: false,
             forgiveParseErrors: true,
         });
-        // create the context storage for the plugin platform
         this.log.debug(`Creating context for plugin ${this.config.name}`);
         this._contextReady = this.storage.createStorage('context').then((context) => {
             this.context = context;
             this.log.debug(`Created context for plugin ${this.config.name}`);
             return;
         });
-        // create the selectDevice storage for the plugin platform
         this.log.debug(`Loading selectDevice for plugin ${this.config.name}`);
         this._selectDeviceContextReady = this.storage.createStorage('selectDevice').then(async (context) => {
             const selectDevice = await context.get('selectDevice', []);
@@ -103,7 +51,6 @@ export class MatterbridgePlatform {
             this.log.debug(`Loaded ${this.selectDevice.size} selectDevice for plugin ${this.config.name}`);
             return;
         });
-        // create the selectEntity storage for the plugin platform
         this.log.debug(`Loading selectEntity for plugin ${this.config.name}`);
         this._selectEntityContextReady = this.storage.createStorage('selectEntity').then(async (context) => {
             const selectEntity = await context.get('selectEntity', []);
@@ -112,156 +59,89 @@ export class MatterbridgePlatform {
             this.log.debug(`Loaded ${this.selectEntity.size} selectEntity for plugin ${this.config.name}`);
             return;
         });
-        // Create the `ready` promise for the platform
         this.ready = Promise.all([this._contextReady, this._selectDeviceContextReady, this._selectEntityContextReady]).then(() => {
             this.log.debug(`MatterbridgePlatform for plugin ${this.config.name} is fully initialized`);
             return;
         });
     }
-    /**
-     * This method must be overridden in the extended class.
-     * It is called when the platform is started.
-     * Use this method to create the MatterbridgeEndpoints and call this.registerDevice().
-     *
-     * @param {string} [reason] - The reason for starting.
-     * @throws {Error} - Throws an error if the method is not overridden.
-     */
     async onStart(reason) {
         this.log.error('Plugins must override onStart.', reason);
         throw new Error('Plugins must override onStart.');
     }
-    /**
-     * This method can be overridden in the extended class. In this case always call super.onConfigure() to save the select and run checkEndpointNumbers().
-     * It is called after the platform has started.
-     * Use this method to perform any configuration of your devices and to override the value of the attributes that are persistent and stored in the
-     * matter storage (i.e. the onOff attribute of the OnOff cluster).
-     */
     async onConfigure() {
         this.log.debug(`Configuring platform ${this.name}`);
-        // Save the selectDevice and selectEntity
         await this.saveSelects();
-        // Check and update the endpoint numbers
         await this.checkEndpointNumbers();
     }
-    /**
-     * This method can be overridden in the extended class. In this case always call super.onShutdown() to save the selects, run checkEndpointNumbers() and cleanup memory.
-     * It is called when the platform is shutting down.
-     * Use this method to clean up any resources you used in the constructor or onStart.
-     *
-     * @param {string} [reason] - The reason for shutting down.
-     */
     async onShutdown(reason) {
         this.log.debug(`Shutting down platform ${this.name}`, reason);
-        // Save the selectDevice and selectEntity
         await this.saveSelects();
-        // Check and update the endpoint numbers
         await this.checkEndpointNumbers();
-        // Cleanup memory
         this.selectDevice.clear();
         this.selectEntity.clear();
         this._registeredEndpoints.clear();
         this._registeredEndpointsByName.clear();
-        // Close the storage
         await this.context?.close();
         this.context = undefined;
         await this.storage?.close();
     }
-    /**
-     * Called when the logger level is changed.
-     *
-     * @param {LogLevel} logLevel The new logger level.
-     */
     async onChangeLoggerLevel(logLevel) {
         this.log.debug(`The plugin doesn't override onChangeLoggerLevel. Logger level set to: ${logLevel}`);
     }
-    /**
-     * Called when a plugin config includes an action button or an action button with text field.
-     *
-     * @param {string} action The action triggered by the button in plugin config.
-     * @param {string} value The value of the field of the action button.
-     * @param {string} id The id of the schema associated with the action.
-     * @param {PlatformConfig} formData The changed form data of the plugin.
-     *
-     * @remarks
-     * This method can be overridden in the extended class.
-     *
-     * Use this method to handle the action defined in the plugin schema:
-     * ```json
-     *  "addDevice": {
-     *      "description": "Manually add a device that has not been discovered with mdns:",
-     *      "type": "boolean",
-     *      "buttonText": "ADD",      // The text on the button. This is used when the action doesn't include a text field.
-     *      "buttonField": "ADD",     // The text on the button. This is used when the action includes a text field.
-     *      "buttonClose": false,     // optional, default is false. When true, the dialog will close after the action is sent.
-     *      "buttonSave": false,      // optional, default is false. When true, the dialog will close and trigger the restart required after the action is sent.
-     *      "textPlaceholder": "Enter the device IP address",   // optional: the placeholder text for the text field.
-     *      "default": false
-     *  },
-     * ```
-     */
     async onAction(action, value, id, formData) {
         this.log.debug(`The plugin ${CYAN}${this.name}${db} doesn't override onAction. Received action ${CYAN}${action}${db}${value ? ' with ' + CYAN + value + db : ''} ${id ? ' for schema ' + CYAN + id + db : ''}`, formData);
     }
-    /**
-     * Called when the plugin config has been updated.
-     *
-     * @param {PlatformConfig} config The new plugin config.
-     */
     async onConfigChanged(config) {
         this.log.debug(`The plugin ${CYAN}${config.name}${db} doesn't override onConfigChanged. Received new config.`);
     }
-    /**
-     * Retrieves the devices registered with the platform.
-     *
-     * @returns {MatterbridgeEndpoint[]} The registered devices.
-     */
     getDevices() {
         return Array.from(this._registeredEndpoints.values());
     }
-    /**
-     * Checks if a device with this name is already registered in the platform.
-     *
-     * @param {string} deviceName - The device name to check.
-     * @returns {boolean} True if the device is already registered, false otherwise.
-     */
     hasDeviceName(deviceName) {
         return this._registeredEndpointsByName.has(deviceName);
     }
-    /**
-     * Registers a device with the Matterbridge platform.
-     *
-     * @param {MatterbridgeEndpoint} device - The device to register.
-     */
     async registerDevice(device) {
         device.plugin = this.name;
-        if (device.deviceName && this._registeredEndpointsByName.has(device.deviceName)) {
+        if (!device.uniqueId) {
+            this.log.error(`Device with name ${CYAN}${device.deviceName}${er} has no uniqueId. Did you forget to call createDefaultBasicInformationClusterServer() or createDefaultBridgedDeviceBasicInformationClusterServer()? The device will not be added.`);
+            return;
+        }
+        if (!device.deviceName) {
+            this.log.error(`Device with uniqueId ${CYAN}${device.uniqueId}${er} has no deviceName. The device will not be added.`);
+            return;
+        }
+        if (!device.serialNumber) {
+            this.log.error(`Device with uniqueId ${CYAN}${device.uniqueId}${er} has no serialNumber. The device will not be added.`);
+            return;
+        }
+        if (this._registeredEndpointsByName.has(device.deviceName)) {
             this.log.error(`Device with name ${CYAN}${device.deviceName}${er} is already registered. The device will not be added. Please change the device name.`);
             return;
         }
-        if (device.deviceName && checkNotLatinCharacters(device.deviceName)) {
+        if (checkNotLatinCharacters(device.deviceName)) {
             this.log.debug(`Device with name ${CYAN}${device.deviceName}${db} has non latin characters.`);
         }
-        /* TODO: Do we need to handle the childbridged mode with DynamicPlatform here if the implementation forgets to call createDefaultBridgedDeviceBasicInformationClusterServer?
-        if (this.matterbridge.bridgeMode === 'childbridge' && this.type === 'DynamicPlatform' && device.mode === undefined) {
-          const options = device.getClusterServerOptions(Descriptor.Cluster.id);
-          if (options) {
-            const deviceTypeList = options.deviceTypeList as { deviceType: number; revision: number }[];
-            deviceTypeList.push({ deviceType: bridgedNode.code, revision: bridgedNode.revision });
-          }
-          device.createDefaultBridgedDeviceBasicInformationClusterServer(deviceName, serialNumber, vendorId, vendorName, productName, softwareVersion, softwareVersionString, hardwareVersion, hardwareVersionString);
+        if (device.mode === undefined && (this.matterbridge.bridgeMode === 'bridge' || (this.matterbridge.bridgeMode === 'childbridge' && this.type === 'DynamicPlatform'))) {
+            if (!device.deviceTypes.has(bridgedNode.code)) {
+                this.log.debug(`Device with name ${CYAN}${device.deviceName}${db} has no bridgedNode device type. Adding it...`);
+                device.deviceTypes.set(bridgedNode.code, bridgedNode);
+                const options = device.getClusterServerOptions(Descriptor.Cluster.id);
+                if (options) {
+                    const deviceTypeList = options.deviceTypeList;
+                    if (!deviceTypeList.find((dt) => dt.deviceType === bridgedNode.code)) {
+                        deviceTypeList.push({ deviceType: bridgedNode.code, revision: bridgedNode.revision });
+                    }
+                }
+            }
+            if (!device.hasClusterServer(BridgedDeviceBasicInformation.Cluster.id)) {
+                this.log.debug(`Device with name ${CYAN}${device.deviceName}${db} has no BridgedDeviceBasicInformation cluster. Adding it...`);
+                device.createDefaultBridgedDeviceBasicInformationClusterServer(device.deviceName, device.serialNumber, device.vendorId, device.vendorName, device.productName, device.softwareVersion, device.softwareVersionString, device.hardwareVersion, device.hardwareVersionString);
+            }
         }
-        */
         await this.matterbridge.addBridgedEndpoint(this.name, device);
-        if (device.uniqueId)
-            this._registeredEndpoints.set(device.uniqueId, device);
-        if (device.deviceName)
-            this._registeredEndpointsByName.set(device.deviceName, device);
+        this._registeredEndpoints.set(device.uniqueId, device);
+        this._registeredEndpointsByName.set(device.deviceName, device);
     }
-    /**
-     * Unregisters a device registered with the Matterbridge platform.
-     *
-     * @param {MatterbridgeEndpoint} device - The device to unregister.
-     */
     async unregisterDevice(device) {
         await this.matterbridge.removeBridgedEndpoint(this.name, device);
         if (device.uniqueId)
@@ -269,24 +149,11 @@ export class MatterbridgePlatform {
         if (device.deviceName)
             this._registeredEndpointsByName.delete(device.deviceName);
     }
-    /**
-     * Unregisters all devices registered with the Matterbridge platform.
-     *
-     * @param {number} [delay] - The delay in milliseconds between removing each bridged endpoint (default: 0).
-     */
     async unregisterAllDevices(delay = 0) {
         await this.matterbridge.removeAllBridgedEndpoints(this.name, delay);
         this._registeredEndpoints.clear();
         this._registeredEndpointsByName.clear();
     }
-    /**
-     * Saves the select devices and entities to storage.
-     *
-     * This method saves the current state of `selectDevice` and `selectEntity` maps to their respective storage.
-     * It logs the number of items being saved and ensures that the storage is properly closed after saving.
-     *
-     * @returns {Promise<void>} A promise that resolves when the save operation is complete.
-     */
     async saveSelects() {
         if (this.storage) {
             this.log.debug(`Saving ${this.selectDevice.size} selectDevice...`);
@@ -299,36 +166,15 @@ export class MatterbridgePlatform {
             await selectEntity.close();
         }
     }
-    /**
-     * Clears all the select device and entity maps.
-     *
-     * @returns {void}
-     */
     async clearSelect() {
         this.selectDevice.clear();
         this.selectEntity.clear();
         await this.saveSelects();
     }
-    /**
-     * Clears the select for a single device.
-     *
-     * @param {string} serial - The serial of the device to clear.
-     * @returns {void}
-     */
     async clearDeviceSelect(serial) {
         this.selectDevice.delete(serial);
         await this.saveSelects();
     }
-    /**
-     * Set the select device in the platform map.
-     *
-     * @param {string} serial - The serial number of the device.
-     * @param {string} name - The name of the device.
-     * @param {string} [configUrl] - The configuration URL of the device.
-     * @param {string} [icon] - The icon of the device: 'wifi', 'ble', 'hub'
-     * @param {Array<{ name: string; description: string; icon?: string }>} [entities] - The entities associated with the device.
-     * @returns {void}
-     */
     setSelectDevice(serial, name, configUrl, icon, entities) {
         const device = this.selectDevice.get(serial);
         if (device) {
@@ -345,15 +191,6 @@ export class MatterbridgePlatform {
             this.selectDevice.set(serial, { serial, name, configUrl, icon, entities });
         }
     }
-    /**
-     * Set the select device entity in the platform map.
-     *
-     * @param {string} serial - The serial number of the device.
-     * @param {string} entityName - The name of the entity.
-     * @param {string} entityDescription - The description of the entity.
-     * @param {string} [entityIcon] - The icon of the entity: 'wifi', 'ble', 'hub', 'component', 'matter'
-     * @returns {void}
-     */
     setSelectDeviceEntity(serial, entityName, entityDescription, entityIcon) {
         const device = this.selectDevice.get(serial);
         if (device) {
@@ -363,11 +200,6 @@ export class MatterbridgePlatform {
                 device.entities.push({ name: entityName, description: entityDescription, icon: entityIcon });
         }
     }
-    /**
-     * Retrieves the select devices from the platform map.
-     *
-     * @returns {{ pluginName: string; serial: string; name: string; configUrl?: string; icon?: string; entities?: { name: string; description: string; icon?: string }[] }[]} The selected devices array.
-     */
     getSelectDevices() {
         const selectDevices = [];
         for (const device of this.selectDevice.values()) {
@@ -375,22 +207,9 @@ export class MatterbridgePlatform {
         }
         return selectDevices;
     }
-    /**
-     * Set the select entity in the platform map.
-     *
-     * @param {string} name - The entity name.
-     * @param {string} description - The entity description.
-     * @param {string} [icon] - The entity icon: 'wifi', 'ble', 'hub', 'component', 'matter'
-     * @returns {void}
-     */
     setSelectEntity(name, description, icon) {
         this.selectEntity.set(name, { name, description, icon });
     }
-    /**
-     * Retrieve the select entities.
-     *
-     * @returns {{ pluginName: string; name: string; description: string; icon?: string }[]} The select entities array.
-     */
     getSelectEntities() {
         const selectEntities = [];
         for (const entity of this.selectEntity.values()) {
@@ -398,12 +217,6 @@ export class MatterbridgePlatform {
         }
         return selectEntities;
     }
-    /**
-     * Verifies if the Matterbridge version meets the required version.
-     *
-     * @param {string} requiredVersion - The required version to compare against.
-     * @returns {boolean} True if the Matterbridge version meets or exceeds the required version, false otherwise.
-     */
     verifyMatterbridgeVersion(requiredVersion) {
         const compareVersions = (matterbridgeVersion, requiredVersion) => {
             const stripTag = (v) => {
@@ -428,14 +241,6 @@ export class MatterbridgePlatform {
             return false;
         return true;
     }
-    /**
-     * Validates if a device is allowed based on the whitelist and blacklist configurations.
-     * The blacklist has priority over the whitelist.
-     *
-     * @param {string | string[]} device - The device name(s) to validate.
-     * @param {boolean} [log] - Whether to log the validation result.
-     * @returns {boolean} - Returns true if the device is allowed, false otherwise.
-     */
     validateDevice(device, log = true) {
         if (!Array.isArray(device))
             device = [device];
@@ -465,14 +270,6 @@ export class MatterbridgePlatform {
             this.log.info(`Skipping device ${CYAN}${device.join(', ')}${nf} because not in whitelist`);
         return false;
     }
-    /**
-     * Validates if an entity is allowed based on the entity blacklist and device-entity blacklist configurations.
-     *
-     * @param {string} device - The device to which the entity belongs.
-     * @param {string} entity - The entity to validate.
-     * @param {boolean} [log] - Whether to log the validation result.
-     * @returns {boolean} - Returns true if the entity is allowed, false otherwise.
-     */
     validateEntity(device, entity, log = true) {
         if (isValidArray(this.config.entityBlackList, 1) && this.config.entityBlackList.find((e) => e === entity)) {
             if (log)
@@ -491,15 +288,6 @@ export class MatterbridgePlatform {
         }
         return true;
     }
-    /**
-     * Checks and updates the endpoint numbers for Matterbridge devices.
-     *
-     * This method retrieves the list of Matterbridge devices and their child endpoints,
-     * compares their current endpoint numbers with the stored ones, and updates the storage
-     * if there are any changes. It logs the changes and updates the endpoint numbers accordingly.
-     *
-     * @returns {Promise<number>} The size of the updated endpoint map, or -1 if storage is not available.
-     */
     async checkEndpointNumbers() {
         if (!this.storage)
             return -1;
@@ -540,4 +328,3 @@ export class MatterbridgePlatform {
         return endpointMap.size;
     }
 }
-//# sourceMappingURL=matterbridgePlatform.js.map

package/dist/matterbridgeTypes.js

@@ -1,28 +1,3 @@
-/**
- * This file contains the types for Matterbridge.
- *
- * @file matterbridgeTypes.ts
- * @author Luca Liguori
- * @created 2024-07-12
- * @version 1.0.2
- * @license Apache-2.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.
- */
-// Default colors
 export const plg = '\u001B[38;5;33m';
 export const dev = '\u001B[38;5;79m';
 export const typ = '\u001B[38;5;207m';
-//# sourceMappingURL=matterbridgeTypes.js.map