matterbridge 3.1.3-dev-20250714-c9b85b3 → 3.1.3

package/dist/matterbridge.js

@@ -1,15 +1,43 @@
+/**
+ * This file contains the class Matterbridge.
+ *
+ * @file matterbridge.ts
+ * @author Luca Liguori
+ * @created 2023-12-29
+ * @version 1.6.0
+ * @license Apache-2.0
+ *
+ * Copyright 2023, 2024, 2025 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// 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, db, debugStringify, BRIGHT, RESET, er, nf, rs, wr, RED, GREEN, zb, CYAN, nt } from 'node-ansi-logger';
+// NodeStorage module
 import { NodeStorageManager } from 'node-persist-manager';
+// @matter
 import { DeviceTypeId, Endpoint, Logger, LogLevel as MatterLogLevel, LogFormat as MatterLogFormat, VendorId, StorageService, Environment, ServerNode, UINT32_MAX, UINT16_MAX, Crypto, } 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';
+// Matterbridge
 import { getParameter, getIntParameter, hasParameter, copyDirectory, withTimeout, waiter, isValidString, parseVersionString, isValidNumber, createDirectory } from './utils/export.js';
 import { dev, plg, typ } from './matterbridgeTypes.js';
 import { PluginManager } from './pluginManager.js';
@@ -18,6 +46,9 @@ import { MatterbridgeEndpoint } from './matterbridgeEndpoint.js';
 import { bridge } from './matterbridgeDeviceTypes.js';
 import { Frontend } from './frontend.js';
 import { addVirtualDevices } from './helpers.js';
+/**
+ * Represents the Matterbridge application.
+ */
 export class Matterbridge extends EventEmitter {
     systemInformation = {
         interfaceName: '',
@@ -66,7 +97,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,
@@ -94,15 +125,18 @@ export class Matterbridge extends EventEmitter {
     shutdown = false;
     edge = true;
     failCountLimit = hasParameter('shelly') ? 600 : 120;
-    log = new AnsiLogger({ logName: 'Matterbridge', logTimestampFormat: 4, logLevel: hasParameter('debug') ? "debug" : "info" });
+    // Matterbridge log files
+    log = new AnsiLogger({ logName: 'Matterbridge', logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: hasParameter('debug') ? "debug" /* LogLevel.DEBUG */ : "info" /* LogLevel.INFO */ });
     matterbridgeLoggerFile = 'matterbridge' + (getParameter('profile') ? '.' + getParameter('profile') : '') + '.log';
     matterLoggerFile = 'matter' + (getParameter('profile') ? '.' + getParameter('profile') : '') + '.log';
     plugins;
     devices;
     frontend = new Frontend(this);
+    // Matterbridge storage
     nodeStorageName = 'storage' + (getParameter('profile') ? '.' + getParameter('profile') : '');
     nodeStorage;
     nodeContext;
+    // Cleanup
     hasCleanupStarted = false;
     initialized = false;
     execRunningCount = 0;
@@ -116,19 +150,23 @@ 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
+    // Matter nodes
     serverNode;
     aggregatorNode;
     aggregatorVendorId = VendorId(getIntParameter('vendorId') ?? 0xfff1);
@@ -136,15 +174,31 @@ export class Matterbridge extends EventEmitter {
     aggregatorProductId = getIntParameter('productId') ?? 0x8000;
     aggregatorProductName = getParameter('productName') ?? 'Matterbridge aggregator';
     static instance;
+    // We load asyncronously so is private
     constructor() {
         super();
     }
+    /**
+     * 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;
@@ -158,19 +212,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 {Matterbridge} A promise that resolves to the 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();
@@ -179,8 +245,17 @@ export class Matterbridge extends EventEmitter {
         }
         return Matterbridge.instance;
     }
+    /**
+     * Call cleanup() and dispose MdnsService.
+     *
+     * @param {number} [timeout] - The timeout duration to wait for the cleanup to complete in milliseconds. Default is 1000.
+     * @param {number} [pause] - The pause duration after the cleanup in milliseconds. Default is 250.
+     *
+     * @deprecated This method is deprecated and is ONLY used for jest tests.
+     */
     async destroyInstance(timeout = 1000, pause = 250) {
         this.log.info(`Destroy instance...`);
+        // Save server nodes to close
         const servers = [];
         if (this.bridgeMode === 'bridge') {
             if (this.serverNode)
@@ -198,76 +273,109 @@ export class Matterbridge extends EventEmitter {
                     servers.push(device.serverNode);
             }
         }
+        // Let any already‐queued microtasks run first
         await Promise.resolve();
+        // Wait for the cleanup to finish
         await new Promise((resolve) => {
             setTimeout(resolve, pause);
         });
+        // Cleanup
         await this.cleanup('destroying instance...', false, timeout);
+        // 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`);
         }
+        // Let any already‐queued microtasks run first
         await Promise.resolve();
+        // Wait for the cleanup to finish
         await new Promise((resolve) => {
             setTimeout(resolve, pause);
         });
     }
+    /**
+     * 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 {Promise<void>} A Promise that resolves when the initialization is complete.
+     */
     async initialize() {
+        // Emit the initialize_started event
         this.emit('initialize_started');
+        // 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 createDirectory(this.homeDirectory, 'Matterbridge Home Directory', this.log);
+        // Set the matterbridge directory
         this.matterbridgeDirectory = path.join(this.homeDirectory, '.matterbridge');
         this.matterbridgeInformation.matterbridgeDirectory = this.matterbridgeDirectory;
         await createDirectory(this.matterbridgeDirectory, 'Matterbridge Directory', this.log);
         await createDirectory(path.join(this.matterbridgeDirectory, 'certs'), 'Matterbridge Frontend Certificate Directory', this.log);
         await createDirectory(path.join(this.matterbridgeDirectory, 'uploads'), 'Matterbridge Frontend Uploads Directory', this.log);
+        // Set the matterbridge plugin directory
         this.matterbridgePluginDirectory = path.join(this.homeDirectory, 'Matterbridge');
         this.matterbridgeInformation.matterbridgePluginDirectory = this.matterbridgePluginDirectory;
         await createDirectory(this.matterbridgePluginDirectory, 'Matterbridge Plugin Directory', this.log);
+        // Set the matterbridge cert directory
         this.matterbridgeCertDirectory = path.join(this.homeDirectory, '.mattercert');
         this.matterbridgeInformation.matterbridgeCertDirectory = this.matterbridgeCertDirectory;
         await createDirectory(this.matterbridgeCertDirectory, 'Matterbridge Matter Certificate Directory', this.log);
+        // 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 storage is corrupted. Found -norestore parameter: exiting...`);
@@ -281,14 +389,20 @@ export class Matterbridge extends EventEmitter {
         if (!this.nodeStorage || !this.nodeContext) {
             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(this.environment.get(Crypto));
+        // 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(this.environment.get(Crypto));
+        // Certificate management
         const pairingFilePath = path.join(this.matterbridgeCertDirectory, 'pairing.json');
         try {
+            // eslint-disable-next-line n/no-unsupported-features/node-builtins
             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))
@@ -297,11 +411,14 @@ export class Matterbridge extends EventEmitter {
                 this.aggregatorProductId = 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
+            /* istanbul ignore next if */
             if (pairingFileJson.privateKey && pairingFileJson.certificate && pairingFileJson.intermediateCertificate && pairingFileJson.declaration) {
                 const hexStringToUint8Array = (hexString) => {
                     const matches = hexString.match(/.{1,2}/g);
@@ -319,41 +436,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.matterbridgeLoggerFile), this.log.logLevel, true);
             this.matterbridgeInformation.fileLogger = true;
@@ -362,6 +482,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') {
@@ -392,7 +513,9 @@ export class Matterbridge extends EventEmitter {
         }
         Logger.format = MatterLogFormat.ANSI;
         Logger.setLogger('default', this.createMatterLogger());
+        // Logger.destinations.default.write = this.createMatterLogger();
         this.matterbridgeInformation.matterLoggerLevel = Logger.level;
+        // 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), {
@@ -401,7 +524,9 @@ export class Matterbridge extends EventEmitter {
             });
         }
         this.log.debug(`Matter logLevel: ${Logger.level} fileLoger: ${this.matterbridgeInformation.matterFileLogger}.`);
+        // Log network interfaces
         const networkInterfaces = os.networkInterfaces();
+        // console.log(`Network interfaces:`, networkInterfaces);
         const availableAddresses = Object.entries(networkInterfaces);
         const availableInterfaces = Object.keys(networkInterfaces);
         for (const [ifaceName, ifaces] of availableAddresses) {
@@ -412,6 +537,7 @@ export class Matterbridge extends EventEmitter {
                 });
             }
         }
+        // Set the interface to use for matter server node mdnsInterface
         if (hasParameter('mdnsinterface')) {
             this.mdnsInterface = getParameter('mdnsinterface');
         }
@@ -420,6 +546,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.`);
@@ -432,6 +559,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');
         }
@@ -440,6 +568,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) {
@@ -455,6 +584,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');
         }
@@ -463,6 +593,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) {
@@ -471,6 +602,7 @@ export class Matterbridge extends EventEmitter {
                     isValid = true;
                     break;
                 }
+                /* istanbul ignore next */
                 if (ifaces && ifaces.find((iface) => iface.scopeid && iface.scopeid > 0 && iface.address + '%' + (process.platform === 'win32' ? iface.scopeid : ifaceName) === this.ipv6address)) {
                     this.log.info(`Using ipv6address ${CYAN}${this.ipv6address}${nf} on interface ${CYAN}${ifaceName}${nf} for the Matter server node.`);
                     isValid = true;
@@ -483,6 +615,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');
@@ -491,14 +624,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.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 {
                     const { spawnCommand } = await import('./utils/spawn.js');
@@ -521,6 +659,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 +667,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 +675,18 @@ 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
@@ -599,6 +747,19 @@ export class Matterbridge extends EventEmitter {
                 }
                 index++;
             }
+            /*
+            const serializedRegisteredDevices = await this.nodeContext?.get<SerializedMatterbridgeEndpoint[]>('devices', []);
+            this.log.info(`│ Registered devices (${serializedRegisteredDevices?.length})`);
+            serializedRegisteredDevices?.forEach((device, index) => {
+              if (index !== serializedRegisteredDevices.length - 1) {
+                this.log.info(`├─┬─ plugin ${plg}${device.pluginName}${nf} device: ${dev}${device.deviceName}${nf} uniqueId: ${YELLOW}${device.uniqueId}${nf}`);
+                this.log.info(`│ └─ endpoint ${RED}${device.endpoint}${nf} ${typ}${device.endpointName}${nf} ${debugStringify(device.clusterServersId)}`);
+              } else {
+                this.log.info(`└─┬─ plugin ${plg}${device.pluginName}${nf} device: ${dev}${device.deviceName}${nf} uniqueId: ${YELLOW}${device.uniqueId}${nf}`);
+                this.log.info(`  └─ endpoint ${RED}${device.endpoint}${nf} ${typ}${device.endpointName}${nf} ${debugStringify(device.clusterServersId)}`);
+              }
+            });
+            */
             this.shutdown = true;
             return;
         }
@@ -649,6 +810,7 @@ export class Matterbridge extends EventEmitter {
             this.shutdown = true;
             return;
         }
+        // Start the matter storage and create the matterbridge context
         try {
             await this.startMatterStorage();
         }
@@ -656,18 +818,21 @@ 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'));
             if (plugin) {
                 const matterStorageManager = await this.matterStorageService?.open(plugin.name);
                 if (!matterStorageManager) {
+                    /* istanbul ignore next */
                     this.log.error(`Plugin ${plg}${plugin.name}${er} storageManager not found`);
                 }
                 else {
@@ -686,32 +851,39 @@ 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
         clearTimeout(this.checkUpdateTimeout);
         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
         clearInterval(this.checkUpdateInterval);
         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';
@@ -719,6 +891,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';
@@ -727,10 +900,20 @@ export class Matterbridge extends EventEmitter {
             return;
         }
     }
+    /**
+     * Asynchronously loads and starts the registered plugins.
+     *
+     * This method is responsible for initializing and starting 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;
@@ -748,10 +931,14 @@ export class Matterbridge extends EventEmitter {
             plugin.configured = false;
             plugin.registeredDevices = undefined;
             plugin.addedDevices = 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');
@@ -778,6 +965,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)
@@ -794,12 +984,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) {
@@ -825,19 +1020,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}`);
@@ -853,14 +1051,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 {
                 const { getGlobalNodeModules } = await import('./utils/network.js');
                 this.execRunningCount++;
@@ -875,50 +1076,81 @@ 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;
             }
         };
     }
