matterbridge 3.0.3-dev-20250520-e6e7257 → 3.0.3

package/dist/matterbridge.js

@@ -1,10 +1,36 @@
+/**
+ * This file contains the class Matterbridge.
+ *
+ * @file matterbridge.ts
+ * @author Luca Liguori
+ * @date 2023-12-29
+ * @version 1.5.3
+ *
+ * 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. *
+ */
+// Node.js modules
 import os from 'node:os';
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import EventEmitter from 'node:events';
 import { inspect } from 'node:util';
+// AnsiLogger module
 import { AnsiLogger, UNDERLINE, UNDERLINEOFF, YELLOW, db, debugStringify, BRIGHT, RESET, er, nf, rs, wr, RED, GREEN, zb, CYAN } from './logger/export.js';
+// NodeStorage module
 import { NodeStorageManager } from './storage/export.js';
+// Matterbridge
 import { getParameter, getIntParameter, hasParameter, copyDirectory, withTimeout, waiter, isValidString, parseVersionString, isValidNumber } from './utils/export.js';
 import { logInterfaces, getGlobalNodeModules } from './utils/network.js';
 import { dev, plg, typ } from './matterbridgeTypes.js';
@@ -14,11 +40,15 @@ import { MatterbridgeEndpoint } from './matterbridgeEndpoint.js';
 import { bridge } from './matterbridgeDeviceTypes.js';
 import { Frontend } from './frontend.js';
 import { addVirtualDevices } from './helpers.js';
+// @matter
 import { DeviceTypeId, Endpoint, Logger, LogLevel as MatterLogLevel, LogFormat as MatterLogFormat, VendorId, StorageService, Environment, ServerNode, UINT32_MAX, UINT16_MAX, } from '@matter/main';
 import { DeviceCommissioner, FabricAction, MdnsService, PaseClient } from '@matter/main/protocol';
 import { AggregatorEndpoint } from '@matter/main/endpoints';
 import { BasicInformationServer } from '@matter/main/behaviors/basic-information';
 import { BridgedDeviceBasicInformationServer } from '@matter/main/behaviors/bridged-device-basic-information';
