matterbridge 3.5.0-dev-20260119-f9ea00e → 3.5.0

package/dist/matterNode.js

@@ -1,8 +1,35 @@
+/**
+ * This file contains the class MatterNode.
+ *
+ * @file matterNode.ts
+ * @author Luca Liguori
+ * @created 2025-10-01
+ * @version 1.0.0
+ * @license Apache-2.0
+ *
+ * Copyright 2025, 2026, 2027 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 modules
 import path from 'node:path';
 import fs from 'node:fs';
 import EventEmitter from 'node:events';
+// AnsiLogger module
 import { AnsiLogger, BLUE, CYAN, db, debugStringify, er, nf, or, zb } from 'node-ansi-logger';
+// Node persist manager module
 import { NodeStorageManager } from 'node-persist-manager';
+// @matter
 import '@matter/nodejs';
 import { Logger, LogLevel as MatterLogLevel, LogFormat as MatterLogFormat, StorageService, UINT32_MAX, UINT16_MAX, Environment } from '@matter/general';
 import { MdnsService } from '@matter/protocol';
@@ -22,27 +49,48 @@ import { BroadcastServer } from './broadcastServer.js';
 import { toBaseDevice } from './deviceManager.js';
 import { PluginManager } from './pluginManager.js';
 import { addVirtualDevice } from './helpers.js';
+/**
+ * Represents the Matter class.
+ */
 export class MatterNode extends EventEmitter {
     matterbridge;
     pluginName;
     device;
-    log = new AnsiLogger({ logName: 'MatterNode', logTimestampFormat: 4, logLevel: "debug" });
-    matterLog = new AnsiLogger({ logName: 'MatterNode', logTimestampFormat: 4, logLevel: "debug" });
+    /** Matterbridge logger */
+    log = new AnsiLogger({ logName: 'MatterNode', logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: "debug" /* LogLevel.DEBUG */ });
+    /** Matter logger */
+    matterLog = new AnsiLogger({ logName: 'MatterNode', logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: "debug" /* LogLevel.DEBUG */ });
+    /** Matter environment default */
     environment = Environment.default;
+    /** Matter storage id */
     storeId;
+    /** Matter mdns service from environment default */
     matterMdnsService;
+    /** Matter storage service from environment default */
     matterStorageService;
+    /** Matter storage manager created with name 'Matterbridge' */
     matterStorageManager;
+    /** Matter storage context created in the storage manager with name 'persist' */
     matterStorageContext;
+    /** Matter mdns interface name e.g. 'eth0' or 'wlan0' or 'Wi-Fi' */
     mdnsInterface;
+    /** Matter listeningAddressIpv4 address */
     ipv4Address;
+    /** Matter listeningAddressIpv6 address */
     ipv6Address;
+    /** Matter commissioning port It is incremented in childbridge mode. */
     port;
+    /** Matter commissioning passcode. It is incremented in childbridge mode. */
     passcode;
+    /** Matter commissioning discriminator. It is incremented in childbridge mode. */
     discriminator;
+    /** Matter device certification */
     certification;
+    /** Matter server node */
     serverNode;
+    /** Matter aggregator node */
     aggregatorNode;
+    // Default values for the aggregator node
     aggregatorVendorId = VendorId(getIntParameter('vendorId') ?? 0xfff1);
     aggregatorVendorName = getParameter('vendorName') ?? 'Matterbridge';
     aggregatorProductId = getIntParameter('productId') ?? 0x8000;
@@ -50,12 +98,23 @@ export class MatterNode extends EventEmitter {
     aggregatorDeviceType = DeviceTypeId(getIntParameter('deviceType') ?? bridge.code);
     aggregatorSerialNumber = getParameter('serialNumber');
     aggregatorUniqueId = getParameter('uniqueId');
+    /** Advertising nodes map: time advertising started keyed by storeId */
     advertisingNodes = new Map();
+    /** Plugins */
     pluginManager;
+    /** Dependant MatterNodes keyed by device id */
     dependantMatterNodes = new Map();
+    /** Broadcast server */
     server;
     debug = hasParameter('debug') || hasParameter('verbose');
     verbose = hasParameter('verbose');
+    /**
+     * Creates an instance of the Matter class.
+     *
+     * @param {SharedMatterbridge} matterbridge - The shared matterbridge instance.
+     * @param {PluginName} [pluginName] - The plugin name (optional). If not provided, it is assumed to be the main matter node instance and all plugins are included.
+     * @param {MatterbridgeEndpoint} [device] - The matterbridge endpoint device (optional). It is used to create a server mode device.
+     */
     constructor(matterbridge, pluginName, device) {
         super();
         this.matterbridge = matterbridge;
@@ -64,19 +123,25 @@ export class MatterNode extends EventEmitter {
         this.log.logNameColor = '\x1b[38;5;65m';
         if (this.debug)
             this.log.debug(`MatterNode ${this.pluginName ? 'for plugin ' + this.pluginName : 'bridge'} loading...`);
+        // Setup Matter parameters
         this.port = matterbridge.port;
         this.passcode = matterbridge.passcode;
         this.discriminator = matterbridge.discriminator;
+        // Setup the broadcast server
         this.server = new BroadcastServer('matter', this.log);
         this.server.on('broadcast_message', this.msgHandler.bind(this));
         if (this.verbose)
             this.log.debug(`BroadcastServer is ready`);
+        // Ensure the matterbridge directory exists
         fs.mkdirSync(matterbridge.matterbridgeDirectory, { recursive: true });
+        // Setup the plugin manager with thread server closed
         this.pluginManager = new PluginManager(this.matterbridge);
-        this.pluginManager.logLevel = this.debug ? "debug" : "info";
+        this.pluginManager.logLevel = this.debug ? "debug" /* LogLevel.DEBUG */ : "info" /* LogLevel.INFO */;
+        // @ts-expect-error access private property
         this.pluginManager.server.close();
         if (this.verbose)
             this.log.debug(`PluginManager is ready`);
+        // Setup the matter environment
         this.environment.vars.set('log.level', MatterLogLevel.DEBUG);
         this.environment.vars.set('log.format', MatterLogFormat.ANSI);
         this.environment.vars.set('path.root', path.join(matterbridge.matterbridgeDirectory, MATTER_STORAGE_NAME));
@@ -84,15 +149,18 @@ export class MatterNode extends EventEmitter {
         this.environment.vars.set('runtime.exitcode', false);
         if (this.verbose)
             this.log.debug(`Matter Environment is ready`);
+        // Ensure MdnsService is registered in the default environment
         this.matterMdnsService = new MdnsService(this.environment);
         setImmediate(async () => {
             await this.matterMdnsService?.construction.ready;
             if (this.verbose)
                 this.log.debug(`Matter MdnsService is ready`);
         });
+        // Setup the matterbridge logger
         if (this.matterbridge.fileLogger) {
             AnsiLogger.setGlobalLogfile(path.join(this.matterbridge.matterbridgeDirectory, MATTERBRIDGE_LOGGER_FILE), this.matterbridge.logLevel);
         }
+        // Setup the matter logger
         Logger.destinations.default.write = this.createDestinationMatterLogger();
         const levels = ['debug', 'info', 'notice', 'warn', 'error', 'fatal'];
         if (this.verbose)
@@ -100,6 +168,11 @@ export class MatterNode extends EventEmitter {
         if (this.debug)
             this.log.debug(`MatterNode ${this.pluginName ? 'for plugin ' + this.pluginName : 'bridge'} loaded`);
     }
+    /**
+     * Handles incoming messages from the broadcast server.
+     *
+     * @param {WorkerMessage} msg - The incoming message.
+     */
     async msgHandler(msg) {
         if (this.server.isWorkerRequest(msg) && (msg.dst === 'all' || msg.dst === 'matter')) {
             if (this.verbose)
@@ -130,9 +203,17 @@ export class MatterNode extends EventEmitter {
             }
         }
     }
+    /**
+     * Destroys the Matter instance.
+     * It closes the mDNS service and the broadcast server.
+     *
+     * @param {boolean} closeMdns - Whether to close the mDNS service. Default is true.
+     * @returns {Promise<void>} A promise that resolves when the instance is destroyed.
+     */
     async destroy(closeMdns = true) {
         if (this.verbose)
             this.log.debug(`Destroying MatterNode instance for ${this.storeId}...`);
+        // Close mDNS service
         if (closeMdns) {
             if (this.verbose)
                 this.log.debug(`Closing Matter MdnsService for ${this.storeId}...`);
@@ -140,18 +221,26 @@ export class MatterNode extends EventEmitter {
             if (this.verbose)
                 this.log.debug(`Closed Matter MdnsService for ${this.storeId}`);
         }
+        // Close the plugin manager
         this.pluginManager.destroy();
+        // Close the broadcast server
         this.server.close();
+        // Yield to the Node.js event loop to allow all resources to be released
         await this.yieldToNode();
         if (this.verbose)
             this.log.debug(`Destroyed MatterNode instance for ${this.storeId}`);
     }
     async create() {
         this.log.info('Creating Matter node...');
+        // Start matter storage
         await this.startMatterStorage();
+        // Load plugins from storage
+        // @ts-expect-error access private property
         this.pluginManager.matterbridge.nodeStorage = new NodeStorageManager({ dir: path.join(this.matterbridge.matterbridgeDirectory, NODE_STORAGE_DIR), writeQueue: false, expiredInterval: undefined, logging: false });
+        // @ts-expect-error access private property
         this.pluginManager.matterbridge.nodeContext = await this.pluginManager.matterbridge.nodeStorage.createStorage('matterbridge');
         await this.pluginManager.loadFromStorage();
+        // Create Matter node for a server mode device
         if (this.pluginName && this.device && this.device.deviceName) {
             this.log.debug(`Creating MatterNode instance for server node device ${CYAN}${this.device.deviceName}${db}...`);
             await this.createDeviceServerNode(this.pluginName, this.device);
@@ -162,6 +251,7 @@ export class MatterNode extends EventEmitter {
         if (!this.pluginName) {
             this.log.debug('Creating MatterNode instance for all plugins...');
             await this.createMatterbridgeServerNode();
+            // Load all enabled plugins
             this.log.debug('Loading all plugins...');
             const loadPromises = [];
             for (const plugin of this.pluginManager.array().filter((p) => p.enabled)) {
@@ -174,6 +264,7 @@ export class MatterNode extends EventEmitter {
         }
         else {
             this.log.debug(`Creating MatterNode instance for plugin ${CYAN}${this.pluginName}${db}...`);
+            // Load only the specified plugin
             this.log.debug(`Loading plugin ${CYAN}${this.pluginName}${db}...`);
             await this.pluginManager.load(this.pluginName);
             this.log.debug(`Loaded plugin ${CYAN}${this.pluginName}${db}`);
@@ -187,13 +278,16 @@ export class MatterNode extends EventEmitter {
         if (!this.serverNode && !this.pluginName)
             throw new Error('Matter server node not created yet. Call create() first.');
         this.log.info('Starting MatterNode...');
+        // Start Matter node for a server mode device
         if (this.pluginName && this.device && this.device.deviceName) {
+            // Start the server node
             this.log.debug(`Starting MatterNode for server device ${this.pluginName}:${this.device.deviceName}...`);
             await this.startServerNode();
             this.log.debug(`Started MatterNode for server device ${this.pluginName}:${this.device.deviceName}`);
             return;
         }
         if (!this.pluginName) {
+            // Start all loaded plugins
             this.log.debug('Starting all plugins...');
             const startPromises = [];
             for (const plugin of this.pluginManager.array().filter((p) => p.enabled && p.loaded)) {
@@ -201,9 +295,11 @@ export class MatterNode extends EventEmitter {
             }
             await Promise.all(startPromises);
             this.log.debug('Started all plugins');
+            // Start the server node
             this.log.debug('Starting MatterNode for all plugins...');
             await this.startServerNode();
             this.log.debug('Started MatterNode for all plugins');
+            // Configure all loaded plugins
             this.log.debug('Configuring all plugins...');
             const configurePromises = [];
             for (const plugin of this.pluginManager.array().filter((p) => p.enabled && p.started)) {
@@ -213,12 +309,16 @@ export class MatterNode extends EventEmitter {
             this.log.debug('Configured all plugins');
         }
         else {
+            // Start the loaded plugin
             await this.pluginManager.start(this.pluginName, 'Starting MatterNode');
+            // Start the server node
             this.log.debug(`Starting MatterNode for plugin ${this.pluginName}...`);
             await this.startServerNode();
             this.log.debug(`Started MatterNode for plugin ${this.pluginName}`);
+            // Configure the plugin
             await this.pluginManager.configure(this.pluginName);
         }
+        // Start the dependant MatterNodes
         this.log.debug(`Starting dependant MatterNodes...`);
         for (const dependantMatterNode of this.dependantMatterNodes.values()) {
             await dependantMatterNode.start();
@@ -231,13 +331,15 @@ export class MatterNode extends EventEmitter {
         if (!this.serverNode)
             throw new Error('Matter server node not created yet. Call create() first.');
         this.log.info('Stopping MatterNode...');
+        // Stop Matter node for a server mode device
         if (this.pluginName && this.device && this.device.deviceName) {
+            // Stop the server node
             this.log.debug(`Stopping MatterNode for server device ${this.pluginName}:${this.device.deviceName}...`);
             await this.stopServerNode();
             this.serverNode = undefined;
             this.aggregatorNode = undefined;
             await this.stopMatterStorage();
-            await this.destroy(false);
+            await this.destroy(false); // Do not close mDNS since it is shared
             this.log.debug(`Stopped MatterNode for server device ${this.pluginName}:${this.device.deviceName}`);
             this.log.info('Stopped MatterNode');
             await this.yieldToNode();
@@ -257,6 +359,7 @@ export class MatterNode extends EventEmitter {
             await this.pluginManager.shutdown(this.pluginName, 'Stopping MatterNode');
             this.log.debug(`Stopped plugin ${this.pluginName}`);
         }
+        // Stop the dependant MatterNodes
         this.log.debug(`Stopping dependant MatterNodes...`);
         for (const dependantMatterNode of this.dependantMatterNodes.values()) {
             await dependantMatterNode.stop();
@@ -269,24 +372,46 @@ export class MatterNode extends EventEmitter {
         this.log.info('Stopped MatterNode');
         await this.yieldToNode();
     }
+    /**
+     * Creates a MatterLogger function to show the matter.js log messages in AnsiLogger (console and frontend).
+     * It also logs to file (matter.log) if fileLogger is true.
+     *
+     * @returns {Function} The MatterLogger function. \x1b[35m for violet \x1b[34m is blue
+     */
     createDestinationMatterLogger() {
-        this.matterLog.logNameColor = '\x1b[34m';
+        this.matterLog.logNameColor = '\x1b[34m'; // Blue matter.js Logger
         if (this.matterbridge.matterFileLogger) {
             this.matterLog.logFilePath = path.join(this.matterbridge.matterbridgeDirectory, MATTER_LOGGER_FILE);
         }
         return (text, message) => {
+            // 2024-08-21 08:55:19.488 DEBUG InteractionMessenger Sending DataReport chunk with 28 attributes and 0 events: 1004 bytes
             const logger = text.slice(44, 44 + 20).trim();
             const msg = text.slice(65);
             this.matterLog.logName = logger;
             this.matterLog.log(MatterLogLevel.names[message.level], msg);
         };
     }
+    /**
+     * Starts the matter storage with name Matterbridge and performs a backup.
+     *
+     * @returns {Promise<void>} - A promise that resolves when the storage is started.
+     */
     async startMatterStorage() {
+        // Setup Matter storage
         this.log.info(`Starting matter node storage...`);
         this.matterStorageService = this.environment.get(StorageService);
         this.log.info(`Started matter node storage in ${CYAN}${this.matterStorageService.location}${nf}`);
+        // Backup matter storage since it is created/opened correctly
         await this.backupMatterStorage(path.join(this.matterbridge.matterbridgeDirectory, MATTER_STORAGE_NAME), path.join(this.matterbridge.matterbridgeDirectory, MATTER_STORAGE_NAME + '.backup'));
     }
+    /**
+     * Makes a backup copy of the specified matter storage directory.
+     *
+     * @param {string} storageName - The name of the storage directory to be backed up.
+     * @param {string} backupName - The name of the backup directory to be created.
+     * @private
+     * @returns {Promise<void>} A promise that resolves when the has been done.
+     */
     async backupMatterStorage(storageName, backupName) {
         this.log.info(`Creating matter node storage backup from ${CYAN}${storageName}${nf} to ${CYAN}${backupName}${nf}...`);
         try {
@@ -294,6 +419,7 @@ export class MatterNode extends EventEmitter {
             this.log.info('Created matter node storage backup');
         }
         catch (error) {
+            // istanbul ignore next if
             if (error instanceof Error && error?.code === 'ENOENT') {
                 this.log.info(`No matter node storage found to backup from ${CYAN}${storageName}${nf} to ${CYAN}${backupName}${nf}`);
             }
@@ -302,6 +428,11 @@ export class MatterNode extends EventEmitter {
             }
         }
     }
+    /**
+     * Stops the matter storage.
+     *
+     * @returns {Promise<void>} A promise that resolves when the storage is stopped.
+     */
     async stopMatterStorage() {
         this.log.info('Closing matter node storage...');
         await this.matterStorageManager?.close();
@@ -311,6 +442,21 @@ export class MatterNode extends EventEmitter {
         this.log.info('Closed matter node storage');
         this.emit('closed');
     }
+    /**
+     * Creates a server node storage context.
+     *
+     * @param {string} storeId - The storeId.
+     * @param {string} deviceName - The name of the device.
+     * @param {DeviceTypeId} deviceType - The device type of the device.
+     * @param {VendorId} vendorId - The vendor ID.
+     * @param {string} vendorName - The vendor name.
+     * @param {number} productId - The product ID.
+     * @param {string} productName - The product name.
+     * @param {string} [serialNumber] - The serial number of the device (optional).
+     * @param {string} [uniqueId] - The unique ID of the device (optional).
+     * @returns {Promise<StorageContext>} The storage context for the commissioning server.
+     * @throws {Error} If the storage service is not initialized.
+     */
     async createServerNodeContext(storeId, deviceName, deviceType, vendorId, vendorName, productId, productName, serialNumber, uniqueId) {
         if (!this.matterStorageService) {
             throw new Error('No storage service initialized');
@@ -353,33 +499,52 @@ export class MatterNode extends EventEmitter {
         this.log.debug(`- hardwareVersionString: ${await storageContext.get('hardwareVersionString')}`);
         return storageContext;
     }
+    /**
+     * Creates a server node.
+     *
+     * @param {number} [port] - The port number for the server node. Defaults to 5540.
+     * @param {number} [passcode] - The passcode for the server node. Defaults to 20242025.
+     * @param {number} [discriminator] - The discriminator for the server node. Defaults to 3850.
+     * @returns {Promise<ServerNode<ServerNode.RootEndpoint>>} A promise that resolves to the created server node.
+     * @throws {Error} If the matter storage context is not created yet.
+     */
     async createServerNode(port = 5540, passcode = 20252026, discriminator = 3850) {
         if (!this.matterStorageContext) {
             throw new Error('Matter server node context not created yet. Call createServerNodeContext() first.');
         }
         const storeId = await this.matterStorageContext.get('storeId');
         this.log.notice(`Creating server node for ${storeId} on port ${port} with passcode ${passcode} and discriminator ${discriminator}...`);
+        /**
+         * Create a Matter ServerNode, which contains the Root Endpoint and all relevant data and configuration
+         */
         const serverNode = await ServerNode.create({
+            // Required: Give the Node a unique ID which is used to store the state of this node
             id: storeId,
+            // Provide the environment to run this node in
             environment: this.environment,
+            // Provide Network relevant configuration like the port
             network: {
                 listeningAddressIpv4: this.ipv4Address,
                 listeningAddressIpv6: this.ipv6Address,
                 port,
             },
+            // Provide the certificate for the device
             operationalCredentials: {
                 certification: this.certification,
             },
+            // Provide Commissioning relevant settings
             commissioning: {
                 passcode,
                 discriminator,
             },
+            // Provide Node announcement settings
             productDescription: {
                 name: await this.matterStorageContext.get('deviceName'),
                 deviceType: DeviceTypeId(await this.matterStorageContext.get('deviceType')),
                 vendorId: VendorId(await this.matterStorageContext.get('vendorId')),
                 productId: await this.matterStorageContext.get('productId'),
             },
+            // Provide defaults for the BasicInformation cluster on the Root endpoint
             basicInformation: {
                 vendorId: VendorId(await this.matterStorageContext.get('vendorId')),
                 vendorName: await this.matterStorageContext.get('vendorName'),
@@ -396,17 +561,23 @@ export class MatterNode extends EventEmitter {
                 reachable: true,
             },
         });
+        /**
+         * This event is triggered when the device is initially commissioned successfully.
+         * This means: It is added to the first fabric.
+         */
         serverNode.lifecycle.commissioned.on(() => {
             this.log.notice(`Server node for ${storeId} was initially commissioned successfully!`);
             this.advertisingNodes.delete(storeId);
             this.server.request({ type: 'frontend_refreshrequired', src: 'matter', dst: 'frontend', params: { changed: 'matter', matter: { ...this.getServerNodeData(serverNode) } } });
         });
+        /** This event is triggered when all fabrics are removed from the device, usually it also does a factory reset then. */
         serverNode.lifecycle.decommissioned.on(() => {
             this.log.notice(`Server node for ${storeId} was fully decommissioned successfully!`);
             this.advertisingNodes.delete(storeId);
             this.server.request({ type: 'frontend_refreshrequired', src: 'matter', dst: 'frontend', params: { changed: 'matter', matter: { ...this.getServerNodeData(serverNode) } } });
             this.server.request({ type: 'frontend_snackbarmessage', src: 'matter', dst: 'frontend', params: { message: `${storeId} is offline`, timeout: 5, severity: 'warning' } });
         });
+        /** This event is triggered when the device went online. This means that it is discoverable in the network. */
         serverNode.lifecycle.online.on(async () => {
             this.log.notice(`Server node for ${storeId} is online`);
             if (!serverNode.lifecycle.isCommissioned) {
@@ -424,6 +595,7 @@ export class MatterNode extends EventEmitter {
             this.server.request({ type: 'frontend_snackbarmessage', src: 'matter', dst: 'frontend', params: { message: `${storeId} is online`, timeout: 5, severity: 'success' } });
             this.emit('online', storeId);
         });
+        /** This event is triggered when the device went offline. it is not longer discoverable or connectable in the network. */
         serverNode.lifecycle.offline.on(() => {
             this.log.notice(`Server node for ${storeId} is offline`);
             this.advertisingNodes.delete(storeId);
@@ -431,11 +603,15 @@ export class MatterNode extends EventEmitter {
             this.server.request({ type: 'frontend_snackbarmessage', src: 'matter', dst: 'frontend', params: { message: `${storeId} is offline`, timeout: 5, severity: 'warning' } });
             this.emit('offline', storeId);
         });
+        /**
+         * This event is triggered when a fabric is added, removed or updated on the device. Use this if more granular
+         * information is needed.
+         */
         serverNode.events.commissioning.fabricsChanged.on((fabricIndex, fabricAction) => {
             let action = '';
             switch (fabricAction) {
                 case 'added':
-                    this.advertisingNodes.delete(storeId);
+                    this.advertisingNodes.delete(storeId); // The advertising stops when a fabric is added
                     action = 'added';
                     break;
                 case 'deleted':
@@ -448,14 +624,22 @@ export class MatterNode extends EventEmitter {
             this.log.notice(`Commissioned fabric index ${fabricIndex} ${action} on server node for ${storeId}: ${debugStringify(serverNode.state.commissioning.fabrics[fabricIndex])}`);
             this.server.request({ type: 'frontend_refreshrequired', src: 'matter', dst: 'frontend', params: { changed: 'matter', matter: { ...this.getServerNodeData(serverNode) } } });
         });
+        /**
+         * This event is triggered when an operative new session was opened by a Controller.
+         * It is not triggered for the initial commissioning process, just afterwards for real connections.
+         */
         serverNode.events.sessions.opened.on((session) => {
             this.log.notice(`Session opened on server node for ${storeId}: ${debugStringify(session)}`);
             this.server.request({ type: 'frontend_refreshrequired', src: 'matter', dst: 'frontend', params: { changed: 'matter', matter: { ...this.getServerNodeData(serverNode) } } });
         });
+        /**
+         * This event is triggered when an operative session is closed by a Controller or because the Device goes offline.
+         */
         serverNode.events.sessions.closed.on((session) => {
             this.log.notice(`Session closed on server node for ${storeId}: ${debugStringify(session)}`);
             this.server.request({ type: 'frontend_refreshrequired', src: 'matter', dst: 'frontend', params: { changed: 'matter', matter: { ...this.getServerNodeData(serverNode) } } });
         });
+        /** This event is triggered when a subscription gets added or removed on an operative session. */
         serverNode.events.sessions.subscriptionsChanged.on((session) => {
             this.log.notice(`Session subscriptions changed on server node for ${storeId}: ${debugStringify(session)}`);
             this.server.request({ type: 'frontend_refreshrequired', src: 'matter', dst: 'frontend', params: { changed: 'matter', matter: { ...this.getServerNodeData(serverNode) } } });
@@ -464,6 +648,12 @@ export class MatterNode extends EventEmitter {
         this.log.info(`Created server node for ${this.storeId}`);
         return serverNode;
     }
+    /**
+     * Gets the matter serializable data of the specified server node.
+     *
+     * @param {ServerNode} [serverNode] - The server node to start.
+     * @returns {ApiMatter} The serializable data of the server node.
+     */
     getServerNodeData(serverNode) {
         const advertiseTime = this.advertisingNodes.get(serverNode.id) || 0;
         return {
@@ -480,6 +670,13 @@ export class MatterNode extends EventEmitter {
             serialNumber: serverNode.state.basicInformation.serialNumber,
         };
     }
+    /**
+     * Starts the specified server node.
+     *
+     * @param {number} [timeout] - The timeout in milliseconds for starting the server node. Defaults to 30 seconds.
+     * @returns {Promise<void>} A promise that resolves when the server node has started.
+     * @throws {Error} If the server node is not created yet.
+     */
     async startServerNode(timeout = 30000) {
         if (!this.serverNode) {
             throw new Error('Matter server node not created yet. Call create() first.');
@@ -490,9 +687,17 @@ export class MatterNode extends EventEmitter {
             this.log.notice(`Started ${this.serverNode.id} server node`);
         }
         catch (error) {
+            // istanbul ignore next
             this.log.error(`Failed to start ${this.serverNode.id} server node: ${error instanceof Error ? error.message : error}`);
         }
     }
+    /**
+     * Stops the specified server node.
+     *
+     * @param {number} [timeout] - The timeout in milliseconds for stopping the server node. Defaults to 30 seconds.
+     * @returns {Promise<void>} A promise that resolves when the server node has stopped.
+     * @throws {Error} If the server node is not created yet.
+     */
     async stopServerNode(timeout = 30000) {
         if (!this.serverNode) {
             throw new Error('Matter server node not created yet. Call create() first.');
@@ -503,9 +708,16 @@ export class MatterNode extends EventEmitter {
             this.log.info(`Closed ${this.serverNode.id} server node`);
         }
         catch (error) {
+            // istanbul ignore next
             this.log.error(`Failed to close ${this.serverNode.id} server node: ${error instanceof Error ? error.message : error}`);
         }
     }
+    /**
+     * Creates an aggregator node with the specified storage context.
+     *
+     * @returns {Promise<Endpoint<AggregatorEndpoint>>} A promise that resolves to the created aggregator node.
+     * @throws {Error} If the matter storage context is not created yet.
+     */
     async createAggregatorNode() {
         if (!this.matterStorageContext) {
             throw new Error('Matter server node context not created yet. Call createServerNodeContext() first.');
@@ -515,9 +727,16 @@ export class MatterNode extends EventEmitter {
         this.log.info(`Created ${await this.matterStorageContext.get('storeId')} aggregator`);
         return aggregatorNode;
     }
+    /**
+     * Creates the matterbridge server node.
+     *
+     * @returns {Promise<ServerNode<ServerNode.RootEndpoint>>} A promise that resolves to the created matterbridge server node.
+     */
     async createMatterbridgeServerNode() {
         this.log.debug(`Creating ${plg}Matterbridge${db} server node...`);
-        this.matterStorageContext = await this.createServerNodeContext('Matterbridge', 'Matterbridge', this.aggregatorDeviceType, this.aggregatorVendorId, this.aggregatorVendorName, this.aggregatorProductId, this.aggregatorProductName, this.aggregatorSerialNumber, this.aggregatorUniqueId);
+        this.matterStorageContext = await this.createServerNodeContext('Matterbridge', // storeId
+        'Matterbridge', // deviceName
+        this.aggregatorDeviceType, this.aggregatorVendorId, this.aggregatorVendorName, this.aggregatorProductId, this.aggregatorProductName, this.aggregatorSerialNumber, this.aggregatorUniqueId);
         this.serverNode = await this.createServerNode(this.port ? this.port++ : undefined, this.passcode ? this.passcode++ : undefined, this.discriminator ? this.discriminator++ : undefined);
         this.aggregatorNode = await this.createAggregatorNode();
         this.log.debug(`Adding ${plg}Matterbridge${db} aggregator node...`);
@@ -528,6 +747,13 @@ export class MatterNode extends EventEmitter {
         this.log.debug(`Created ${plg}Matterbridge${db} server node`);
         return this.serverNode;
     }
+    /**
+     * Creates and configures the server node for an accessory plugin for a given device.
+     *
+     * @param {Plugin | PluginName} plugin - The plugin to configure.
+     * @param {MatterbridgeEndpoint} device - The device to associate with the plugin.
+     * @returns {Promise<ServerNode<ServerNode.RootEndpoint> | undefined>} A promise that resolves to the server node for the accessory plugin.
+     */
     async createAccessoryPlugin(plugin, device) {
         if (typeof plugin === 'string') {
             const _plugin = this.pluginManager.get(plugin);
@@ -549,6 +775,12 @@ export class MatterNode extends EventEmitter {
         }
         return this.serverNode;
     }
+    /**
+     * Creates and configures the server node and the aggregator node for a dynamic plugin.
+     *
+     * @param {Plugin | PluginName} plugin - The plugin to configure.
+     * @returns {Promise<ServerNode<ServerNode.RootEndpoint> | undefined>} A promise that resolves to the server node for the dynamic plugin.
+     */
     async createDynamicPlugin(plugin) {
         if (typeof plugin === 'string') {
             const _plugin = this.pluginManager.get(plugin);
@@ -572,6 +804,13 @@ export class MatterNode extends EventEmitter {
         }
         return this.serverNode;
     }
+    /**
+     * Creates and configures the server node for a single not bridged device.
+     *
+     * @param {Plugin | PluginName} plugin - The plugin to configure.
+     * @param {MatterbridgeEndpoint} device - The device to associate with the plugin.
+     * @returns {Promise<ServerNode<ServerNode.RootEndpoint> | undefined>} A promise that resolves to the server node for the device with mode server.
+     */
     async createDeviceServerNode(plugin, device) {
         if (typeof plugin === 'string') {
             const _plugin = this.pluginManager.get(plugin);
@@ -592,13 +831,22 @@ export class MatterNode extends EventEmitter {
         }
         return this.serverNode;
     }
+    /**
+     * Adds a MatterbridgeEndpoint to the specified plugin.
+     *
+     * @param {string} pluginName - The name of the plugin.
+     * @param {MatterbridgeEndpoint} device - The device to add as a bridged endpoint.
+     * @returns {Promise<MatterbridgeEndpoint | undefined>} A promise that resolves to the added bridged endpoint, or undefined if there was an error.
+     */
     async addBridgedEndpoint(pluginName, device) {
+        // Check if the plugin is registered
         const plugin = this.pluginManager.get(pluginName);
         if (!plugin)
             throw new Error(`Error adding bridged endpoint ${plg}${pluginName}${er}:${dev}${device.deviceName}${er} (${zb}${device.name}${er}): plugin not found`);
         if (device.mode === 'server') {
             try {
                 this.log.debug(`Creating MatterNode for device ${plg}${pluginName}${db}:${dev}${device.deviceName}${db} (${zb}${device.name}${db})...`);
+                // Create the MatterNode to manage the device
                 const matterNode = new MatterNode(this.matterbridge, pluginName, device);
                 matterNode.port = this.port ? this.port++ : undefined;
                 matterNode.passcode = this.passcode ? this.passcode++ : undefined;
@@ -614,6 +862,7 @@ export class MatterNode extends EventEmitter {
         }
         else if (this.matterbridge.bridgeMode === 'bridge') {
             if (device.mode === 'matter') {
+                // Register and add the device to the Matter server node
                 this.log.debug(`Adding matter endpoint ${plg}${pluginName}${db}:${dev}${device.deviceName}${db} (${zb}${device.name}${db})...`);
                 if (!this.serverNode)
                     throw new Error(`Server node not found for matter endpoint ${plg}${pluginName}${er}:${dev}${device.deviceName}${er} (${zb}${device.name}${er})`);
@@ -626,6 +875,7 @@ export class MatterNode extends EventEmitter {
                 }
             }
             else {
+                // Register and add the device to the Matter aggregator node
                 this.log.debug(`Adding bridged endpoint ${plg}${pluginName}${db}:${dev}${device.deviceName}${db} (${zb}${device.name}${db})...`);
                 if (!this.aggregatorNode)
                     throw new Error(`Aggregator node not found for endpoint ${plg}${pluginName}${er}:${dev}${device.deviceName}${er} (${zb}${device.name}${er})`);
@@ -639,6 +889,7 @@ export class MatterNode extends EventEmitter {
             }
         }
         else if (this.matterbridge.bridgeMode === 'childbridge') {
+            // Register and add the device to the plugin server node
             if (plugin.type === 'AccessoryPlatform') {
                 try {
                     this.log.debug(`Adding accessory endpoint ${plg}${pluginName}${db}:${dev}${device.deviceName}${db} (${zb}${device.name}${db})...`);
@@ -654,10 +905,12 @@ export class MatterNode extends EventEmitter {
                     return;
                 }
             }
+            // Register and add the device to the plugin aggregator node
             if (plugin.type === 'DynamicPlatform') {
                 try {
                     this.log.debug(`Adding bridged endpoint ${plg}${pluginName}${db}:${dev}${device.deviceName}${db} (${zb}${device.name}${db})...`);
                     if (!this.serverNode) {
+                        // Fast plugins can add another device before the server node is ready, so we wait for the server node to be ready
                         await this.createDynamicPlugin(plugin);
                     }
                     if (device.mode === 'matter')
@@ -673,19 +926,31 @@ export class MatterNode extends EventEmitter {
         }
         if (plugin.registeredDevices !== undefined)
             plugin.registeredDevices++;
+        // Add the device to the DeviceManager
         await this.server.fetch({ type: 'devices_set', src: this.server.name, dst: 'devices', params: { device: toBaseDevice(device) } });
+        // Add the device to the DeviceManager
         await device.construction.ready;
+        // Subscribe to the attributes changed event
         await this.subscribeAttributeChanged(plugin, device);
         this.log.info(`Added endpoint #${plugin.registeredDevices} ${plg}${pluginName}${nf}:${dev}${device.deviceName}${nf} (${zb}${device.name}${nf})`);
         await this.yieldToNode(10);
         return device;
     }
+    /**
+     * Removes a MatterbridgeEndpoint from the specified plugin.
+     *
+     * @param {string} pluginName - The name of the plugin.
+     * @param {MatterbridgeEndpoint} device - The device to remove as a bridged endpoint.
+     * @returns {Promise<MatterbridgeEndpoint | undefined>} A promise that resolves to the removed bridged endpoint, or undefined if there was an error.
+     */
     async removeBridgedEndpoint(pluginName, device) {
         this.log.debug(`Removing bridged endpoint ${plg}${pluginName}${db}:${dev}${device.deviceName}${db} (${zb}${device.name}${db})...`);
+        // Check if the plugin is registered
         const plugin = this.pluginManager.get(pluginName);
         if (!plugin)
             throw new Error(`Error removing bridged endpoint ${plg}${pluginName}${er}:${dev}${device.deviceName}${er} (${zb}${device.name}${er}): plugin not found`);
         if (device.serverNode) {
+            // TODO: Close and remove the MatterNode managing the device
         }
         else if (this.matterbridge.bridgeMode === 'bridge') {
             if (!this.aggregatorNode)
@@ -707,11 +972,25 @@ export class MatterNode extends EventEmitter {
         this.log.info(`Removed bridged endpoint #${plugin.registeredDevices} ${plg}${pluginName}${nf}:${dev}${device.deviceName}${nf} (${zb}${device.name}${nf})`);
         if (plugin.registeredDevices !== undefined)
             plugin.registeredDevices--;
+        // Remove the device from the DeviceManager
         await this.server.fetch({ type: 'devices_remove', src: this.server.name, dst: 'devices', params: { device: toBaseDevice(device) } });
         await this.yieldToNode(10);
         return device;
     }
+    /**
+     * Removes all bridged endpoints from the specified plugin.
+     *
+     * @param {string} pluginName - The name of the plugin.
+     * @param {number} [delay] - The delay in milliseconds between removing each bridged endpoint (default: 0).
+     * @returns {Promise<void>} A promise that resolves when all bridged endpoints have been removed.
+     *
+     * @remarks
+     * This method iterates through all devices in the DeviceManager and removes each bridged endpoint associated with the specified plugin.
+     * It also applies a delay between each removal if specified.
+     * The delay is useful to allow the controllers to receive a single subscription for each device removed.
+     */
     async removeAllBridgedEndpoints(pluginName, delay = 0) {
+        // Check if the plugin is registered
         const plugin = this.pluginManager.get(pluginName);
         if (!plugin)
             throw new Error(`Error removing all bridged endpoints for plugin ${plg}${pluginName}${er}: plugin not found`);
@@ -726,6 +1005,7 @@ export class MatterNode extends EventEmitter {
             this.log.info(`Removed bridged endpoint #${plugin.registeredDevices} ${plg}${pluginName}${nf}:${dev}${device.deviceName}${nf} (${zb}${endpoint?.name}${nf})`);
             if (plugin.registeredDevices !== undefined)
                 plugin.registeredDevices--;
+            // Remove the device from the DeviceManager
             await this.server.fetch({ type: 'devices_remove', src: this.server.name, dst: 'devices', params: { device: toBaseDevice(device) } });
             await this.yieldToNode(10);
             if (delay > 0)
@@ -734,6 +1014,25 @@ export class MatterNode extends EventEmitter {
         if (delay > 0)
             await wait(Number(process.env['MATTERBRIDGE_REMOVE_ALL_ENDPOINT_TIMEOUT_MS']) || 2000);
     }
+    /**
+     * Registers a virtual device with the Matterbridge platform.
+     * Virtual devices are only supported in bridge mode and childbridge mode with a DynamicPlatform.
+     *
+     * The virtual device is created as an instance of `Endpoint` with the provided device type.
+     * When the virtual device is turned on, the provided callback function is executed.
+     * The onOff state of the virtual device always reverts to false when the device is turned on.
+     *
+     * @param {string} pluginName - The name of the plugin.
+     * @param { string } name - The name of the virtual device.
+     * @param { 'light' | 'outlet' | 'switch' | 'mounted_switch' } type - The type of the virtual device.
+     * @param { () => Promise<void> } callback - The callback to call when the virtual device is turned on.
+     *
+     * @returns {Promise<boolean>} A promise that resolves to true if the virtual device was successfully registered, false otherwise.
+     *
+     * @remarks
+     * The virtual devices don't show up in the device list of the frontend.
+     * Type 'switch' is not supported by Alexa and 'mounted_switch' is not supported by Apple Home.
+     */
     async addVirtualEndpoint(pluginName, name, type, callback) {
         this.log.debug(`Creating virtual device ${plg}${pluginName}${db}:${dev}${name}${db}...`);
         const plugin = this.pluginManager.get(pluginName);
@@ -758,10 +1057,20 @@ export class MatterNode extends EventEmitter {
         await this.yieldToNode(10);
         return true;
     }
+    /**
+     * Subscribes to the attribute change event for the given device and plugin.
+     * Specifically, it listens for changes in the 'reachable' attribute of the
+     * BridgedDeviceBasicInformationServer cluster server of the bridged device or BasicInformationServer cluster server of server node.
+     *
+     * @param {Plugin} plugin - The plugin associated with the device.
+     * @param {MatterbridgeEndpoint} device - The device to subscribe to attribute changes for.
+     * @returns {Promise<void>} A promise that resolves when the subscription is set up.
+     */
     async subscribeAttributeChanged(plugin, device) {
         if (!plugin || !device || !device.plugin || !device.serialNumber || !device.uniqueId || !device.maybeNumber)
             return;
         this.log.debug(`Subscribing attributes for endpoint ${plg}${plugin.name}${db}:${dev}${device.deviceName}${db}:${or}${device.id}${db}:${or}${device.number}${db} (${zb}${device.name}${db})`);
+        // Subscribe to the reachable$Changed event of the BasicInformationServer cluster server of the server node in childbridge mode
         if (this.matterbridge.bridgeMode === 'childbridge' && plugin.type === 'AccessoryPlatform' && this.serverNode) {
             this.serverNode.eventsOf(BasicInformationServer).reachable$Changed?.on((reachable) => {
                 this.log.debug(`Accessory endpoint ${plg}${plugin.name}${nf}:${dev}${device.deviceName}${nf}:${or}${device.id}${nf}:${or}${device.number}${nf} is ${reachable ? 'reachable' : 'unreachable'}`);
@@ -769,6 +1078,7 @@ export class MatterNode extends EventEmitter {
                     type: 'frontend_attributechanged',
                     src: 'matter',
                     dst: 'frontend',
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                     params: { plugin: device.plugin, serialNumber: device.serialNumber, uniqueId: device.uniqueId, number: device.number, id: device.id, cluster: 'BasicInformation', attribute: 'reachable', value: reachable },
                 });
             });
@@ -821,6 +1131,7 @@ export class MatterNode extends EventEmitter {
                         type: 'frontend_attributechanged',
                         src: 'matter',
                         dst: 'frontend',
+                        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                         params: { plugin: device.plugin, serialNumber: device.serialNumber, uniqueId: device.uniqueId, number: device.number, id: device.id, cluster: sub.cluster, attribute: sub.attribute, value: value },
                     });
                 });
@@ -834,6 +1145,7 @@ export class MatterNode extends EventEmitter {
                             type: 'frontend_attributechanged',
                             src: 'matter',
                             dst: 'frontend',
+                            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                             params: { plugin: device.plugin, serialNumber: device.serialNumber, uniqueId: device.uniqueId, number: child.number, id: child.id, cluster: sub.cluster, attribute: sub.attribute, value: value },
                         });
                     });
@@ -841,6 +1153,12 @@ export class MatterNode extends EventEmitter {
             }
         }
     }
+    /**
+     * Sanitizes the fabric information by converting bigint properties to strings because `res.json` doesn't support bigint.
+     *
+     * @param {ExposedFabricInformation[]} fabricInfo - The array of exposed fabric information objects.
+     * @returns {SanitizedExposedFabricInformation[]} An array of sanitized exposed fabric information objects.
+     */
     sanitizeFabricInformations(fabricInfo) {
         return fabricInfo.map((info) => {
             return {
@@ -854,6 +1172,12 @@ export class MatterNode extends EventEmitter {
             };
         });
     }
+    /**
+     * Sanitizes the session information by converting bigint properties to strings because `res.json` doesn't support bigint.
+     *
+     * @param {SessionsBehavior.Session[]} sessions - The array of session information objects.
+     * @returns {SanitizedSession[]} An array of sanitized session information objects.
+     */
     sanitizeSessionInformation(sessions) {
         return sessions
             .filter((session) => session.isPeerActive)
@@ -880,10 +1204,21 @@ export class MatterNode extends EventEmitter {
             };
         });
     }
+    /**
+     * Sets the reachability of the specified server node and trigger the corresponding event.
+     *
+     * @param {boolean} reachable - A boolean indicating the reachability status to set.
+     */
     async setServerReachability(reachable) {
         await this.serverNode?.setStateOf(BasicInformationServer, { reachable });
         this.serverNode?.act((agent) => this.serverNode?.eventsOf(BasicInformationServer).reachableChanged?.emit({ reachableNewValue: reachable }, agent.context));
     }
+    /**
+     * Sets the reachability of the specified aggregator node bridged devices and trigger.
+     *
+     * @param {Endpoint<AggregatorEndpoint>} aggregatorNode - The aggregator node to set the reachability for.
+     * @param {boolean} reachable - A boolean indicating the reachability status to set.
+     */
     async setAggregatorReachability(aggregatorNode, reachable) {
         for (const child of aggregatorNode.parts) {
             this.log.debug(`Setting reachability of ${child?.deviceName} to ${reachable}`);
@@ -929,19 +1264,35 @@ export class MatterNode extends EventEmitter {
             case 0x1488:
                 vendorName = '(ShortcutLabsFlic)';
                 break;
-            case 65521:
+            case 65521: // 0xFFF1
                 vendorName = '(MatterTest)';
                 break;
         }
         return vendorName;
     };
+    /**
+     * Yield to the Node.js event loop:
+     * 1. Flushes the current microtask queue (Promise/async continuations queued so far).
+     * 2. Yields one macrotask turn (setImmediate) and then its microtasks.
+     * 3. Waits a bit (setTimeout) to allow other macrotasks to run.
+     *
+     * This does **not** guarantee that every promise in the process is settled,
+     * but it gives all already-scheduled work a very good chance to run before continuing.
+     *
+     * @param {number} [timeout] - Optional timeout in milliseconds to wait after yielding. Default is 100 ms (minimum 10 ms).
+     * @returns {Promise<void>}
+     */
     async yieldToNode(timeout = 100) {
+        // 1. Let all currently queued microtasks run
         await Promise.resolve();
+        // 2. Yield to the next event-loop turn (macrotask + its microtasks)
         await new Promise((resolve) => {
             setImmediate(resolve);
         });
+        // 3. Pause a bit to allow other macrotasks to run
         await new Promise((resolve) => {
             setTimeout(resolve, Math.min(timeout, 10));
         });
     }
 }
+//# sourceMappingURL=matterNode.js.map