+    /**
+     * Creates a Matter File Logger.
+     *
+     * @param {string} filePath - The path to the log file.
+     * @param {boolean} [unlink] - 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 {
@@ -929,10 +1161,12 @@ export class Matterbridge extends EventEmitter {
             }
         }
         return async (level, formattedLog) => {
+            /* istanbul ignore if */
             if (fileSize > 100000000) {
-                return;
+                return; // Stop logging if the file size is greater than 100MB
             }
             fileSize += formattedLog.length;
+            /* istanbul ignore if */
             if (fileSize > 100000000) {
                 await fs.appendFile(filePath, `Logging on file has been stopped because the file size is greater than 100MB.` + os.EOL);
                 return;
@@ -965,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.
+     */
     async shutdownProcess() {
         await this.cleanup('shutting down...', false);
     }
+    /**
+     * Update matterbridge and shut down the process.
+     */
     async updateProcess() {
         this.log.info('Updating matterbridge...');
         try {
@@ -984,52 +1227,75 @@ 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] - Indicates whether to restart the instance after cleanup. Default is `false`.
+     * @param {number} [timeout] - The timeout duration to wait for the message exchange to complete in milliseconds. Default is 1000.
+     * @returns {Promise<void>} A promise that resolves when the cleanup is completed.
+     */
     async cleanup(message, restart = false, timeout = 1000) {
         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) {
                 clearTimeout(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');
             }
+            // Call the shutdown method of each plugin and clear the plugins reachability timeout
             for (const plugin of this.plugins) {
                 if (!plugin.enabled || plugin.error)
                     continue;
@@ -1040,9 +1306,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, timeout));
+            await new Promise((resolve) => setTimeout(resolve, timeout)); // Wait for MessageExchange to finish
             if (this.bridgeMode === 'bridge') {
                 if (this.serverNode) {
                     await this.stopServerNode(this.serverNode);
@@ -1064,6 +1331,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();
@@ -1073,18 +1341,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}...`);
@@ -1101,8 +1387,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 });
@@ -1116,6 +1404,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 });
@@ -1130,12 +1419,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...');
@@ -1156,6 +1446,13 @@ export class Matterbridge extends EventEmitter {
             this.log.debug('Cleanup already started...');
         }
     }
+    /**
+     * Creates and configures the server node for a single not bridged device.
+     *
+     * @param {RegisteredPlugin} plugin - The plugin to configure.
+     * @param {MatterbridgeEndpoint} device - The device to associate with the plugin.
+     * @returns {Promise<void>} A promise that resolves when the server node for the accessory plugin is created and configured.
+     */
     async createDeviceServerNode(plugin, device) {
         if (device.mode === 'server' && !device.serverNode && device.deviceType && device.deviceName && device.vendorId && device.vendorName && device.productId && device.productName) {
             this.log.debug(`Creating device ${plg}${plugin.name}${db}:${dev}${device.deviceName}${db} server node...`);
@@ -1166,6 +1463,14 @@ export class Matterbridge extends EventEmitter {
             this.log.debug(`Added ${plg}${plugin.name}${db}:${dev}${device.deviceName}${db} to server node`);
         }
     }
+    /**
+     * 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] - Whether to start the server node after adding the device. Default is `false`.
+     * @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.deviceType && device.deviceName && device.vendorId && device.productId && device.vendorName && device.productName) {
             plugin.locked = true;
@@ -1179,6 +1484,12 @@ export class Matterbridge extends EventEmitter {
                 await this.startServerNode(plugin.serverNode);
         }
     }
+    /**
+     * Creates and configures the server node and the aggregator node for a dynamic plugin.
+     *
+     * @param {RegisteredPlugin} plugin - The plugin to configure.
+     * @returns {Promise<void>} A promise that resolves when the server node and the aggregator node for the dynamic plugin is created and configured.
+     */
     async createDynamicPlugin(plugin) {
         if (!plugin.locked) {
             plugin.locked = true;
@@ -1189,7 +1500,14 @@ export class Matterbridge extends EventEmitter {
             await plugin.serverNode.add(plugin.aggregatorNode);
         }
     }
+    /**
+     * 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,13 +1546,16 @@ export class Matterbridge extends EventEmitter {
             clearInterval(this.startMatterInterval);
             this.startMatterInterval = undefined;
             this.log.debug('Cleared startMatterInterval interval for Matterbridge');
-            this.startServerNode(this.serverNode);
+            // Start the Matter server node
+            this.startServerNode(this.serverNode); // We don't await this, because the server node is started in the background
+            // Start the Matter server node of single devices in mode 'server'
             for (const device of this.devices.array()) {
                 if (device.mode === 'server' && device.serverNode) {
                     this.log.debug(`Starting server node for device ${dev}${device.deviceName}${db} in server mode...`);
-                    this.startServerNode(device.serverNode);
+                    this.startServerNode(device.serverNode); // We don't await this, because the server node is started in the background
                 }
             }
+            // Configure the plugins
             this.configureTimeout = setTimeout(async () => {
                 for (const plugin of this.plugins) {
                     if (!plugin.enabled || !plugin.loaded || !plugin.started || plugin.error)
@@ -1252,16 +1573,24 @@ export class Matterbridge extends EventEmitter {
                 }
                 this.frontend.wssSendRefreshRequired('plugins');
             }, 30 * 1000).unref();
+            // Setting reachability to true
             this.reachabilityTimeout = setTimeout(() => {
                 this.log.info(`Setting reachability to true for ${plg}Matterbridge${db}`);
                 if (this.aggregatorNode)
                     this.setAggregatorReachability(this.aggregatorNode, true);
                 this.frontend.wssSendRefreshRequired('reachability');
             }, 60 * 1000).unref();
+            // Logger.get('LogServerNode').info(this.serverNode);
             this.emit('bridge_started');
             this.log.notice('Matterbridge bridge started successfully');
         }, 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');
@@ -1298,8 +1627,9 @@ export class Matterbridge extends EventEmitter {
                 return;
             clearInterval(this.startMatterInterval);
             this.startMatterInterval = undefined;
-            await new Promise((resolve) => setTimeout(resolve, 1000));
+            await new Promise((resolve) => setTimeout(resolve, 1000)); // Wait 1 second to ensure all plugins server nodes are ready
             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)
@@ -1336,7 +1666,9 @@ export class Matterbridge extends EventEmitter {
                     this.log.error(`Node storage context not found for plugin ${plg}${plugin.name}${er}`);
                     continue;
                 }
-                this.startServerNode(plugin.serverNode);
+                // Start the Matter server node
+                this.startServerNode(plugin.serverNode); // We don't await this, because the server node is started in the background
+                // 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)
@@ -1344,19 +1676,241 @@ export class Matterbridge extends EventEmitter {
                     this.frontend.wssSendRefreshRequired('reachability');
                 }, 60 * 1000).unref();
             }
+            // Start the Matter server node of single devices in mode 'server'
             for (const device of this.devices.array()) {
                 if (device.mode === 'server' && device.serverNode) {
                     this.log.debug(`Starting server node for device ${dev}${device.deviceName}${db} in server mode...`);
-                    this.startServerNode(device.serverNode);
+                    this.startServerNode(device.serverNode); // We don't await this, because the server node is started in the background
                 }
             }
+            // Logger.get('LogServerNode').info(this.serverNode);
             this.emit('childbridge_started');
             this.log.notice('Matterbridge childbridge started successfully');
         }, 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');
+          await this.cleanup('No storage manager initialized');
+          return;
+        }
+        this.log.info('Creating context: mattercontrollerContext');
+        this.controllerContext = this.matterStorageManager.createContext('mattercontrollerContext');
+        if (!this.controllerContext) {
+          this.log.error('No storage context mattercontrollerContext initialized');
+          await this.cleanup('No storage context mattercontrollerContext initialized');
+          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 with name Matterbridge, create the matterbridge context and performs a backup.
+     *
+     * @returns {Promise<void>} - A promise that resolves when the storage is started.
+     */
     async startMatterStorage() {
+        // Setup Matter storage
         this.log.info(`Starting matter node storage...`);
         this.matterStorageService = this.environment.get(StorageService);
         this.log.info(`Matter node storage service created: ${this.matterStorageService.location}`);
@@ -1365,8 +1919,17 @@ 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 {string} storageName - The name of the storage directory to be backed up.
+     * @param {string} backupName - The name of the backup directory to be created.
+     * @private
+     * @returns {Promise<void>} A promise that resolves when the has been done.
+     */
     async backupMatterStorage(storageName, backupName) {
         this.log.info('Creating matter node storage backup...');
         try {
@@ -1377,6 +1940,11 @@ export class Matterbridge extends EventEmitter {
             this.log.error(`Error creating matter node storage backup from ${storageName} to ${backupName}:`, error);
         }
     }
+    /**
+     * 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();
@@ -1385,6 +1953,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)
@@ -1418,6 +1999,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] - The port number for the server node. Defaults to 5540.
+     * @param {number} [passcode] - The passcode for the server node. Defaults to 20242025.
+     * @param {number} [discriminator] - The discriminator for the server node. Defaults to 3850.
+     * @returns {Promise<ServerNode<ServerNode.RootEndpoint>>} A promise that resolves to the created server node.
+     */
     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}...`);
@@ -1427,24 +2017,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'),
@@ -1461,14 +2064,20 @@ export class Matterbridge extends EventEmitter {
                 reachable: true,
             },
         });