+/**
+ * Represents the Matterbridge application.
+ */
 export class Matterbridge extends EventEmitter {
     systemInformation = {
         interfaceName: '',
@@ -66,7 +96,7 @@ export class Matterbridge extends EventEmitter {
         shellySysUpdate: false,
         shellyMainUpdate: false,
         profile: getParameter('profile'),
-        loggerLevel: "info",
+        loggerLevel: "info" /* LogLevel.INFO */,
         fileLogger: false,
         matterLoggerLevel: MatterLogLevel.INFO,
         matterFileLogger: false,
@@ -105,9 +135,11 @@ export class Matterbridge extends EventEmitter {
     plugins;
     devices;
     frontend = new Frontend(this);
+    // Matterbridge storage
     nodeStorage;
     nodeContext;
     nodeStorageName = 'storage' + (getParameter('profile') ? '.' + getParameter('profile') : '');
+    // Cleanup
     hasCleanupStarted = false;
     initialized = false;
     execRunningCount = 0;
@@ -120,19 +152,22 @@ export class Matterbridge extends EventEmitter {
     sigtermHandler;
     exceptionHandler;
     rejectionHandler;
+    // Matter environment
     environment = Environment.default;
+    // Matter storage
     matterStorageName = 'matterstorage' + (getParameter('profile') ? '.' + getParameter('profile') : '');
     matterStorageService;
     matterStorageManager;
     matterbridgeContext;
     controllerContext;
-    mdnsInterface;
-    ipv4address;
-    ipv6address;
-    port;
-    passcode;
-    discriminator;
-    certification;
+    // Matter parameters
+    mdnsInterface; // matter server node mdnsInterface: e.g. 'eth0' or 'wlan0' or 'WiFi'
+    ipv4address; // matter server node listeningAddressIpv4
+    ipv6address; // matter server node listeningAddressIpv6
+    port; // first server node port
+    passcode; // first server node passcode
+    discriminator; // first server node discriminator
+    certification; // device certification
     serverNode;
     aggregatorNode;
     aggregatorVendorId = VendorId(getIntParameter('vendorId') ?? 0xfff1);
@@ -140,21 +175,50 @@ export class Matterbridge extends EventEmitter {
     aggregatorProductId = getIntParameter('productId') ?? 0x8000;
     aggregatorProductName = getParameter('productName') ?? 'Matterbridge aggregator';
     static instance;
+    // We load asyncronously so is private
     constructor() {
         super();
     }
+    /**
+     * Emits an event of the specified type with the provided arguments.
+     *
+     * @template K - The type of the event.
+     * @param {K} eventName - The name of the event to emit.
+     * @param {...MatterbridgeEvent[K]} args - The arguments to pass to the event listeners.
+     * @returns {boolean} - Returns true if the event had listeners, false otherwise.
+     */
     emit(eventName, ...args) {
         return super.emit(eventName, ...args);
     }
+    /**
+     * Registers an event listener for the specified event type.
+     *
+     * @template K - The type of the event.
+     * @param {K} eventName - The name of the event to listen for.
+     * @param {(...args: MatterbridgeEvent[K]) => void} listener - The callback function to invoke when the event is emitted.
+     * @returns {this} - Returns the instance of the Matterbridge class.
+     */
     on(eventName, listener) {
         return super.on(eventName, listener);
     }
+    /**
+     * Retrieves the list of Matterbridge devices.
+     * @returns {MatterbridgeEndpoint[]} An array of MatterbridgeDevice objects.
+     */
     getDevices() {
         return this.devices.array();
     }
+    /**
+     * Retrieves the list of registered plugins.
+     * @returns {RegisteredPlugin[]} An array of RegisteredPlugin objects.
+     */
     getPlugins() {
         return this.plugins.array();
     }
+    /**
+     * Set the logger logLevel for the Matterbridge classes and call onChangeLoggerLevel() for each plugin.
+     * @param {LogLevel} logLevel The logger logLevel to set.
+     */
     async setLogLevel(logLevel) {
         if (this.log)
             this.log.logLevel = logLevel;
@@ -168,19 +232,31 @@ export class Matterbridge extends EventEmitter {
         for (const plugin of this.plugins) {
             if (!plugin.platform || !plugin.platform.log || !plugin.platform.config)
                 continue;
-            plugin.platform.log.logLevel = plugin.platform.config.debug === true ? "debug" : this.log.logLevel;
-            await plugin.platform.onChangeLoggerLevel(plugin.platform.config.debug === true ? "debug" : this.log.logLevel);
-        }
-        let callbackLogLevel = "notice";
-        if (this.matterbridgeInformation.loggerLevel === "info" || this.matterbridgeInformation.matterLoggerLevel === MatterLogLevel.INFO)
-            callbackLogLevel = "info";
-        if (this.matterbridgeInformation.loggerLevel === "debug" || this.matterbridgeInformation.matterLoggerLevel === MatterLogLevel.DEBUG)
-            callbackLogLevel = "debug";
+            plugin.platform.log.logLevel = plugin.platform.config.debug === true ? "debug" /* LogLevel.DEBUG */ : this.log.logLevel;
+            await plugin.platform.onChangeLoggerLevel(plugin.platform.config.debug === true ? "debug" /* LogLevel.DEBUG */ : this.log.logLevel);
+        }
+        // Set the global logger callback for the WebSocketServer to the common minimum logLevel
+        let callbackLogLevel = "notice" /* LogLevel.NOTICE */;
+        if (this.matterbridgeInformation.loggerLevel === "info" /* LogLevel.INFO */ || this.matterbridgeInformation.matterLoggerLevel === MatterLogLevel.INFO)
+            callbackLogLevel = "info" /* LogLevel.INFO */;
+        if (this.matterbridgeInformation.loggerLevel === "debug" /* LogLevel.DEBUG */ || this.matterbridgeInformation.matterLoggerLevel === MatterLogLevel.DEBUG)
+            callbackLogLevel = "debug" /* LogLevel.DEBUG */;
         AnsiLogger.setGlobalCallback(this.frontend.wssSendMessage.bind(this.frontend), callbackLogLevel);
         this.log.debug(`WebSocketServer logger global callback set to ${callbackLogLevel}`);
     }
+    /** ***********************************************************************************************************************************/
+    /**                                              loadInstance() and cleanup() methods                                                 */
+    /** ***********************************************************************************************************************************/
+    /**
+     * Loads an instance of the Matterbridge class.
+     * If an instance already exists, return that instance.
+     *
+     * @param {boolean} initialize - Whether to initialize the Matterbridge instance after loading. Defaults to false.
+     * @returns The loaded Matterbridge instance.
+     */
     static async loadInstance(initialize = false) {
         if (!Matterbridge.instance) {
+            // eslint-disable-next-line no-console
             if (hasParameter('debug'))
                 console.log(GREEN + 'Creating a new instance of Matterbridge.', initialize ? 'Initializing...' : 'Not initializing...', rs);
             Matterbridge.instance = new Matterbridge();
@@ -189,8 +265,14 @@ export class Matterbridge extends EventEmitter {
         }
         return Matterbridge.instance;
     }
+    /**
+     * Call cleanup().
+     * @deprecated This method is deprecated and is only used for jest tests.
+     *
+     */
     async destroyInstance() {
         this.log.info(`Destroy instance...`);
+        // Save server nodes to close
         const servers = [];
         if (this.bridgeMode === 'bridge') {
             if (this.serverNode)
@@ -202,72 +284,103 @@ export class Matterbridge extends EventEmitter {
                     servers.push(plugin.serverNode);
             }
         }
+        // Cleanup
         await this.cleanup('destroying instance...', false);
+        // Close servers mdns service
         this.log.info(`Dispose ${servers.length} MdnsService...`);
         for (const server of servers) {
             await server.env.get(MdnsService)[Symbol.asyncDispose]();
             this.log.info(`Closed ${server.id} MdnsService`);
         }
+        // Wait for the cleanup to finish
         await new Promise((resolve) => {
             setTimeout(resolve, 500);
         });
     }
+    /**
+     * Initializes the Matterbridge application.
+     *
+     * @remarks
+     * This method performs the necessary setup and initialization steps for the Matterbridge application.
+     * It displays the help information if the 'help' parameter is provided, sets up the logger, checks the
+     * node version, registers signal handlers, initializes storage, and parses the command line.
+     *
+     * @returns A Promise that resolves when the initialization is complete.
+     */
     async initialize() {
+        // Emit the initialize_started event
         this.emit('initialize_started');
-        this.log = new AnsiLogger({ logName: 'Matterbridge', logTimestampFormat: 4, logLevel: hasParameter('debug') ? "debug" : "info" });
+        // Create the matterbridge logger
+        this.log = new AnsiLogger({ logName: 'Matterbridge', logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: hasParameter('debug') ? "debug" /* LogLevel.DEBUG */ : "info" /* LogLevel.INFO */ });
+        // Set the restart mode
         if (hasParameter('service'))
             this.restartMode = 'service';
         if (hasParameter('docker'))
             this.restartMode = 'docker';
+        // Set the matterbridge home directory
         this.homeDirectory = getParameter('homedir') ?? os.homedir();
         this.matterbridgeInformation.homeDirectory = this.homeDirectory;
         await this.createDirectory(this.homeDirectory, 'Matterbridge Home Directory');
+        // Set the matterbridge directory
         this.matterbridgeDirectory = path.join(this.homeDirectory, '.matterbridge');
         this.matterbridgeInformation.matterbridgeDirectory = this.matterbridgeDirectory;
         await this.createDirectory(this.matterbridgeDirectory, 'Matterbridge Directory');
         await this.createDirectory(path.join(this.matterbridgeDirectory, 'certs'), 'Matterbridge Frontend Certificate Directory');
         await this.createDirectory(path.join(this.matterbridgeDirectory, 'uploads'), 'Matterbridge Frontend Uploads Directory');
+        // Set the matterbridge plugin directory
         this.matterbridgePluginDirectory = path.join(this.homeDirectory, 'Matterbridge');
         this.matterbridgeInformation.matterbridgePluginDirectory = this.matterbridgePluginDirectory;
         await this.createDirectory(this.matterbridgePluginDirectory, 'Matterbridge Plugin Directory');
+        // Set the matterbridge cert directory
         this.matterbridgeCertDirectory = path.join(this.homeDirectory, '.mattercert');
         this.matterbridgeInformation.matterbridgeCertDirectory = this.matterbridgeCertDirectory;
         await this.createDirectory(this.matterbridgeCertDirectory, 'Matterbridge Matter Certificate Directory');
+        // Set the matterbridge root directory
         const { fileURLToPath } = await import('node:url');
         const currentFileDirectory = path.dirname(fileURLToPath(import.meta.url));
         this.rootDirectory = path.resolve(currentFileDirectory, '../');
         this.matterbridgeInformation.rootDirectory = this.rootDirectory;
+        // Setup the matter environment
         this.environment.vars.set('log.level', MatterLogLevel.INFO);
         this.environment.vars.set('log.format', MatterLogFormat.ANSI);
         this.environment.vars.set('path.root', path.join(this.matterbridgeDirectory, this.matterStorageName));
         this.environment.vars.set('runtime.signals', false);
         this.environment.vars.set('runtime.exitcode', false);
+        // Register process handlers
         this.registerProcessHandlers();
+        // Initialize nodeStorage and nodeContext
         try {
             this.log.debug(`Creating node storage manager: ${CYAN}${this.nodeStorageName}${db}`);
             this.nodeStorage = new NodeStorageManager({ dir: path.join(this.matterbridgeDirectory, this.nodeStorageName), writeQueue: false, expiredInterval: undefined, logging: false });
             this.log.debug('Creating node storage context for matterbridge');
             this.nodeContext = await this.nodeStorage.createStorage('matterbridge');
+            // TODO: Remove this code when node-persist-manager is updated
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const keys = (await this.nodeStorage?.storage.keys());
             for (const key of keys) {
                 this.log.debug(`Checking node storage manager key: ${CYAN}${key}${db}`);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 await this.nodeStorage?.storage.get(key);
             }
             const storages = await this.nodeStorage.getStorageNames();
             for (const storage of storages) {
                 this.log.debug(`Checking storage: ${CYAN}${storage}${db}`);
                 const nodeContext = await this.nodeStorage?.createStorage(storage);
+                // TODO: Remove this code when node-persist-manager is updated
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 const keys = (await nodeContext?.storage.keys());
                 keys.forEach(async (key) => {
                     this.log.debug(`Checking key: ${CYAN}${storage}:${key}${db}`);
                     await nodeContext?.get(key);
                 });
             }
+            // Creating a backup of the node storage since it is not corrupted
             this.log.debug('Creating node storage backup...');
             await copyDirectory(path.join(this.matterbridgeDirectory, this.nodeStorageName), path.join(this.matterbridgeDirectory, this.nodeStorageName + '.backup'));
             this.log.debug('Created node storage backup');
         }
         catch (error) {
+            // Restoring the backup of the node storage since it is corrupted
             this.log.error(`Error creating node storage manager and context: ${error instanceof Error ? error.message : error}`);
             if (hasParameter('norestore')) {
                 this.log.fatal(`The matterbridge node storage is corrupted. Parameter -norestore found: exiting...`);
@@ -282,14 +395,19 @@ export class Matterbridge extends EventEmitter {
             this.log.fatal('Fatal error creating node storage manager and context for matterbridge');
             throw new Error('Fatal error creating node storage manager and context for matterbridge');
         }
+        // Set the first port to use for the commissioning server (will be incremented in childbridge mode)
         this.port = getIntParameter('port') ?? (await this.nodeContext.get('matterport', 5540)) ?? 5540;
+        // Set the first passcode to use for the commissioning server (will be incremented in childbridge mode)
         this.passcode = getIntParameter('passcode') ?? (await this.nodeContext.get('matterpasscode')) ?? PaseClient.generateRandomPasscode();
+        // Set the first discriminator to use for the commissioning server (will be incremented in childbridge mode)
         this.discriminator = getIntParameter('discriminator') ?? (await this.nodeContext.get('matterdiscriminator')) ?? PaseClient.generateRandomDiscriminator();
+        // Certificate management
         const pairingFilePath = path.join(this.matterbridgeCertDirectory, 'pairing.json');
         try {
             await fs.access(pairingFilePath, fs.constants.R_OK);
             const pairingFileContent = await fs.readFile(pairingFilePath, 'utf8');
             const pairingFileJson = JSON.parse(pairingFileContent);
+            // Set the vendorId, vendorName, productId and productName if they are present in the pairing file
             if (isValidNumber(pairingFileJson.vendorId))
                 this.aggregatorVendorId = VendorId(pairingFileJson.vendorId);
             if (isValidString(pairingFileJson.vendorName, 3))
@@ -298,16 +416,20 @@ export class Matterbridge extends EventEmitter {
                 this.aggregatorProductId = VendorId(pairingFileJson.productId);
             if (isValidString(pairingFileJson.productName, 3))
                 this.aggregatorProductName = pairingFileJson.productName;
+            // Override the passcode and discriminator if they are present in the pairing file
             if (isValidNumber(pairingFileJson.passcode) && isValidNumber(pairingFileJson.discriminator)) {
                 this.passcode = pairingFileJson.passcode;
                 this.discriminator = pairingFileJson.discriminator;
                 this.log.info(`Pairing file ${CYAN}${pairingFilePath}${nf} found. Using passcode ${CYAN}${this.passcode}${nf} and discriminator ${CYAN}${this.discriminator}${nf} from pairing file.`);
             }
+            // Set the certification if it is present in the pairing file
             if (pairingFileJson.privateKey && pairingFileJson.certificate && pairingFileJson.intermediateCertificate && pairingFileJson.declaration) {
                 const hexStringToUint8Array = (hexString) => {
                     const matches = hexString.match(/.{1,2}/g);
                     return matches ? new Uint8Array(matches.map((byte) => parseInt(byte, 16))) : new Uint8Array();
                 };
+                // const hexString = Buffer.from('Test string', 'utf-8').toString('hex');
+                // console.log(hexString, Buffer.from(hexStringToUint8Array(hexString)).toString('utf-8'));
                 this.certification = {
                     privateKey: hexStringToUint8Array(pairingFileJson.privateKey),
                     certificate: hexStringToUint8Array(pairingFileJson.certificate),
@@ -320,41 +442,44 @@ export class Matterbridge extends EventEmitter {
         catch (error) {
             this.log.debug(`Pairing file ${CYAN}${pairingFilePath}${db} not found: ${error instanceof Error ? error.message : error}`);
         }
+        // Store the passcode, discriminator and port in the node context
         await this.nodeContext.set('matterport', this.port);
         await this.nodeContext.set('matterpasscode', this.passcode);
         await this.nodeContext.set('matterdiscriminator', this.discriminator);
         this.log.debug(`Initializing server node for Matterbridge on port ${this.port} with passcode ${this.passcode} and discriminator ${this.discriminator}`);
+        // Set matterbridge logger level (context: matterbridgeLogLevel)
         if (hasParameter('logger')) {
             const level = getParameter('logger');
             if (level === 'debug') {
-                this.log.logLevel = "debug";
+                this.log.logLevel = "debug" /* LogLevel.DEBUG */;
             }
             else if (level === 'info') {
-                this.log.logLevel = "info";
+                this.log.logLevel = "info" /* LogLevel.INFO */;
             }
             else if (level === 'notice') {
-                this.log.logLevel = "notice";
+                this.log.logLevel = "notice" /* LogLevel.NOTICE */;
             }
             else if (level === 'warn') {
-                this.log.logLevel = "warn";
+                this.log.logLevel = "warn" /* LogLevel.WARN */;
             }
             else if (level === 'error') {
-                this.log.logLevel = "error";
+                this.log.logLevel = "error" /* LogLevel.ERROR */;
             }
             else if (level === 'fatal') {
-                this.log.logLevel = "fatal";
+                this.log.logLevel = "fatal" /* LogLevel.FATAL */;
             }
             else {
                 this.log.warn(`Invalid matterbridge logger level: ${level}. Using default level "info".`);
-                this.log.logLevel = "info";
+                this.log.logLevel = "info" /* LogLevel.INFO */;
             }
         }
         else {
-            this.log.logLevel = await this.nodeContext.get('matterbridgeLogLevel', this.matterbridgeInformation.shellyBoard ? "notice" : "info");
+            this.log.logLevel = await this.nodeContext.get('matterbridgeLogLevel', this.matterbridgeInformation.shellyBoard ? "notice" /* LogLevel.NOTICE */ : "info" /* LogLevel.INFO */);
         }
         this.frontend.logLevel = this.log.logLevel;
         MatterbridgeEndpoint.logLevel = this.log.logLevel;
         this.matterbridgeInformation.loggerLevel = this.log.logLevel;
+        // Create the file logger for matterbridge (context: matterbridgeFileLog)
         if (hasParameter('filelogger') || (await this.nodeContext.get('matterbridgeFileLog', false))) {
             AnsiLogger.setGlobalLogfile(path.join(this.matterbridgeDirectory, this.matterbrideLoggerFile), this.log.logLevel, true);
             this.matterbridgeInformation.fileLogger = true;
@@ -363,6 +488,7 @@ export class Matterbridge extends EventEmitter {
         this.log.debug(`Matterbridge logLevel: ${this.log.logLevel} fileLoger: ${this.matterbridgeInformation.fileLogger}.`);
         if (this.profile !== undefined)
             this.log.debug(`Matterbridge profile: ${this.profile}.`);
+        // Set matter.js logger level, format and logger (context: matterLogLevel)
         if (hasParameter('matterlogger')) {
             const level = getParameter('matterlogger');
             if (level === 'debug') {
@@ -394,6 +520,7 @@ export class Matterbridge extends EventEmitter {
         Logger.format = MatterLogFormat.ANSI;
         Logger.setLogger('default', this.createMatterLogger());
         this.matterbridgeInformation.matterLoggerLevel = Logger.defaultLogLevel;
+        // Create the file logger for matter.js (context: matterFileLog)
         if (hasParameter('matterfilelogger') || (await this.nodeContext.get('matterFileLog', false))) {
             this.matterbridgeInformation.matterFileLogger = true;
             Logger.addLogger('matterfilelogger', await this.createMatterFileLogger(path.join(this.matterbridgeDirectory, this.matterLoggerFile), true), {
@@ -402,6 +529,7 @@ export class Matterbridge extends EventEmitter {
             });
         }
         this.log.debug(`Matter logLevel: ${Logger.defaultLogLevel} fileLoger: ${this.matterbridgeInformation.matterFileLogger}.`);
+        // Log network interfaces
         const networkInterfaces = os.networkInterfaces();
         const availableAddresses = Object.entries(networkInterfaces);
         const availableInterfaces = Object.keys(networkInterfaces);
@@ -413,6 +541,7 @@ export class Matterbridge extends EventEmitter {
                 });
             }
         }
+        // Set the interface to use for matter server node mdnsInterface
         if (hasParameter('mdnsinterface')) {
             this.mdnsInterface = getParameter('mdnsinterface');
         }
@@ -421,6 +550,7 @@ export class Matterbridge extends EventEmitter {
             if (this.mdnsInterface === '')
                 this.mdnsInterface = undefined;
         }
+        // Validate mdnsInterface
         if (this.mdnsInterface) {
             if (!availableInterfaces.includes(this.mdnsInterface)) {
                 this.log.error(`Invalid mdnsInterface: ${this.mdnsInterface}. Available interfaces are: ${availableInterfaces.join(', ')}. Using all available interfaces.`);
@@ -433,6 +563,7 @@ export class Matterbridge extends EventEmitter {
         }
         if (this.mdnsInterface)
             this.environment.vars.set('mdns.networkInterface', this.mdnsInterface);
+        // Set the listeningAddressIpv4 for the matter commissioning server
         if (hasParameter('ipv4address')) {
             this.ipv4address = getParameter('ipv4address');
         }
@@ -441,6 +572,7 @@ export class Matterbridge extends EventEmitter {
             if (this.ipv4address === '')
                 this.ipv4address = undefined;
         }
+        // Validate ipv4address
         if (this.ipv4address) {
             let isValid = false;
             for (const [ifaceName, ifaces] of availableAddresses) {
@@ -456,6 +588,7 @@ export class Matterbridge extends EventEmitter {
                 await this.nodeContext.remove('matteripv4address');
             }
         }
+        // Set the listeningAddressIpv6 for the matter commissioning server
         if (hasParameter('ipv6address')) {
             this.ipv6address = getParameter('ipv6address');
         }
@@ -464,6 +597,7 @@ export class Matterbridge extends EventEmitter {
             if (this.ipv6address === '')
                 this.ipv6address = undefined;
         }
+        // Validate ipv6address
         if (this.ipv6address) {
             let isValid = false;
             for (const [ifaceName, ifaces] of availableAddresses) {
@@ -484,6 +618,7 @@ export class Matterbridge extends EventEmitter {
                 await this.nodeContext.remove('matteripv6address');
             }
         }
+        // Initialize the virtual mode
         if (hasParameter('novirtual')) {
             this.matterbridgeInformation.virtualMode = 'disabled';
             await this.nodeContext.set('virtualmode', 'disabled');
@@ -492,14 +627,19 @@ export class Matterbridge extends EventEmitter {
             this.matterbridgeInformation.virtualMode = (await this.nodeContext.get('virtualmode', 'outlet'));
         }
         this.log.debug(`Virtual mode ${this.matterbridgeInformation.virtualMode}.`);
+        // Initialize PluginManager
         this.plugins = new PluginManager(this);
         await this.plugins.loadFromStorage();
         this.plugins.logLevel = this.log.logLevel;
+        // Initialize DeviceManager
         this.devices = new DeviceManager(this, this.nodeContext);
         this.devices.logLevel = this.log.logLevel;
+        // Get the plugins from node storage and create the plugins node storage contexts
         for (const plugin of this.plugins) {
             const packageJson = await this.plugins.parse(plugin);
             if (packageJson === null && !hasParameter('add') && !hasParameter('remove') && !hasParameter('enable') && !hasParameter('disable') && !hasParameter('reset') && !hasParameter('factoryreset')) {
+                // Try to reinstall the plugin from npm (for Docker pull and external plugins)
+                // We don't do this when the add and other parameters are set because we shut down the process after adding the plugin
                 this.log.info(`Error parsing plugin ${plg}${plugin.name}${nf}. Trying to reinstall it from npm.`);
                 try {
                     await this.spawnCommand('npm', ['install', '-g', plugin.name, '--omit=dev', '--verbose']);
@@ -521,6 +661,7 @@ export class Matterbridge extends EventEmitter {
             await plugin.nodeContext.set('description', plugin.description);
             await plugin.nodeContext.set('author', plugin.author);
         }
+        // Log system info and create .matterbridge directory
         await this.logNodeAndSystemInfo();
         this.log.notice(`Matterbridge version ${this.matterbridgeVersion} ` +
             `${hasParameter('bridge') || (!hasParameter('childbridge') && (await this.nodeContext?.get('bridgeMode', '')) === 'bridge') ? 'mode bridge ' : ''}` +
@@ -528,6 +669,7 @@ export class Matterbridge extends EventEmitter {
             `${hasParameter('controller') ? 'mode controller ' : ''}` +
             `${this.restartMode !== '' ? 'restart mode ' + this.restartMode + ' ' : ''}` +
             `running on ${this.systemInformation.osType} (v.${this.systemInformation.osRelease}) platform ${this.systemInformation.osPlatform} arch ${this.systemInformation.osArch}`);
+        // Check node version and throw error
         const minNodeVersion = 18;
         const nodeVersion = process.versions.node;
         const versionMajor = parseInt(nodeVersion.split('.')[0]);
@@ -535,10 +677,17 @@ export class Matterbridge extends EventEmitter {
             this.log.error(`Node version ${versionMajor} is not supported. Please upgrade to ${minNodeVersion} or above.`);
             throw new Error(`Node version ${versionMajor} is not supported. Please upgrade to ${minNodeVersion} or above.`);
         }
+        // Parse command line
         await this.parseCommandLine();
+        // Emit the initialize_completed event
         this.emit('initialize_completed');
         this.initialized = true;
     }
+    /**
+     * Parses the command line arguments and performs the corresponding actions.
+     * @private
+     * @returns {Promise<void>} A promise that resolves when the command line arguments have been processed, or the process exits.
+     */
     async parseCommandLine() {
         if (hasParameter('help')) {
             this.log.info(`\nUsage: matterbridge [options]\n
@@ -660,6 +809,7 @@ export class Matterbridge extends EventEmitter {
             this.shutdown = true;
             return;
         }
+        // Start the matter storage and create the matterbridge context
         try {
             await this.startMatterStorage();
         }
@@ -667,12 +817,14 @@ export class Matterbridge extends EventEmitter {
             this.log.fatal(`Fatal error creating matter storage: ${error instanceof Error ? error.message : error}`);
             throw new Error(`Fatal error creating matter storage: ${error instanceof Error ? error.message : error}`);
         }
+        // Clear the matterbridge context if the reset parameter is set
         if (hasParameter('reset') && getParameter('reset') === undefined) {
             this.initialized = true;
             await this.shutdownProcessAndReset();
             this.shutdown = true;
             return;
         }
+        // Clear matterbridge plugin context if the reset parameter is set
         if (hasParameter('reset') && getParameter('reset') !== undefined) {
             this.log.debug(`Reset plugin ${getParameter('reset')}`);
             const plugin = this.plugins.get(getParameter('reset'));
@@ -697,30 +849,37 @@ export class Matterbridge extends EventEmitter {
             this.shutdown = true;
             return;
         }
+        // Initialize frontend
         if (getIntParameter('frontend') !== 0 || getIntParameter('frontend') === undefined)
             await this.frontend.start(getIntParameter('frontend'));
+        // Check in 30 seconds the latest and dev versions of matterbridge and the plugins
         this.checkUpdateTimeout = setTimeout(async () => {
             const { checkUpdates } = await import('./update.js');
             checkUpdates(this);
         }, 30 * 1000).unref();
+        // Check each 12 hours the latest and dev versions of matterbridge and the plugins
         this.checkUpdateInterval = setInterval(async () => {
             const { checkUpdates } = await import('./update.js');
             checkUpdates(this);
         }, 12 * 60 * 60 * 1000).unref();
+        // Start the matterbridge in mode test
         if (hasParameter('test')) {
             this.bridgeMode = 'bridge';
             MatterbridgeEndpoint.bridgeMode = 'bridge';
             return;
         }
+        // Start the matterbridge in mode controller
         if (hasParameter('controller')) {
             this.bridgeMode = 'controller';
             await this.startController();
             return;
         }
+        // Check if the bridge mode is set and start matterbridge in bridge mode if not set
         if (!hasParameter('bridge') && !hasParameter('childbridge') && (await this.nodeContext?.get('bridgeMode', '')) === '') {
             this.log.info('Setting default matterbridge start mode to bridge');
             await this.nodeContext?.set('bridgeMode', 'bridge');
         }
+        // Start matterbridge in bridge mode
         if (hasParameter('bridge') || (!hasParameter('childbridge') && (await this.nodeContext?.get('bridgeMode', '')) === 'bridge')) {
             this.bridgeMode = 'bridge';
             MatterbridgeEndpoint.bridgeMode = 'bridge';
@@ -728,6 +887,7 @@ export class Matterbridge extends EventEmitter {
             await this.startBridge();
             return;
         }
+        // Start matterbridge in childbridge mode
         if (hasParameter('childbridge') || (!hasParameter('bridge') && (await this.nodeContext?.get('bridgeMode', '')) === 'childbridge')) {
             this.bridgeMode = 'childbridge';
             MatterbridgeEndpoint.bridgeMode = 'childbridge';
@@ -736,10 +896,20 @@ export class Matterbridge extends EventEmitter {
             return;
         }
     }
+    /**
+     * Asynchronously loads and starts the registered plugins.
+     *
+     * This method is responsible for initializing and staarting all enabled plugins.
+     * It ensures that each plugin is properly loaded and started before the bridge starts.
+     *
+     * @returns {Promise<void>} A promise that resolves when all plugins have been loaded and started.
+     */
     async startPlugins() {
+        // Check, load and start the plugins
         for (const plugin of this.plugins) {
             plugin.configJson = await this.plugins.loadConfig(plugin);
             plugin.schemaJson = await this.plugins.loadSchema(plugin);
+            // Check if the plugin is available
             if (!(await this.plugins.resolve(plugin.path))) {
                 this.log.error(`Plugin ${plg}${plugin.name}${er} not found or not validated. Disabling it.`);
                 plugin.enabled = false;
@@ -759,10 +929,14 @@ export class Matterbridge extends EventEmitter {
             plugin.addedDevices = undefined;
             plugin.qrPairingCode = undefined;
             plugin.manualPairingCode = undefined;
-            this.plugins.load(plugin, true, 'Matterbridge is starting');
+            this.plugins.load(plugin, true, 'Matterbridge is starting'); // No await do it asyncronously
         }
         this.frontend.wssSendRefreshRequired('plugins');
     }
+    /**
+     * Registers the process handlers for uncaughtException, unhandledRejection, SIGINT and SIGTERM.
+     * When either of these signals are received, the cleanup method is called with an appropriate message.
+     */
     registerProcessHandlers() {
         this.log.debug(`Registering uncaughtException and unhandledRejection handlers...`);
         process.removeAllListeners('uncaughtException');
@@ -789,6 +963,9 @@ export class Matterbridge extends EventEmitter {
         };
         process.on('SIGTERM', this.sigtermHandler);
     }
+    /**
+     * Deregisters the process uncaughtException, unhandledRejection, SIGINT and SIGTERM signal handlers.
+     */
     deregisterProcessHandlers() {
         this.log.debug(`Deregistering uncaughtException and unhandledRejection handlers...`);
         if (this.exceptionHandler)
@@ -805,12 +982,17 @@ export class Matterbridge extends EventEmitter {
             process.off('SIGTERM', this.sigtermHandler);
         this.sigtermHandler = undefined;
     }
+    /**
+     * Logs the node and system information.
+     */
     async logNodeAndSystemInfo() {
+        // IP address information
         const networkInterfaces = os.networkInterfaces();
         this.systemInformation.interfaceName = '';
         this.systemInformation.ipv4Address = '';
         this.systemInformation.ipv6Address = '';
         for (const [interfaceName, interfaceDetails] of Object.entries(networkInterfaces)) {
+            // this.log.debug(`Checking interface: '${interfaceName}' for '${this.mdnsInterface}'`);
             if (this.mdnsInterface && interfaceName !== this.mdnsInterface)
                 continue;
             if (!interfaceDetails) {
@@ -836,19 +1018,22 @@ export class Matterbridge extends EventEmitter {
                 break;
             }
         }
+        // Node information
         this.systemInformation.nodeVersion = process.versions.node;
         const versionMajor = parseInt(this.systemInformation.nodeVersion.split('.')[0]);
         const versionMinor = parseInt(this.systemInformation.nodeVersion.split('.')[1]);
         const versionPatch = parseInt(this.systemInformation.nodeVersion.split('.')[2]);
+        // Host system information
         this.systemInformation.hostname = os.hostname();
         this.systemInformation.user = os.userInfo().username;
-        this.systemInformation.osType = os.type();
-        this.systemInformation.osRelease = os.release();
-        this.systemInformation.osPlatform = os.platform();
-        this.systemInformation.osArch = os.arch();
-        this.systemInformation.totalMemory = (os.totalmem() / 1024 / 1024 / 1024).toFixed(2) + ' GB';
-        this.systemInformation.freeMemory = (os.freemem() / 1024 / 1024 / 1024).toFixed(2) + ' GB';
-        this.systemInformation.systemUptime = (os.uptime() / 60 / 60).toFixed(2) + ' hours';
+        this.systemInformation.osType = os.type(); // "Windows_NT", "Darwin", etc.
+        this.systemInformation.osRelease = os.release(); // Kernel version
+        this.systemInformation.osPlatform = os.platform(); // "win32", "linux", "darwin", etc.
+        this.systemInformation.osArch = os.arch(); // "x64", "arm", etc.
+        this.systemInformation.totalMemory = (os.totalmem() / 1024 / 1024 / 1024).toFixed(2) + ' GB'; // Convert to GB
+        this.systemInformation.freeMemory = (os.freemem() / 1024 / 1024 / 1024).toFixed(2) + ' GB'; // Convert to GB
+        this.systemInformation.systemUptime = (os.uptime() / 60 / 60).toFixed(2) + ' hours'; // Convert to hours
+        // Log the system information
         this.log.debug('Host System Information:');
         this.log.debug(`- Hostname: ${this.systemInformation.hostname}`);
         this.log.debug(`- User: ${this.systemInformation.user}`);
@@ -864,14 +1049,17 @@ export class Matterbridge extends EventEmitter {
         this.log.debug(`- Total Memory: ${this.systemInformation.totalMemory}`);
         this.log.debug(`- Free Memory: ${this.systemInformation.freeMemory}`);
         this.log.debug(`- System Uptime: ${this.systemInformation.systemUptime}`);
+        // Log directories
         this.log.debug(`Root Directory: ${this.rootDirectory}`);
         this.log.debug(`Home Directory: ${this.homeDirectory}`);
         this.log.debug(`Matterbridge Directory: ${this.matterbridgeDirectory}`);
         this.log.debug(`Matterbridge Plugin Directory: ${this.matterbridgePluginDirectory}`);
         this.log.debug(`Matterbridge Matter Certificate Directory: ${this.matterbridgeCertDirectory}`);
+        // Global node_modules directory
         if (this.nodeContext)
             this.globalModulesDirectory = this.matterbridgeInformation.globalModulesDirectory = await this.nodeContext.get('globalModulesDirectory', '');
         if (this.globalModulesDirectory === '') {
+            // First run of Matterbridge so the node storage is empty
             try {
                 this.execRunningCount++;
                 this.matterbridgeInformation.globalModulesDirectory = this.globalModulesDirectory = await getGlobalNodeModules();
@@ -885,53 +1073,84 @@ export class Matterbridge extends EventEmitter {
         }
         else
             this.log.debug(`Global node_modules Directory: ${this.globalModulesDirectory}`);
+        /* removed cause is too expensive for the shelly board and not really needed. Why should the globalModulesDirectory change?
+        else {
+          this.getGlobalNodeModules()
+            .then(async (globalModulesDirectory) => {
+              this.globalModulesDirectory = globalModulesDirectory;
+              this.matterbridgeInformation.globalModulesDirectory = this.globalModulesDirectory;
+              this.log.debug(`Global node_modules Directory: ${this.globalModulesDirectory}`);
+              await this.nodeContext?.set<string>('globalModulesDirectory', this.globalModulesDirectory);
+            })
+            .catch((error) => {
+              this.log.error(`Error getting global node_modules directory: ${error}`);
+            });
+        }*/
+        // Matterbridge version
         const packageJson = JSON.parse(await fs.readFile(path.join(this.rootDirectory, 'package.json'), 'utf-8'));
         this.matterbridgeVersion = this.matterbridgeLatestVersion = this.matterbridgeDevVersion = packageJson.version;
         this.matterbridgeInformation.matterbridgeVersion = this.matterbridgeInformation.matterbridgeLatestVersion = this.matterbridgeInformation.matterbridgeDevVersion = packageJson.version;
         this.log.debug(`Matterbridge Version: ${this.matterbridgeVersion}`);
+        // Matterbridge latest version (will be set in the checkUpdate function)
         if (this.nodeContext)
             this.matterbridgeLatestVersion = this.matterbridgeInformation.matterbridgeLatestVersion = await this.nodeContext.get('matterbridgeLatestVersion', this.matterbridgeVersion);
         this.log.debug(`Matterbridge Latest Version: ${this.matterbridgeLatestVersion}`);
+        // Matterbridge dev version (will be set in the checkUpdate function)
         if (this.nodeContext)
             this.matterbridgeDevVersion = this.matterbridgeInformation.matterbridgeDevVersion = await this.nodeContext.get('matterbridgeDevVersion', this.matterbridgeVersion);
         this.log.debug(`Matterbridge Dev Version: ${this.matterbridgeDevVersion}`);
+        // Current working directory
         const currentDir = process.cwd();
         this.log.debug(`Current Working Directory: ${currentDir}`);
+        // Command line arguments (excluding 'node' and the script name)
         const cmdArgs = process.argv.slice(2).join(' ');
         this.log.debug(`Command Line Arguments: ${cmdArgs}`);
     }
+    /**
+     * Creates a MatterLogger function to show the matter.js log messages in AnsiLogger (for the frontend).
+     *
+     * @returns {Function} The MatterLogger function.
+     */
     createMatterLogger() {
-        const matterLogger = new AnsiLogger({ logName: 'Matter', logTimestampFormat: 4, logLevel: "debug" });
+        const matterLogger = new AnsiLogger({ logName: 'Matter', logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: "debug" /* LogLevel.DEBUG */ });
         return (level, formattedLog) => {
             const logger = formattedLog.slice(44, 44 + 20).trim();
             const message = formattedLog.slice(65);
             matterLogger.logName = logger;
             switch (level) {
                 case MatterLogLevel.DEBUG:
-                    matterLogger.log("debug", message);
+                    matterLogger.log("debug" /* LogLevel.DEBUG */, message);
                     break;
                 case MatterLogLevel.INFO:
-                    matterLogger.log("info", message);
+                    matterLogger.log("info" /* LogLevel.INFO */, message);
                     break;
                 case MatterLogLevel.NOTICE:
-                    matterLogger.log("notice", message);
+                    matterLogger.log("notice" /* LogLevel.NOTICE */, message);
                     break;
                 case MatterLogLevel.WARN:
-                    matterLogger.log("warn", message);
+                    matterLogger.log("warn" /* LogLevel.WARN */, message);
                     break;
                 case MatterLogLevel.ERROR:
-                    matterLogger.log("error", message);
+                    matterLogger.log("error" /* LogLevel.ERROR */, message);
                     break;
                 case MatterLogLevel.FATAL:
-                    matterLogger.log("fatal", message);
+                    matterLogger.log("fatal" /* LogLevel.FATAL */, message);
                     break;
                 default:
-                    matterLogger.log("debug", message);
+                    matterLogger.log("debug" /* LogLevel.DEBUG */, message);
                     break;
             }
         };
     }
+    /**
+     * Creates a Matter File Logger.
+     *
+     * @param {string} filePath - The path to the log file.
+     * @param {boolean} [unlink=false] - Whether to unlink the log file before creating a new one.
+     * @returns {Function} - A function that logs formatted messages to the log file.
+     */
     async createMatterFileLogger(filePath, unlink = false) {
+        // 2024-08-21 08:55:19.488 DEBUG InteractionMessenger Sending DataReport chunk with 28 attributes and 0 events: 1004 bytes
         let fileSize = 0;
         if (unlink) {
             try {
@@ -980,12 +1199,21 @@ export class Matterbridge extends EventEmitter {
             }
         };
     }
+    /**
+     * Restarts the process by exiting the current instance and loading a new instance.
+     */
     async restartProcess() {
         await this.cleanup('restarting...', true);
     }
+    /**
+     * Shut down the process by exiting the current process.
+     */
     async shutdownProcess() {
         await this.cleanup('shutting down...', false);
     }
+    /**
+     * Update matterbridge and and shut down the process.
+     */
     async updateProcess() {
         this.log.info('Updating matterbridge...');
         try {
@@ -998,52 +1226,73 @@ export class Matterbridge extends EventEmitter {
         this.frontend.wssSendRestartRequired();
         await this.cleanup('updating...', false);
     }
+    /**
+     * Unregister all devices and shut down the process.
+     */
     async unregisterAndShutdownProcess() {
         this.log.info('Unregistering all devices and shutting down...');
         for (const plugin of this.plugins) {
             await this.removeAllBridgedEndpoints(plugin.name, 250);
         }
         this.log.debug('Waiting for the MessageExchange to finish...');
-        await new Promise((resolve) => setTimeout(resolve, 1000));
+        await new Promise((resolve) => setTimeout(resolve, 1000)); // Wait 1 second for MessageExchange to finish
         this.log.debug('Cleaning up and shutting down...');
         await this.cleanup('unregistered all devices and shutting down...', false);
     }
+    /**
+     * Reset commissioning and shut down the process.
+     */
     async shutdownProcessAndReset() {
         await this.cleanup('shutting down with reset...', false);
     }
+    /**
+     * Factory reset and shut down the process.
+     */
     async shutdownProcessAndFactoryReset() {
         await this.cleanup('shutting down with factory reset...', false);
     }
+    /**
+     * Cleans up the Matterbridge instance.
+     * @param {string} message - The cleanup message.
+     * @param {boolean} [restart=false] - Indicates whether to restart the instance after cleanup. Default is `false`.
+     * @returns A promise that resolves when the cleanup is completed.
+     */
     async cleanup(message, restart = false) {
         if (this.initialized && !this.hasCleanupStarted) {
             this.emit('cleanup_started');
             this.hasCleanupStarted = true;
             this.log.info(message);
+            // Clear the start matter interval
             if (this.startMatterInterval) {
                 clearInterval(this.startMatterInterval);
                 this.startMatterInterval = undefined;
                 this.log.debug('Start matter interval cleared');
             }
+            // Clear the check update timeout
             if (this.checkUpdateTimeout) {
                 clearInterval(this.checkUpdateTimeout);
                 this.checkUpdateTimeout = undefined;
                 this.log.debug('Check update timeout cleared');
             }
+            // Clear the check update interval
             if (this.checkUpdateInterval) {
                 clearInterval(this.checkUpdateInterval);
                 this.checkUpdateInterval = undefined;
                 this.log.debug('Check update interval cleared');
             }
+            // Clear the configure timeout
             if (this.configureTimeout) {
                 clearTimeout(this.configureTimeout);
                 this.configureTimeout = undefined;
                 this.log.debug('Matterbridge configure timeout cleared');
             }
+            // Clear the reachability timeout
             if (this.reachabilityTimeout) {
                 clearTimeout(this.reachabilityTimeout);
                 this.reachabilityTimeout = undefined;
                 this.log.debug('Matterbridge reachability timeout cleared');
             }
+            // Calling the shutdown method of each plugin and clear the plugins reachability timeout
             for (const plugin of this.plugins) {
                 if (!plugin.enabled || plugin.error)
                     continue;
@@ -1054,9 +1303,10 @@ export class Matterbridge extends EventEmitter {
                     this.log.debug(`Plugin ${plg}${plugin.name}${db} reachability timeout cleared`);
                 }
             }
+            // Stop matter server nodes
             this.log.notice(`Stopping matter server nodes in ${this.bridgeMode} mode...`);
             this.log.debug('Waiting for the MessageExchange to finish...');
-            await new Promise((resolve) => setTimeout(resolve, 1000));
+            await new Promise((resolve) => setTimeout(resolve, 1000)); // Wait 1 second for MessageExchange to finish
             if (this.bridgeMode === 'bridge') {
                 if (this.serverNode) {
                     await this.stopServerNode(this.serverNode);
@@ -1072,6 +1322,7 @@ export class Matterbridge extends EventEmitter {
                 }
             }
             this.log.notice('Stopped matter server nodes');
+            // Matter commisioning reset
             if (message === 'shutting down with reset...') {
                 this.log.info('Resetting Matterbridge commissioning information...');
                 await this.matterStorageManager?.createContext('events')?.clearAll();
@@ -1081,18 +1332,36 @@ export class Matterbridge extends EventEmitter {
                 await this.matterbridgeContext?.clearAll();
                 this.log.info('Matter storage reset done! Remove the bridge from the controller.');
             }
+            // Stop matter storage
             await this.stopMatterStorage();
+            // Stop the frontend
             await this.frontend.stop();
+            // Remove the matterfilelogger
             try {
                 Logger.removeLogger('matterfilelogger');
             }
             catch (error) {
                 this.log.debug(`Error removing the matterfilelogger for file ${CYAN}${path.join(this.matterbridgeDirectory, this.matterLoggerFile)}${db}: ${error instanceof Error ? error.message : String(error)}`);
             }
+            // Close the matterbridge node storage and context
             if (this.nodeStorage && this.nodeContext) {
+                /*
+                TODO: Implement serialization of registered devices in edge mode
+                this.log.info('Saving registered devices...');
+                const serializedRegisteredDevices: SerializedMatterbridgeEndpoint[] = [];
+                this.devices.forEach(async (device) => {
+                  const serializedMatterbridgeDevice = MatterbridgeEndpoint.serialize(device);
+                  // this.log.info(`- ${serializedMatterbridgeDevice.deviceName}${rs}\n`, serializedMatterbridgeDevice);
+                  if (serializedMatterbridgeDevice) serializedRegisteredDevices.push(serializedMatterbridgeDevice);
+                });
+                await this.nodeContext.set<SerializedMatterbridgeEndpoint[]>('devices', serializedRegisteredDevices);
+                this.log.info(`Saved registered devices (${serializedRegisteredDevices?.length})`);
+                */
+                // Clear nodeContext and nodeStorage (they just need 1000ms to write the data to disk)
                 this.log.debug(`Closing node storage context for ${plg}Matterbridge${db}...`);
                 await this.nodeContext.close();
                 this.nodeContext = undefined;
+                // Clear nodeContext for each plugin (they just need 1000ms to write the data to disk)
                 for (const plugin of this.plugins) {
                     if (plugin.nodeContext) {
                         this.log.debug(`Closing node storage context for plugin ${plg}${plugin.name}${db}...`);
@@ -1109,8 +1378,10 @@ export class Matterbridge extends EventEmitter {
             }
             this.plugins.clear();
             this.devices.clear();
+            // Factory reset
             if (message === 'shutting down with factory reset...') {
                 try {
+                    // Delete matter storage directory with its subdirectories and backup
                     const dir = path.join(this.matterbridgeDirectory, this.matterStorageName);
                     this.log.info(`Removing matter storage directory: ${dir}`);
                     await fs.rm(dir, { recursive: true });
@@ -1124,6 +1395,7 @@ export class Matterbridge extends EventEmitter {
                     }
                 }
                 try {
+                    // Delete matterbridge storage directory with its subdirectories and backup
                     const dir = path.join(this.matterbridgeDirectory, this.nodeStorageName);
                     this.log.info(`Removing matterbridge storage directory: ${dir}`);
                     await fs.rm(dir, { recursive: true });
@@ -1138,12 +1410,13 @@ export class Matterbridge extends EventEmitter {
                 }
                 this.log.info('Factory reset done! Remove all paired fabrics from the controllers.');
             }
+            // Deregisters the process handlers
             this.deregisterProcessHandlers();
             if (restart) {
                 if (message === 'updating...') {
                     this.log.info('Cleanup completed. Updating...');
                     Matterbridge.instance = undefined;
-                    this.emit('update');
+                    this.emit('update'); // Restart the process but the update has been done before. TODO move all updates to the cli
                 }
                 else if (message === 'restarting...') {
                     this.log.info('Cleanup completed. Restarting...');
@@ -1164,6 +1437,14 @@ export class Matterbridge extends EventEmitter {
             this.log.debug('Cleanup already started...');
         }
     }
+    /**
+     * Creates and configures the server node for an accessory plugin for a given device.
+     *
+     * @param {RegisteredPlugin} plugin - The plugin to configure.
+     * @param {MatterbridgeEndpoint} device - The device to associate with the plugin.
+     * @param {boolean} [start=false] - Whether to start the server node after adding the device.
+     * @returns {Promise<void>} A promise that resolves when the server node for the accessory plugin is created and configured.
+     */
     async createAccessoryPlugin(plugin, device, start = false) {
         if (!plugin.locked && device.deviceName && device.vendorId && device.productId && device.vendorName && device.productName) {
             plugin.locked = true;
@@ -1177,6 +1458,13 @@ export class Matterbridge extends EventEmitter {
                 await this.startServerNode(plugin.serverNode);
         }
     }
+    /**
+     * Creates and configures the server node for a dynamic plugin.
+     *
+     * @param {RegisteredPlugin} plugin - The plugin to configure.
+     * @param {boolean} [start=false] - Whether to start the server node after adding the aggregator node.
+     * @returns {Promise<void>} A promise that resolves when the server node for the dynamic plugin is created and configured.
+     */
     async createDynamicPlugin(plugin, start = false) {
         if (!plugin.locked) {
             plugin.locked = true;
@@ -1189,7 +1477,13 @@ export class Matterbridge extends EventEmitter {
                 await this.startServerNode(plugin.serverNode);
         }
     }
+    /**
+     * Starts the Matterbridge in bridge mode.
+     * @private
+     * @returns {Promise<void>} A promise that resolves when the Matterbridge is started.
+     */
     async startBridge() {
+        // Plugins are configured by a timer when matter server is started and plugin.configured is set to true
         if (!this.matterStorageManager)
             throw new Error('No storage manager initialized');
         if (!this.matterbridgeContext)
@@ -1228,7 +1522,9 @@ export class Matterbridge extends EventEmitter {
             clearInterval(this.startMatterInterval);
             this.startMatterInterval = undefined;
             this.log.debug('Cleared startMatterInterval interval for Matterbridge');
+            // Start the Matter server node
             this.startServerNode(this.serverNode);
+            // Configure the plugins
             this.configureTimeout = setTimeout(async () => {
                 for (const plugin of this.plugins) {
                     if (!plugin.enabled || !plugin.loaded || !plugin.started || plugin.error)
@@ -1246,6 +1542,7 @@ export class Matterbridge extends EventEmitter {
                 }
                 this.frontend.wssSendRefreshRequired('plugins');
             }, 30 * 1000);
+            // Setting reachability to true
             this.reachabilityTimeout = setTimeout(() => {
                 this.log.info(`Setting reachability to true for ${plg}Matterbridge${db}`);
                 if (this.aggregatorNode)
@@ -1254,6 +1551,11 @@ export class Matterbridge extends EventEmitter {
             }, 60 * 1000);
         }, 1000);
     }
+    /**
+     * Starts the Matterbridge in childbridge mode.
+     * @private
+     * @returns {Promise<void>} A promise that resolves when the Matterbridge is started.
+     */
     async startChildbridge() {
         if (!this.matterStorageManager)
             throw new Error('No storage manager initialized');
@@ -1291,6 +1593,7 @@ export class Matterbridge extends EventEmitter {
             clearInterval(this.startMatterInterval);
             this.startMatterInterval = undefined;
             this.log.debug('Cleared startMatterInterval interval in childbridge mode');
+            // Configure the plugins
             this.configureTimeout = setTimeout(async () => {
                 for (const plugin of this.plugins) {
                     if (!plugin.enabled || !plugin.loaded || !plugin.started || plugin.error)
@@ -1327,7 +1630,9 @@ export class Matterbridge extends EventEmitter {
                     this.log.error(`Node storage context not found for plugin ${plg}${plugin.name}${er}`);
                     continue;
                 }
+                // Start the Matter server node
                 this.startServerNode(plugin.serverNode);
+                // Setting reachability to true
                 plugin.reachabilityTimeout = setTimeout(() => {
                     this.log.info(`Setting reachability to true for ${plg}${plugin.name}${nf} type ${plugin.type} server node ${plugin.serverNode !== undefined} aggregator node ${plugin.aggregatorNode !== undefined} device ${plugin.device !== undefined}`);
                     if (plugin.type === 'DynamicPlatform' && plugin.aggregatorNode)
@@ -1337,6 +1642,11 @@ export class Matterbridge extends EventEmitter {
             }
         }, 1000);
     }
+    /**
+     * Starts the Matterbridge controller.
+     * @private
+     * @returns {Promise<void>} A promise that resolves when the Matterbridge is started.
+     */
     async startController() {
         if (!this.matterStorageManager) {
             this.log.error('No storage manager initialized');
@@ -1351,8 +1661,207 @@ export class Matterbridge extends EventEmitter {
             return;
         }
         this.log.debug('Starting matterbridge in mode', this.bridgeMode);
+        /*
+        this.matterServer = await this.createMatterServer(this.storageManager);
+        this.log.info('Creating matter commissioning controller');
+        this.commissioningController = new CommissioningController({
+          autoConnect: false,
+        });
+        this.log.info('Adding matter commissioning controller to matter server');
+        await this.matterServer.addCommissioningController(this.commissioningController);
+    
+        this.log.info('Starting matter server');
+        await this.matterServer.start();
+        this.log.info('Matter server started');
+      const commissioningOptions: ControllerCommissioningFlowOptions = {
+          regulatoryLocation: GeneralCommissioning.RegulatoryLocationType.IndoorOutdoor,
+          regulatoryCountryCode: 'XX',
+        };
+    const commissioningController = new CommissioningController({
+      environment: {
+          environment,
+          id: uniqueId,
+      },
+      autoConnect: false, // Do not auto connect to the commissioned nodes
+      adminFabricLabel,
+    });
+    
+        if (hasParameter('pairingcode')) {
+          this.log.info('Pairing device with pairingcode:', getParameter('pairingcode'));
+          const pairingCode = getParameter('pairingcode');
+          const ip = this.controllerContext.has('ip') ? this.controllerContext.get<string>('ip') : undefined;
+          const port = this.controllerContext.has('port') ? this.controllerContext.get<number>('port') : undefined;
+    
+          let longDiscriminator, setupPin, shortDiscriminator;
+          if (pairingCode !== undefined) {
+            const pairingCodeCodec = ManualPairingCodeCodec.decode(pairingCode);
+            shortDiscriminator = pairingCodeCodec.shortDiscriminator;
+            longDiscriminator = undefined;
+            setupPin = pairingCodeCodec.passcode;
+            this.log.info(`Data extracted from pairing code: ${Logger.toJSON(pairingCodeCodec)}`);
+          } else {
+            longDiscriminator = await this.controllerContext.get('longDiscriminator', 3840);
+            if (longDiscriminator > 4095) throw new Error('Discriminator value must be less than 4096');
+            setupPin = this.controllerContext.get('pin', 20202021);
+          }
+          if ((shortDiscriminator === undefined && longDiscriminator === undefined) || setupPin === undefined) {
+            throw new Error('Please specify the longDiscriminator of the device to commission with -longDiscriminator or provide a valid passcode with -passcode');
+          }
+    
+          const options = {
+            commissioning: commissioningOptions,
+            discovery: {
+              knownAddress: ip !== undefined && port !== undefined ? { ip, port, type: 'udp' } : undefined,
+              identifierData: longDiscriminator !== undefined ? { longDiscriminator } : shortDiscriminator !== undefined ? { shortDiscriminator } : {},
+            },
+            passcode: setupPin,
+          } as NodeCommissioningOptions;
+          this.log.info('Commissioning with options:', options);
+          const nodeId = await this.commissioningController.commissionNode(options);
+          this.log.info(`Commissioning successfully done with nodeId: ${nodeId}`);
+          this.log.info('ActiveSessionInformation:', this.commissioningController.getActiveSessionInformation());
+        } // (hasParameter('pairingcode'))
+    
+        if (hasParameter('unpairall')) {
+          this.log.info('***Commissioning controller unpairing all nodes...');
+          const nodeIds = this.commissioningController.getCommissionedNodes();
+          for (const nodeId of nodeIds) {
+            this.log.info('***Commissioning controller unpairing node:', nodeId);
+            await this.commissioningController.removeNode(nodeId);
+          }
+          return;
+        }
+    
+        if (hasParameter('discover')) {
+          // const discover = await this.commissioningController.discoverCommissionableDevices({ productId: 0x8000, deviceType: 0xfff1 });
+          // console.log(discover);
+        }
+    
+        if (!this.commissioningController.isCommissioned()) {
+          this.log.info('***Commissioning controller is not commissioned: use matterbridge -controller -pairingcode [pairingcode] to commission a device');
+          return;
+        }
+    
+        const nodeIds = this.commissioningController.getCommissionedNodes();
+        this.log.info(`***Commissioning controller is commissioned ${this.commissioningController.isCommissioned()} and has ${nodeIds.length} nodes commisioned: `);
+        for (const nodeId of nodeIds) {
+          this.log.info(`***Connecting to commissioned node: ${nodeId}`);
+    
+          const node = await this.commissioningController.connectNode(nodeId, {
+            autoSubscribe: false,
+            attributeChangedCallback: (peerNodeId, { path: { nodeId, clusterId, endpointId, attributeName }, value }) =>
+              this.log.info(`***Commissioning controller attributeChangedCallback ${peerNodeId}: attribute ${nodeId}/${endpointId}/${clusterId}/${attributeName} changed to ${Logger.toJSON(value)}`),
+            eventTriggeredCallback: (peerNodeId, { path: { nodeId, clusterId, endpointId, eventName }, events }) =>
+              this.log.info(`***Commissioning controller eventTriggeredCallback ${peerNodeId}: Event ${nodeId}/${endpointId}/${clusterId}/${eventName} triggered with ${Logger.toJSON(events)}`),
+            stateInformationCallback: (peerNodeId, info) => {
+              switch (info) {
+                case NodeStateInformation.Connected:
+                  this.log.info(`***Commissioning controller stateInformationCallback ${peerNodeId}: Node ${nodeId} connected`);
+                  break;
+                case NodeStateInformation.Disconnected:
+                  this.log.info(`***Commissioning controller stateInformationCallback ${peerNodeId}: Node ${nodeId} disconnected`);
+                  break;
+                case NodeStateInformation.Reconnecting:
+                  this.log.info(`***Commissioning controller stateInformationCallback ${peerNodeId}: Node ${nodeId} reconnecting`);
+                  break;
+                case NodeStateInformation.WaitingForDeviceDiscovery:
+                  this.log.info(`***Commissioning controller stateInformationCallback ${peerNodeId}: Node ${nodeId} waiting for device discovery`);
+                  break;
+                case NodeStateInformation.StructureChanged:
+                  this.log.info(`***Commissioning controller stateInformationCallback ${peerNodeId}: Node ${nodeId} structure changed`);
+                  break;
+                case NodeStateInformation.Decommissioned:
+                  this.log.info(`***Commissioning controller stateInformationCallback ${peerNodeId}: Node ${nodeId} decommissioned`);
+                  break;
+                default:
+                  this.log.info(`***Commissioning controller stateInformationCallback ${peerNodeId}: Node ${nodeId} NodeStateInformation.${info}`);
+                  break;
+              }
+            },
+          });
+    
+          node.logStructure();
+    
+          // Get the interaction client
+          this.log.info('Getting the interaction client');
+          const interactionClient = await node.getInteractionClient();
+          let cluster;
+          let attributes;
+    
+          // Log BasicInformationCluster
+          cluster = BasicInformationCluster;
+          attributes = await interactionClient.getMultipleAttributes({
+            attributes: [{ clusterId: cluster.id }],
+          });
+          if (attributes.length > 0) this.log.info(`Cluster: ${idn}${cluster.name}${rs}${nf} attributes:`);
+          attributes.forEach((attribute) => {
+            this.log.info(
+              `- endpoint ${or}${attribute.path.endpointId}${nf} cluster ${hk}${getClusterNameById(attribute.path.clusterId)}${nf} (${hk}0x${attribute.path.clusterId.toString(16)}${nf}) attribute ${zb}${attribute.path.attributeName}${nf} (${zb}0x${attribute.path.attributeId.toString(16)}${nf}): ${typeof attribute.value === 'object' ? stringify(attribute.value) : attribute.value}`,
+            );
+          });
+    
+          // Log PowerSourceCluster
+          cluster = PowerSourceCluster;
+          attributes = await interactionClient.getMultipleAttributes({
+            attributes: [{ clusterId: cluster.id }],
+          });
+          if (attributes.length > 0) this.log.info(`Cluster: ${idn}${cluster.name}${rs}${nf} attributes:`);
+          attributes.forEach((attribute) => {
+            this.log.info(
+              `- endpoint ${or}${attribute.path.endpointId}${nf} cluster ${hk}${getClusterNameById(attribute.path.clusterId)}${nf} (${hk}0x${attribute.path.clusterId.toString(16)}${nf}) attribute ${zb}${attribute.path.attributeName}${nf} (${zb}0x${attribute.path.attributeId.toString(16)}${nf}): ${typeof attribute.value === 'object' ? stringify(attribute.value) : attribute.value}`,
+            );
+          });
+    
+          // Log ThreadNetworkDiagnostics
+          cluster = ThreadNetworkDiagnosticsCluster;
+          attributes = await interactionClient.getMultipleAttributes({
+            attributes: [{ clusterId: cluster.id }],
+          });
+          if (attributes.length > 0) this.log.info(`Cluster: ${idn}${cluster.name}${rs}${nf} attributes:`);
+          attributes.forEach((attribute) => {
+            this.log.info(
+              `- endpoint ${or}${attribute.path.endpointId}${nf} cluster ${hk}${getClusterNameById(attribute.path.clusterId)}${nf} (${hk}0x${attribute.path.clusterId.toString(16)}${nf}) attribute ${zb}${attribute.path.attributeName}${nf} (${zb}0x${attribute.path.attributeId.toString(16)}${nf}): ${typeof attribute.value === 'object' ? stringify(attribute.value) : attribute.value}`,
+            );
+          });
+    
+          // Log SwitchCluster
+          cluster = SwitchCluster;
+          attributes = await interactionClient.getMultipleAttributes({
+            attributes: [{ clusterId: cluster.id }],
+          });
+          if (attributes.length > 0) this.log.info(`Cluster: ${idn}${cluster.name}${rs}${nf} attributes:`);
+          attributes.forEach((attribute) => {
+            this.log.info(
+              `- endpoint ${or}${attribute.path.endpointId}${nf} cluster ${hk}${getClusterNameById(attribute.path.clusterId)}${nf} (${hk}0x${attribute.path.clusterId.toString(16)}${nf}) attribute ${zb}${attribute.path.attributeName}${nf} (${zb}0x${attribute.path.attributeId.toString(16)}${nf}): ${typeof attribute.value === 'object' ? stringify(attribute.value) : attribute.value}`,
+            );
+          });
+    
+          this.log.info('Subscribing to all attributes and events');
+          await node.subscribeAllAttributesAndEvents({
+            ignoreInitialTriggers: false,
+            attributeChangedCallback: ({ path: { nodeId, clusterId, endpointId, attributeName }, version, value }) =>
+              this.log.info(
+                `***${db}Commissioning controller attributeChangedCallback version ${version}: attribute ${BLUE}${nodeId}${db}/${or}${endpointId}${db}/${hk}${getClusterNameById(clusterId)}${db}/${zb}${attributeName}${db} changed to ${typeof value === 'object' ? debugStringify(value ?? { none: true }) : value}`,
+              ),
+            eventTriggeredCallback: ({ path: { nodeId, clusterId, endpointId, eventName }, events }) => {
+              this.log.info(
+                `***${db}Commissioning controller eventTriggeredCallback: event ${BLUE}${nodeId}${db}/${or}${endpointId}${db}/${hk}${getClusterNameById(clusterId)}${db}/${zb}${eventName}${db} triggered with ${debugStringify(events ?? { none: true })}`,
+              );
+            },
+          });
+          this.log.info('Subscribed to all attributes and events');
+        }
+        */
     }
+    /** ***********************************************************************************************************************************/
+    /**                                                     Matter.js methods                                                             */
+    /** ***********************************************************************************************************************************/
+    /**
+     * Starts the matter storage process with name Matterbridge.
+     * @returns {Promise<void>} - A promise that resolves when the storage process is started.
+     */
     async startMatterStorage() {
+        // Setup Matter storage
         this.log.info(`Starting matter node storage...`);
         this.matterStorageService = this.environment.get(StorageService);
         this.log.info(`Matter node storage service created: ${this.matterStorageService.location}`);
@@ -1361,13 +1870,25 @@ export class Matterbridge extends EventEmitter {
         this.matterbridgeContext = await this.createServerNodeContext('Matterbridge', 'Matterbridge', bridge.code, this.aggregatorVendorId, this.aggregatorVendorName, this.aggregatorProductId, this.aggregatorProductName);
         this.matterbridgeInformation.matterbridgeSerialNumber = await this.matterbridgeContext.get('serialNumber', '');
         this.log.info('Matter node storage started');
+        // Backup matter storage since it is created/opened correctly
         await this.backupMatterStorage(path.join(this.matterbridgeDirectory, this.matterStorageName), path.join(this.matterbridgeDirectory, this.matterStorageName + '.backup'));
     }
+    /**
+     * Makes a backup copy of the specified matter storage directory.
+     *
+     * @param storageName - The name of the storage directory to be backed up.
+     * @param backupName - The name of the backup directory to be created.
+     * @returns {Promise<void>} A promise that resolves when the has been done.
+     */
     async backupMatterStorage(storageName, backupName) {
         this.log.info('Creating matter node storage backup...');
         await copyDirectory(storageName, backupName);
         this.log.info('Created matter node storage backup');
     }
+    /**
+     * 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();
@@ -1376,6 +1897,19 @@ export class Matterbridge extends EventEmitter {
         this.matterbridgeContext = undefined;
         this.log.info('Matter node storage closed');
     }
+    /**
+     * Creates a server node storage context.
+     *
+     * @param {string} pluginName - The name of the plugin.
+     * @param {string} deviceName - The name of the device.
+     * @param {DeviceTypeId} deviceType - The device type of the device.
+     * @param {number} 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).
+     * @returns {Promise<StorageContext>} The storage context for the commissioning server.
+     */
     async createServerNodeContext(pluginName, deviceName, deviceType, vendorId, vendorName, productId, productName, serialNumber) {
         const { randomBytes } = await import('node:crypto');
         if (!this.matterStorageService)
@@ -1409,6 +1943,15 @@ export class Matterbridge extends EventEmitter {
         this.log.debug(`- hardwareVersion: ${await storageContext.get('hardwareVersion')} hardwareVersionString: ${await storageContext.get('hardwareVersionString')}`);
         return storageContext;
     }
+    /**
+     * Creates a server node.
+     *
+     * @param {StorageContext} storageContext - The storage context for the server node.
+     * @param {number} [port=5540] - The port number for the server node. Defaults to 5540.
+     * @param {number} [passcode=20242025] - The passcode for the server node. Defaults to 20242025.
+     * @param {number} [discriminator=3850] - The discriminator for the server node. Defaults to 3850.
+     * @returns {Promise<ServerNode<ServerNode.RootEndpoint>>} A promise that resolves to the created server node.
+     */
     async createServerNode(storageContext, port = 5540, passcode = 20242025, discriminator = 3850) {
         const storeId = await storageContext.get('storeId');
         this.log.notice(`Creating server node for ${storeId} on port ${port} with passcode ${passcode} and discriminator ${discriminator}...`);
@@ -1418,24 +1961,37 @@ export class Matterbridge extends EventEmitter {
         this.log.debug(`- uniqueId: ${await storageContext.get('uniqueId')}`);
         this.log.debug(`- softwareVersion: ${await storageContext.get('softwareVersion')} softwareVersionString: ${await storageContext.get('softwareVersionString')}`);
         this.log.debug(`- hardwareVersion: ${await storageContext.get('hardwareVersion')} hardwareVersionString: ${await storageContext.get('hardwareVersionString')}`);
+        /**
+         * 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 Network relevant configuration like the port
+            // Optional when operating only one device on a host, Default port is 5540
             network: {
                 listeningAddressIpv4: this.ipv4address,
                 listeningAddressIpv6: this.ipv6address,
                 port,
             },
+            // Provide the certificate for the device
             operationalCredentials: {
                 certification: this.certification,
             },
+            // Provide Commissioning relevant settings
+            // Optional for development/testing purposes
             commissioning: {
                 passcode,
                 discriminator,
             },
+            // Provide Node announcement settings
+            // Optional: If Ommitted some development defaults are used
             productDescription: {
                 name: await storageContext.get('deviceName'),
                 deviceType: DeviceTypeId(await storageContext.get('deviceType')),
             },
+            // Provide defaults for the BasicInformation cluster on the Root endpoint
+            // Optional: If Omitted some development defaults are used
             basicInformation: {
                 vendorId: VendorId(await storageContext.get('vendorId')),
                 vendorName: await storageContext.get('vendorName'),
@@ -1453,12 +2009,13 @@ export class Matterbridge extends EventEmitter {
             },
         });
         const sanitizeFabrics = (fabrics, resetSessions = false) => {
+            // New type of fabric information: Record<FabricIndex, ExposedFabricInformation>
             const sanitizedFabrics = this.sanitizeFabricInformations(Array.from(Object.values(fabrics)));
             this.log.info(`Fabrics: ${debugStringify(sanitizedFabrics)}`);
             if (this.bridgeMode === 'bridge') {
                 this.matterbridgeFabricInformations = sanitizedFabrics;
                 if (resetSessions)
-                    this.matterbridgeSessionInformations = undefined;
+                    this.matterbridgeSessionInformations = undefined; // Changed cause Invoke Matterbridge.operationalCredentials.updateFabricLabel is sent after the session is created
                 this.matterbridgePaired = true;
             }
             if (this.bridgeMode === 'childbridge') {
@@ -1466,13 +2023,19 @@ export class Matterbridge extends EventEmitter {
                 if (plugin) {
                     plugin.fabricInformations = sanitizedFabrics;
                     if (resetSessions)
-                        plugin.sessionInformations = undefined;
+                        plugin.sessionInformations = undefined; // Changed cause Invoke Matterbridge.operationalCredentials.updateFabricLabel is sent after the session is created
                     plugin.paired = 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 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 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) {
@@ -1541,6 +2104,7 @@ export class Matterbridge extends EventEmitter {
             this.frontend.wssSendRefreshRequired('settings');
             this.frontend.wssSendSnackbarMessage(`${storeId} is online`, 5, 'success');
         });
+        /** 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`);
             if (this.bridgeMode === 'bridge') {
@@ -1564,6 +2128,10 @@ export class Matterbridge extends EventEmitter {
             this.frontend.wssSendRefreshRequired('settings');
             this.frontend.wssSendSnackbarMessage(`${storeId} is offline`, 5, 'warning');
         });
+        /**
+         * 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) {
@@ -1597,16 +2165,24 @@ export class Matterbridge extends EventEmitter {
                 }
             }
         };
+        /**
+         * 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)}`);
             sanitizeSessions(Object.values(serverNode.state.sessions.sessions));
             this.frontend.wssSendRefreshRequired('sessions');
         });
+        /**
+         * 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)}`);
             sanitizeSessions(Object.values(serverNode.state.sessions.sessions));
             this.frontend.wssSendRefreshRequired('sessions');
         });
+        /** 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)}`);
             sanitizeSessions(Object.values(serverNode.state.sessions.sessions));
@@ -1615,24 +2191,42 @@ export class Matterbridge extends EventEmitter {
         this.log.info(`Created server node for ${storeId}`);
         return serverNode;
     }
+    /**
+     * Starts the specified server node.
+     *
+     * @param {ServerNode} [matterServerNode] - The server node to start.
+     * @returns {Promise<void>} A promise that resolves when the server node has started.
+     */
     async startServerNode(matterServerNode) {
         if (!matterServerNode)
             return;
         this.log.notice(`Starting ${matterServerNode.id} server node`);
         await matterServerNode.start();
     }
+    /**
+     * Stops the specified server node.
+     *
+     * @param {ServerNode} matterServerNode - The server node to stop.
+     * @returns {Promise<void>} A promise that resolves when the server node has stopped.
+     */
     async stopServerNode(matterServerNode) {
         if (!matterServerNode)
             return;
         this.log.notice(`Closing ${matterServerNode.id} server node`);
         try {
-            await withTimeout(matterServerNode.close(), 30000);
+            await withTimeout(matterServerNode.close(), 30000); // 30 seconds timeout to allow slow devices to close gracefully
             this.log.info(`Closed ${matterServerNode.id} server node`);
         }
         catch (error) {
             this.log.error(`Failed to close ${matterServerNode.id} server node: ${error instanceof Error ? error.message : error}`);
         }
     }
+    /**
+     * Advertises the specified server node.
+     *
+     * @param {ServerNode} [matterServerNode] - The server node to advertise.
+     * @returns {Promise<{ qrPairingCode: string, manualPairingCode: string } | undefined>} A promise that resolves to the pairing codes if the server node is advertised, or undefined if not.
+     */
     async advertiseServerNode(matterServerNode) {
         if (matterServerNode) {
             await matterServerNode.env.get(DeviceCommissioner)?.allowBasicCommissioning();
@@ -1641,25 +2235,46 @@ export class Matterbridge extends EventEmitter {
             return { qrPairingCode, manualPairingCode };
         }
     }
+    /**
+     * Stop advertise the specified server node.
+     *
+     * @param {ServerNode} [matterServerNode] - The server node to advertise.
+     * @returns {Promise<void>} A promise that resolves when the server node has stopped advertising.
+     */
     async stopAdvertiseServerNode(matterServerNode) {
         if (matterServerNode && matterServerNode.lifecycle.isOnline) {
             await matterServerNode.env.get(DeviceCommissioner)?.endCommissioning();
             this.log.notice(`Stopped advertising for ${matterServerNode.id}`);
         }
     }
+    /**
+     * Creates an aggregator node with the specified storage context.
+     *
+     * @param {StorageContext} storageContext - The storage context for the aggregator node.
+     * @returns {Promise<Endpoint<AggregatorEndpoint>>} A promise that resolves to the created aggregator node.
+     */
     async createAggregatorNode(storageContext) {
         this.log.notice(`Creating ${await storageContext.get('storeId')} aggregator...`);
         const aggregatorNode = new Endpoint(AggregatorEndpoint, { id: `${await storageContext.get('storeId')}` });
         this.log.info(`Created ${await storageContext.get('storeId')} aggregator`);
         return aggregatorNode;
     }
+    /**
+     * 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<void>} A promise that resolves when the bridged endpoint has been added.
+     */
     async addBridgedEndpoint(pluginName, device) {
+        // Check if the plugin is registered
         const plugin = this.plugins.get(pluginName);
         if (!plugin) {
             this.log.error(`Error adding bridged endpoint ${dev}${device.deviceName}${er} (${zb}${device.id}${er}) plugin ${plg}${pluginName}${er} not found`);
             return;
         }
         if (this.bridgeMode === 'bridge') {
+            // Register and add the device to the matterbridge aggregator node
             this.log.debug(`Adding bridged endpoint ${plg}${pluginName}${db}:${dev}${device.deviceName}${db} to Matterbridge aggregator node`);
             if (!this.aggregatorNode) {
                 this.log.error('Aggregator node not found for Matterbridge');
@@ -1676,6 +2291,7 @@ export class Matterbridge extends EventEmitter {
             }
         }
         else if (this.bridgeMode === 'childbridge') {
+            // Register and add the device to the plugin server node
             if (plugin.type === 'AccessoryPlatform') {
                 try {
                     this.log.debug(`Creating endpoint ${dev}${device.deviceName}${db} for AccessoryPlatform plugin ${plg}${plugin.name}${db} server node`);
@@ -1692,10 +2308,12 @@ export class Matterbridge extends EventEmitter {
                     return;
                 }
             }
+            // Register and add the device to the plugin aggregator node
             if (plugin.type === 'DynamicPlatform') {
                 try {
                     this.log.debug(`Adding bridged endpoint ${dev}${device.deviceName}${db} for DynamicPlatform plugin ${plg}${plugin.name}${db} aggregator node`);
                     await this.createDynamicPlugin(plugin);
+                    // Fast plugins can add another device before the server node is created
                     await waiter(`createDynamicPlugin(${plugin.name})`, () => plugin.serverNode?.hasParts === true);
                     if (!plugin.aggregatorNode) {
                         this.log.error(`Aggregator node not found for plugin ${plg}${plugin.name}${er}`);
@@ -1715,17 +2333,28 @@ export class Matterbridge extends EventEmitter {
             plugin.registeredDevices++;
         if (plugin.addedDevices !== undefined)
             plugin.addedDevices++;
+        // Add the device to the DeviceManager
         this.devices.set(device);
+        // Subscribe to the reachable$Changed event
         await this.subscribeAttributeChanged(plugin, device);
         this.log.info(`Added and registered bridged endpoint (${plugin.registeredDevices}/${plugin.addedDevices}) ${dev}${device.deviceName}${nf} (${dev}${device.id}${nf}) for plugin ${plg}${pluginName}${nf}`);
     }
+    /**
+     * 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<void>} A promise that resolves when the bridged endpoint has been removed.
+     */
     async removeBridgedEndpoint(pluginName, device) {
         this.log.debug(`Removing bridged endpoint ${plg}${pluginName}${db}:${dev}${device.deviceName}${db} (${zb}${device.name}${db}) for plugin ${plg}${pluginName}${db}`);
+        // Check if the plugin is registered
         const plugin = this.plugins.get(pluginName);
         if (!plugin) {
             this.log.error(`Error removing bridged endpoint ${dev}${device.deviceName}${er} (${zb}${device.name}${er}) for plugin ${plg}${pluginName}${er}: plugin not found`);
             return;
         }
+        // Register and add the device to the matterbridge aggregator node
         if (this.bridgeMode === 'bridge') {
             if (!this.aggregatorNode) {
                 this.log.error(`Error removing bridged endpoint ${dev}${device.deviceName}${er} (${zb}${device.name}${er}) for plugin ${plg}${pluginName}${er}: aggregator node not found`);
@@ -1740,6 +2369,7 @@ export class Matterbridge extends EventEmitter {
         }
         else if (this.bridgeMode === 'childbridge') {
             if (plugin.type === 'AccessoryPlatform') {
+                // Nothing to do here since the server node has no aggregator node but only the device itself
             }
             else if (plugin.type === 'DynamicPlatform') {
                 if (!plugin.aggregatorNode) {
@@ -1754,8 +2384,21 @@ export class Matterbridge extends EventEmitter {
             if (plugin.addedDevices !== undefined)
                 plugin.addedDevices--;
         }
+        // Remove the device from the DeviceManager
         this.devices.remove(device);
     }
+    /**
+     * Removes all bridged endpoints from the specified plugin.
+     *
+     * @param {string} pluginName - The name of the plugin.
+     * @param {number} [delay=0] - 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) {
         this.log.debug(`Removing all bridged endpoints for plugin ${plg}${pluginName}${db}${delay > 0 ? ` with delay ${delay} ms` : ''}`);
         for (const device of this.devices.array().filter((device) => device.plugin === pluginName)) {
@@ -1766,6 +2409,15 @@ export class Matterbridge extends EventEmitter {
         if (delay > 0)
             await new Promise((resolve) => setTimeout(resolve, 2000));
     }
+    /**
+     * 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 {RegisteredPlugin} 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) {
         this.log.info(`Subscribing attributes for endpoint ${dev}${device.deviceName}${nf} (${dev}${device.id}${nf}) plugin ${plg}${plugin.name}${nf}`);
         if (this.bridgeMode === 'childbridge' && plugin.type === 'AccessoryPlatform' && plugin.serverNode) {
@@ -1781,6 +2433,12 @@ export class Matterbridge 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 {
@@ -1794,6 +2452,12 @@ export class Matterbridge extends EventEmitter {
             };
         });
     }
+    /**
+     * Sanitizes the session information by converting bigint properties to strings because `res.json` doesn't support bigint.
+     *
+     * @param {SessionInformation[]} sessionInfo - The array of session information objects.
+     * @returns {SanitizedSessionInformation[]} An array of sanitized session information objects.
+     */
     sanitizeSessionInformation(sessionInfo) {
         return sessionInfo
             .filter((session) => session.isPeerActive)
@@ -1821,7 +2485,20 @@ export class Matterbridge extends EventEmitter {
             };
         });
     }
+    /**
+     * 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.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     async setAggregatorReachability(aggregatorNode, reachable) {
+        /*
+        for (const child of aggregatorNode.parts) {
+          this.log.debug(`Setting reachability of ${(child as unknown as MatterbridgeEndpoint)?.deviceName} to ${reachable}`);
+          await child.setStateOf(BridgedDeviceBasicInformationServer, { reachable });
+          child.act((agent) => child.eventsOf(BridgedDeviceBasicInformationServer).reachableChanged.emit({ reachableNewValue: true }, agent.context));
+        }
+        */
     }
     getVendorIdName = (vendorId) => {
         if (!vendorId)
@@ -1864,14 +2541,29 @@ export class Matterbridge extends EventEmitter {
         }
         return vendorName;
     };
+    /**
+     * Spawns a child process with the given command and arguments.
+     * @param {string} command - The command to execute.
+     * @param {string[]} args - The arguments to pass to the command (default: []).
+     * @returns {Promise<boolean>} A promise that resolves when the child process exits successfully, or rejects if there is an error.
+     */
     async spawnCommand(command, args = []) {
         const { spawn } = await import('node:child_process');
+        /*
+        npm > npm.cmd on windows
+        cmd.exe ['dir'] on windows
+        await this.spawnCommand('npm', ['install', '-g', 'matterbridge']);
+        */
         const cmdLine = command + ' ' + args.join(' ');
         if (process.platform === 'win32' && command === 'npm') {
+            // Must be spawn('cmd.exe', ['/c', 'npm -g install <package>']);
             const argstring = 'npm ' + args.join(' ');
             args.splice(0, args.length, '/c', argstring);
             command = 'cmd.exe';
         }
+        // Decide when using sudo on linux
+        // When you need sudo: Spawn stderr: npm error Error: EACCES: permission denied
+        // When you don't need sudo: Failed to start child process "npm install -g matterbridge-eve-door": spawn sudo ENOENT
         if (hasParameter('sudo') || (process.platform === 'linux' && command === 'npm' && !hasParameter('docker') && !hasParameter('nosudo'))) {
             args.unshift(command);
             command = 'sudo';
@@ -1929,6 +2621,13 @@ export class Matterbridge extends EventEmitter {
             }
         });
     }
+    /**
+     * Creates a directory at the specified path if it doesn't already exist.
+     *
+     * @param {string} path - The path to the directory to create.
+     * @param {string} name - The name of the directory.
+     * @returns {Promise<void>} A promise that resolves when the directory has been created or already exists.
+     */
     async createDirectory(path, name) {
         try {
             await fs.access(path);
@@ -1950,3 +2649,4 @@ export class Matterbridge extends EventEmitter {
         }
     }
 }
+//# sourceMappingURL=matterbridge.js.map