+        /**
+         * This event is triggered when the device is initially commissioned successfully.
+         * This means: It is added to the first fabric.
+         */
         serverNode.lifecycle.commissioned.on(() => {
             this.log.notice(`Server node for ${storeId} was initially commissioned successfully!`);
             clearTimeout(this.endAdvertiseTimeout);
         });
+        /** 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!`);
             clearTimeout(this.endAdvertiseTimeout);
         });
+        /** 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) {
@@ -1476,6 +2085,7 @@ export class Matterbridge extends EventEmitter {
                 const { qrPairingCode, manualPairingCode } = serverNode.state.commissioning.pairingCodes;
                 this.log.notice(`QR Code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=${qrPairingCode}`);
                 this.log.notice(`Manual pairing code: ${manualPairingCode}`);
+                // Set a timeout to show that advertising stops after 15 minutes if not commissioned
                 this.startEndAdvertiseTimer(serverNode);
             }
             else {
@@ -1486,14 +2096,19 @@ export class Matterbridge extends EventEmitter {
             this.frontend.wssSendSnackbarMessage(`${storeId} is online`, 5, 'success');
             this.emit('online', storeId);
         });
+        /** This event is triggered when the device went offline. it is not longer discoverable or connectable in the network. */
         serverNode.lifecycle.offline.on(() => {
             this.log.notice(`Server node for ${storeId} is offline`);
-            this.matterbridgeInformation.matterbridgeEndAdvertise = true;
+            this.matterbridgeInformation.matterbridgeEndAdvertise = true; // Set the end advertise flag to true, so the frontend won't show the QR code anymore
             this.frontend.wssSendRefreshRequired('plugins');
             this.frontend.wssSendRefreshRequired('settings');
             this.frontend.wssSendSnackbarMessage(`${storeId} is offline`, 5, 'warning');
             this.emit('offline', storeId);
         });
+        /**
+         * This event is triggered when a fabric is added, removed or updated on the device. Use this if more granular
+         * information is needed.
+         */
         serverNode.events.commissioning.fabricsChanged.on((fabricIndex, fabricAction) => {
             let action = '';
             switch (fabricAction) {
@@ -1510,14 +2125,22 @@ export class Matterbridge extends EventEmitter {
             this.log.notice(`Commissioned fabric index ${fabricIndex} ${action} on server node for ${storeId}: ${debugStringify(serverNode.state.commissioning.fabrics[fabricIndex])}`);
             this.frontend.wssSendRefreshRequired('fabrics');
         });
+        /**
+         * This event is triggered when an operative new session was opened by a Controller.
+         * It is not triggered for the initial commissioning process, just afterwards for real connections.
+         */
         serverNode.events.sessions.opened.on((session) => {
             this.log.notice(`Session opened on server node for ${storeId}: ${debugStringify(session)}`);
             this.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)}`);
             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)}`);
             this.frontend.wssSendRefreshRequired('sessions');
@@ -1525,6 +2148,11 @@ export class Matterbridge extends EventEmitter {
         this.log.info(`Created server node for ${storeId}`);
         return serverNode;
     }
+    /**
+     * Starts the 15 minutes timer to advice that advertising for the specified server node is ended.
+     *
+     * @param {ServerNode} [matterServerNode] - The server node to start.
+     */
     startEndAdvertiseTimer(matterServerNode) {
         if (this.endAdvertiseTimeout) {
             this.log.debug(`Clear ${matterServerNode.id} server node end advertise timer`);
@@ -1543,12 +2171,25 @@ export class Matterbridge extends EventEmitter {
             this.log.notice(`Advertising on server node for ${matterServerNode.id} stopped. Restart to commission.`);
         }, 15 * 60 * 1000).unref();
     }
+    /**
+     * 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.
+     * @param {number} [timeout] - The timeout in milliseconds for stopping the server node. Defaults to 30 seconds.
+     * @returns {Promise<void>} A promise that resolves when the server node has stopped.
+     */
     async stopServerNode(matterServerNode, timeout = 30000) {
         if (!matterServerNode)
             return;
@@ -1561,6 +2202,12 @@ export class Matterbridge extends EventEmitter {
             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();
@@ -1569,19 +2216,39 @@ 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`);
@@ -1601,6 +2268,7 @@ export class Matterbridge extends EventEmitter {
         }
         else if (this.bridgeMode === 'bridge') {
             if (device.mode === 'matter') {
+                // Register and add the device to the matterbridge server node
                 this.log.debug(`Adding matter endpoint ${plg}${pluginName}${db}:${dev}${device.deviceName}${db} to Matterbridge server node...`);
                 if (!this.serverNode) {
                     this.log.error('Server node not found for Matterbridge');
@@ -1617,6 +2285,7 @@ export class Matterbridge extends EventEmitter {
                 }
             }
             else {
+                // 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');
@@ -1634,6 +2303,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`);
@@ -1657,10 +2327,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 ready, so we wait for the server node to be ready
                     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}`);
@@ -1683,17 +2355,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`);
@@ -1708,6 +2391,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) {
@@ -1722,8 +2406,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] - 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)) {
@@ -1734,6 +2431,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) {
@@ -1749,6 +2455,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 {
@@ -1762,6 +2474,12 @@ export class Matterbridge extends EventEmitter {
             };
         });
     }
+    /**
+     * Sanitizes the session information by converting bigint properties to strings because `res.json` doesn't support bigint.
+     *
+     * @param {SessionsBehavior.Session[]} sessions - The array of session information objects.
+     * @returns {SanitizedSession[]} An array of sanitized session information objects.
+     */
     sanitizeSessionInformation(sessions) {
         return sessions
             .filter((session) => session.isPeerActive)
@@ -1788,7 +2506,21 @@ 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)
@@ -1828,10 +2560,11 @@ export class Matterbridge extends EventEmitter {
             case 0x1488:
                 vendorName = '(ShortcutLabsFlic)';
                 break;
-            case 65521:
+            case 65521: // 0xFFF1
                 vendorName = '(MatterTest)';
                 break;
         }
         return vendorName;
     };
 }
+//# sourceMappingURL=matterbridge.js.map