matterbridge 3.4.0-dev-20251120-1b65c89 → 3.4.0-dev-20251120-5724e43

package/CHANGELOG.md

@@ -34,7 +34,7 @@ Advantages:
 
 Removed the following long deprecated elements:
 
-- [platform]: Matterbridge instead of PlatformMatterbridge in the platform constructor (deprecated since 3.0.0).
+- [platform]: Matterbridge instead of PlatformMatterbridge in the platform constructor (deprecated since 3.3.0).
 - [endpoint]: uniqueStorageKey instead of id in MatterbridgeEndpointOptions (deprecated since months).
 - [endpoint]: endpointId instead of number in MatterbridgeEndpointOptions (deprecated since months).
 
@@ -43,11 +43,17 @@ Removed the following long deprecated elements:
 - [endpoint]: Added getChildEndpointById() and getChildEndpointByOriginalId().
 - [endpoint]: Deprecated getChildEndpointByName(). Use getChildEndpointById() or getChildEndpointByOriginalId().
 - [platform]: Added wssSendSnackbarMessage method to MatterbridgePlatform for sending snackbar notifications to the frontend.
+- [doorLock]: Added autoRelockTime attribute with default 0.
+- [DevContainer]: Added instructions for testing a plugin with a paired controller when using DevContainer.
+- [platform]: Made internal use methods and properties hard-private.
+- [platform]: Added size(), getDeviceByName(), getDeviceByUniqueId(), getDeviceBySerialNumber(), getDeviceById(), getDeviceByOriginalId(), getDeviceByNumber() and hasDeviceUniqueId().
+- [platform]: Added isReady, isLoaded, isStarted and isConfigured.
 
 ### Changed
 
 - [package]: Updated dependencies.
 - [deviceManager]: Bumped DeviceManager v.1.1.1.
+- [pluginManager]: Bumped PluginManager v.1.3.1.
 - [broadcastServer]: Bumped BroadcastServer v.1.0.3.
 - [jest]: Bumped jestHelpers v.1.0.13.
 - [spawn]: Bumped spawn module v.1.2.0.

package/README-DEV.md

@@ -54,6 +54,12 @@ To start the Dev Container, simply open the project folder in [Visual Studio Cod
 
 Since Dev Container doesn't run in network mode 'host', it is not possible to pair Mattebridge running inside the Dev Container.
 
+When you want to test your plugin with a paired controller, you have several options:
+
+- create a tgz (npm run npmPack) and upload it to a running instance of matterbridge.
+- publish it with tag dev and install it (matterbridge-yourplugin@dev in Install plugins) in a running instance of matterbridge.
+- use a local instance of matterbridge running outside the dev container and install (../matterbridge-yourplugin in Install plugins) or add (../matterbridge-yourplugin in Install plugins) your plugin to it (easiest way). Adjust the path if matterbridge dir and your plugin dir are not in the same parent directory.
+
 ## Guidelines on imports/exports
 
 Matterbridge exports from:

package/dist/frontend.js

@@ -1648,6 +1648,7 @@ export class Frontend extends EventEmitter {
                             else if (data.params.value === 'Fatal') {
                                 Logger.level = MatterLogLevel.FATAL;
                             }
+                            this.matterbridge.matterLogLevel = MatterLogLevel.names[Logger.level];
                             let callbackLogLevel = "notice";
                             if (this.matterbridge.getLogLevel() === "info" || Logger.level === MatterLogLevel.INFO)
                                 callbackLogLevel = "info";

package/dist/matterbridge.js

@@ -66,8 +66,10 @@ export class Matterbridge extends EventEmitter {
     virtualMode = 'outlet';
     profile = getParameter('profile');
     log = new AnsiLogger({ logName: 'Matterbridge', logTimestampFormat: 4, logLevel: hasParameter('debug') ? "debug" : "info" });
+    logLevel = this.log.logLevel;
     fileLogger = false;
-    matterLog = new AnsiLogger({ logName: 'Matter', logTimestampFormat: 4, logLevel: "debug" });
+    matterLog = new AnsiLogger({ logName: 'Matter', logTimestampFormat: 4, logLevel: hasParameter('debug') ? "debug" : "info" });
+    matterLogLevel = this.matterLog.logLevel;
     matterFileLogger = false;
     readOnly = hasParameter('readonly') || hasParameter('shelly');
     shellyBoard = hasParameter('shelly');
@@ -320,6 +322,7 @@ export class Matterbridge extends EventEmitter {
         else {
             this.log.logLevel = await this.nodeContext.get('matterbridgeLogLevel', this.shellyBoard ? "notice" : "info");
         }
+        this.logLevel = this.log.logLevel;
         this.frontend.logLevel = this.log.logLevel;
         MatterbridgeEndpoint.logLevel = this.log.logLevel;
         if (hasParameter('filelogger') || (await this.nodeContext.get('matterbridgeFileLog', false))) {
@@ -359,11 +362,12 @@ export class Matterbridge extends EventEmitter {
             Logger.level = (await this.nodeContext.get('matterLogLevel', this.shellyBoard ? MatterLogLevel.NOTICE : MatterLogLevel.INFO));
         }
         Logger.format = MatterLogFormat.ANSI;
+        this.matterLogLevel = MatterLogLevel.names[Logger.level];
         if (hasParameter('matterfilelogger') || (await this.nodeContext.get('matterFileLog', false))) {
             this.matterFileLogger = true;
         }
         Logger.destinations.default.write = this.createDestinationMatterLogger(this.matterFileLogger);
-        this.log.debug(`Matter logLevel: ${Logger.level} fileLoger: ${this.matterFileLogger}.`);
+        this.log.debug(`Matter logLevel: ${this.matterLogLevel} fileLoger: ${this.matterFileLogger}.`);
         const networkInterfaces = os.networkInterfaces();
         const availableAddresses = Object.entries(networkInterfaces);
         const availableInterfaceNames = Object.keys(networkInterfaces);
@@ -841,6 +845,7 @@ export class Matterbridge extends EventEmitter {
         this.log.debug(`Command Line Arguments: ${cmdArgs}`);
     }
     async setLogLevel(logLevel) {
+        this.logLevel = logLevel;
         this.log.logLevel = logLevel;
         this.frontend.logLevel = logLevel;
         MatterbridgeEndpoint.logLevel = logLevel;

package/dist/matterbridgePlatform.js

@@ -20,14 +20,17 @@ export class MatterbridgePlatform {
     version = '1.0.0';
     storage;
     context;
-    selectDevice = new Map();
-    selectEntity = new Map();
-    contextReady;
-    selectDeviceContextReady;
-    selectEntityContextReady;
+    isReady = false;
+    isLoaded = false;
+    isStarted = false;
+    isConfigured = false;
+    #selectDevices = new Map();
+    #selectEntities = new Map();
+    #contextReady;
+    #selectDeviceContextReady;
+    #selectEntityContextReady;
     ready;
-    registeredEndpointsByUniqueId = new Map();
-    registeredEndpointsByName = new Map();
+    #registeredEndpoints = new Map();
     #server;
     #debug = hasParameter('debug') || hasParameter('verbose');
     #verbose = hasParameter('verbose');
@@ -40,8 +43,10 @@ export class MatterbridgePlatform {
             this.log.debug(`Creating MatterbridgePlatform for plugin ${this.config.name}`);
         if (this.#verbose)
             this.log.debug(`Creating MatterbridgePlatform for plugin ${this.config.name} with config:\n${JSON.stringify(this.config, null, 2)}\n`);
-        if (!isValidString(this.config.name, 1))
+        if (!isValidString(this.config.name, 1)) {
+            this.#server.close();
             throw new Error('Platform: the plugin name is missing or invalid.');
+        }
         this.log.debug(`Creating storage for plugin ${this.config.name} in ${path.join(this.matterbridge.matterbridgeDirectory, this.config.name)}`);
         this.storage = new NodeStorageManager({
             dir: path.join(this.matterbridge.matterbridgeDirectory, this.config.name),
@@ -51,32 +56,47 @@ export class MatterbridgePlatform {
             forgiveParseErrors: true,
         });
         this.log.debug(`Creating context for plugin ${this.config.name}`);
-        this.contextReady = this.storage.createStorage('context').then((context) => {
+        this.#contextReady = this.storage.createStorage('context').then((context) => {
             this.context = context;
             this.log.debug(`Created context for plugin ${this.config.name}`);
             return;
         });
         this.log.debug(`Loading selectDevice for plugin ${this.config.name}`);
-        this.selectDeviceContextReady = this.storage.createStorage('selectDevice').then(async (context) => {
+        this.#selectDeviceContextReady = this.storage.createStorage('selectDevice').then(async (context) => {
             const selectDevice = await context.get('selectDevice', []);
             for (const device of selectDevice)
-                this.selectDevice.set(device.serial, device);
-            this.log.debug(`Loaded ${this.selectDevice.size} selectDevice for plugin ${this.config.name}`);
+                this.#selectDevices.set(device.serial, device);
+            this.log.debug(`Loaded ${this.#selectDevices.size} selectDevice for plugin ${this.config.name}`);
             return;
         });
         this.log.debug(`Loading selectEntity for plugin ${this.config.name}`);
-        this.selectEntityContextReady = this.storage.createStorage('selectEntity').then(async (context) => {
+        this.#selectEntityContextReady = this.storage.createStorage('selectEntity').then(async (context) => {
             const selectEntity = await context.get('selectEntity', []);
             for (const entity of selectEntity)
-                this.selectEntity.set(entity.name, entity);
-            this.log.debug(`Loaded ${this.selectEntity.size} selectEntity for plugin ${this.config.name}`);
+                this.#selectEntities.set(entity.name, entity);
+            this.log.debug(`Loaded ${this.#selectEntities.size} selectEntity for plugin ${this.config.name}`);
             return;
         });
-        this.ready = Promise.all([this.contextReady, this.selectDeviceContextReady, this.selectEntityContextReady]).then(() => {
+        this.ready = Promise.all([this.#contextReady, this.#selectDeviceContextReady, this.#selectEntityContextReady]).then(() => {
             this.log.debug(`MatterbridgePlatform for plugin ${this.config.name} is fully initialized`);
+            this.isReady = true;
             return;
         });
     }
+    async destroy() {
+        if (this.#verbose)
+            this.log.debug(`Destroying MatterbridgePlatform for plugin ${this.config.name}`);
+        this.#selectDevices.clear();
+        this.#selectEntities.clear();
+        this.#registeredEndpoints.clear();
+        await this.context?.close();
+        this.context = undefined;
+        await this.storage?.close();
+        this.#server.close();
+        if (this.#verbose)
+            this.log.debug(`Destroyed MatterbridgePlatform for plugin ${this.config.name}`);
+        this.isReady = false;
+    }
     async onStart(reason) {
         this.log.error('Plugins must override onStart.', reason);
         throw new Error('Plugins must override onStart.');
@@ -90,14 +110,7 @@ export class MatterbridgePlatform {
         this.log.debug(`Shutting down platform ${this.name}`, reason);
         await this.saveSelects();
         await this.checkEndpointNumbers();
-        this.selectDevice.clear();
-        this.selectEntity.clear();
-        this.registeredEndpointsByUniqueId.clear();
-        this.registeredEndpointsByName.clear();
-        await this.context?.close();
-        this.context = undefined;
-        await this.storage?.close();
-        this.#server.close();
+        await this.destroy();
     }
     async onChangeLoggerLevel(logLevel) {
         this.log.debug(`The plugin doesn't override onChangeLoggerLevel. Logger level set to: ${logLevel}`);
@@ -135,11 +148,35 @@ export class MatterbridgePlatform {
     wssSendSnackbarMessage(message, timeout, severity) {
         this.#server.request({ type: 'frontend_snackbarmessage', src: 'platform', dst: 'frontend', params: { message, timeout, severity } });
     }
+    size() {
+        return this.#registeredEndpoints.size;
+    }
     getDevices() {
-        return Array.from(this.registeredEndpointsByUniqueId.values());
+        return Array.from(this.#registeredEndpoints.values());
+    }
+    getDeviceByName(deviceName) {
+        return Array.from(this.#registeredEndpoints.values()).find((device) => device.deviceName === deviceName);
+    }
+    getDeviceByUniqueId(uniqueId) {
+        return Array.from(this.#registeredEndpoints.values()).find((device) => device.uniqueId === uniqueId);
+    }
+    getDeviceBySerialNumber(serialNumber) {
+        return Array.from(this.#registeredEndpoints.values()).find((device) => device.serialNumber === serialNumber);
+    }
+    getDeviceById(id) {
+        return Array.from(this.#registeredEndpoints.values()).find((device) => device.maybeId === id);
+    }
+    getDeviceByOriginalId(originalId) {
+        return Array.from(this.#registeredEndpoints.values()).find((device) => device.originalId === originalId);
+    }
+    getDeviceByNumber(number) {
+        return Array.from(this.#registeredEndpoints.values()).find((device) => device.maybeNumber === number);
     }
     hasDeviceName(deviceName) {
-        return this.registeredEndpointsByName.has(deviceName);
+        return Array.from(this.#registeredEndpoints.values()).find((device) => device.deviceName === deviceName) !== undefined;
+    }
+    hasDeviceUniqueId(deviceUniqueId) {
+        return this.#registeredEndpoints.has(deviceUniqueId);
     }
     async registerVirtualDevice(name, type, callback) {
         let aggregator;
@@ -176,7 +213,7 @@ export class MatterbridgePlatform {
             this.log.error(`Device with uniqueId ${CYAN}${device.uniqueId}${er} has no serialNumber. The device will not be added.`);
             return;
         }
-        if (this.registeredEndpointsByName.has(device.deviceName)) {
+        if (this.hasDeviceName(device.deviceName)) {
             this.log.error(`Device with name ${CYAN}${device.deviceName}${er} is already registered. The device will not be added. Please change the device name.`);
             return;
         }
@@ -201,48 +238,44 @@ export class MatterbridgePlatform {
             }
         }
         await this.matterbridge.addBridgedEndpoint(this.name, device);
-        this.registeredEndpointsByUniqueId.set(device.uniqueId, device);
-        this.registeredEndpointsByName.set(device.deviceName, device);
+        this.#registeredEndpoints.set(device.uniqueId, device);
     }
     async unregisterDevice(device) {
         await this.matterbridge.removeBridgedEndpoint(this.name, device);
         if (device.uniqueId)
-            this.registeredEndpointsByUniqueId.delete(device.uniqueId);
-        if (device.deviceName)
-            this.registeredEndpointsByName.delete(device.deviceName);
+            this.#registeredEndpoints.delete(device.uniqueId);
     }
     async unregisterAllDevices(delay = 0) {
         await this.matterbridge.removeAllBridgedEndpoints(this.name, delay);
-        this.registeredEndpointsByUniqueId.clear();
-        this.registeredEndpointsByName.clear();
+        this.#registeredEndpoints.clear();
     }
     async saveSelects() {
         if (this.storage) {
-            this.log.debug(`Saving ${this.selectDevice.size} selectDevice...`);
+            this.log.debug(`Saving ${this.#selectDevices.size} selectDevice...`);
             const selectDevice = await this.storage.createStorage('selectDevice');
-            await selectDevice.set('selectDevice', Array.from(this.selectDevice.values()));
+            await selectDevice.set('selectDevice', Array.from(this.#selectDevices.values()));
             await selectDevice.close();
-            this.log.debug(`Saving ${this.selectEntity.size} selectEntity...`);
+            this.log.debug(`Saving ${this.#selectEntities.size} selectEntity...`);
             const selectEntity = await this.storage.createStorage('selectEntity');
-            await selectEntity.set('selectEntity', Array.from(this.selectEntity.values()));
+            await selectEntity.set('selectEntity', Array.from(this.#selectEntities.values()));
             await selectEntity.close();
         }
     }
     async clearSelect() {
-        this.selectDevice.clear();
-        this.selectEntity.clear();
+        this.#selectDevices.clear();
+        this.#selectEntities.clear();
         await this.saveSelects();
     }
     async clearDeviceSelect(serial) {
-        this.selectDevice.delete(serial);
+        this.#selectDevices.delete(serial);
         await this.saveSelects();
     }
     async clearEntitySelect(name) {
-        this.selectEntity.delete(name);
+        this.#selectEntities.delete(name);
         await this.saveSelects();
     }
     setSelectDevice(serial, name, configUrl, icon, entities) {
-        const device = this.selectDevice.get(serial);
+        const device = this.#selectDevices.get(serial);
         if (device) {
             device.serial = serial;
             device.name = name;
@@ -254,11 +287,14 @@ export class MatterbridgePlatform {
                 device.entities = entities;
         }
         else {
-            this.selectDevice.set(serial, { serial, name, configUrl, icon, entities });
+            this.#selectDevices.set(serial, { serial, name, configUrl, icon, entities });
         }
     }
+    getSelectDevice(serial) {
+        return this.#selectDevices.get(serial);
+    }
     setSelectDeviceEntity(serial, entityName, entityDescription, entityIcon) {
-        const device = this.selectDevice.get(serial);
+        const device = this.#selectDevices.get(serial);
         if (device) {
             if (!device.entities)
                 device.entities = [];
@@ -268,17 +304,20 @@ export class MatterbridgePlatform {
     }
     getSelectDevices() {
         const selectDevices = [];
-        for (const device of this.selectDevice.values()) {
+        for (const device of this.#selectDevices.values()) {
             selectDevices.push({ pluginName: this.name, ...device });
         }
         return selectDevices;
     }
     setSelectEntity(name, description, icon) {
-        this.selectEntity.set(name, { name, description, icon });
+        this.#selectEntities.set(name, { name, description, icon });
+    }
+    getSelectEntity(name) {
+        return this.#selectEntities.get(name);
     }
     getSelectEntities() {
         const selectEntities = [];
-        for (const entity of this.selectEntity.values()) {
+        for (const entity of this.#selectEntities.values()) {
             selectEntities.push({ pluginName: this.name, ...entity });
         }
         return selectEntities;

package/dist/pluginManager.js

@@ -266,6 +266,7 @@ export class PluginManager extends EventEmitter {
         const pluginsArray = await this.matterbridge.nodeContext.get('plugins', []);
         for (const plugin of pluginsArray)
             this._plugins.set(plugin.name, plugin);
+        this.log.debug(`Loaded ${BLUE}${pluginsArray.length}${db} plugins from storage`);
         return pluginsArray;
     }
     async saveToStorage() {
@@ -727,7 +728,7 @@ export class PluginManager extends EventEmitter {
             const { pathToFileURL } = await import('node:url');
             const pluginUrl = pathToFileURL(pluginEntry);
             this.log.debug(`Importing plugin ${plg}${plugin.name}${db} from ${pluginUrl.href}`);
-            const pluginInstance = await import(pluginUrl.href);
+            const pluginInstance = (await import(pluginUrl.href));
             this.log.debug(`Imported plugin ${plg}${plugin.name}${db} from ${pluginUrl.href}`);
             if (pluginInstance.default) {
                 const config = await this.loadConfig(plugin);
@@ -739,12 +740,13 @@ export class PluginManager extends EventEmitter {
                 plugin.schemaJson = await this.loadSchema(plugin);
                 config.name = packageJson.name;
                 config.version = packageJson.version;
-                const log = new AnsiLogger({ logName: plugin.description, logTimestampFormat: 4, logLevel: config.debug ? "debug" : this.matterbridge.log.logLevel });
+                const log = new AnsiLogger({ logName: plugin.description, logTimestampFormat: 4, logLevel: config.debug ? "debug" : this.matterbridge.logLevel });
                 const platform = pluginInstance.default(this.matterbridge, log, config);
                 config.type = platform.type;
                 platform.name = packageJson.name;
                 platform.config = config;
                 platform.version = packageJson.version;
+                platform.isLoaded = true;
                 plugin.name = packageJson.name;
                 plugin.description = packageJson.description ?? 'No description';
                 plugin.version = packageJson.version;
@@ -803,6 +805,7 @@ export class PluginManager extends EventEmitter {
             await plugin.platform.onStart(message);
             this.log.notice(`Started plugin ${plg}${plugin.name}${nt} type ${typ}${plugin.type}${nt}`);
             plugin.started = true;
+            plugin.platform.isStarted = true;
             await this.saveConfigFromPlugin(plugin);
             this.emit('started', plugin.name);
             if (configure)
@@ -845,6 +848,7 @@ export class PluginManager extends EventEmitter {
             await plugin.platform.onConfigure();
             this.log.notice(`Configured plugin ${plg}${plugin.name}${nt} type ${typ}${plugin.type}${nt}`);
             plugin.configured = true;
+            plugin.platform.isConfigured = true;
             this.emit('configured', plugin.name);
             return plugin;
         }
@@ -884,6 +888,10 @@ export class PluginManager extends EventEmitter {
         this.log.info(`Shutting down plugin ${plg}${plugin.name}${nf}: ${reason}...`);
         try {
             await plugin.platform.onShutdown(reason);
+            plugin.platform.isReady = false;
+            plugin.platform.isLoaded = false;
+            plugin.platform.isStarted = false;
+            plugin.platform.isConfigured = false;
             plugin.locked = undefined;
             plugin.error = undefined;
             plugin.loaded = undefined;

package/dist/utils/spawn.js

@@ -8,7 +8,12 @@ export async function spawnCommand(command, args, packageCommand, packageName) {
     const log = new AnsiLogger({ logName: 'Spawn', logTimestampFormat: 4, logLevel: debug ? "debug" : "info" });
     const server = new BroadcastServer('spawn', log);
     const sendLog = (name, message) => {
-        server.request({ type: 'frontend_logmessage', src: 'spawn', dst: 'frontend', params: { level: 'spawn', time: log.now(), name, message } });
+        try {
+            server.request({ type: 'frontend_logmessage', src: 'spawn', dst: 'frontend', params: { level: 'spawn', time: log.now(), name, message } });
+        }
+        catch (err) {
+            log.debug(`Failed to send log message to frontend: ${err instanceof Error ? err.message : String(err)}`);
+        }
     };
     if (verbose)
         log.debug(`Spawning command: ${command} with ${args.join(' ')} ${packageCommand} ${packageName}`);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "matterbridge",
-  "version": "3.4.0-dev-20251120-1b65c89",
+  "version": "3.4.0-dev-20251120-5724e43",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "matterbridge",
-      "version": "3.4.0-dev-20251120-1b65c89",
+      "version": "3.4.0-dev-20251120-5724e43",
       "license": "Apache-2.0",
       "dependencies": {
         "@matter/main": "0.15.6",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matterbridge",
-  "version": "3.4.0-dev-20251120-1b65c89",
+  "version": "3.4.0-dev-20251120-5724e43",
   "description": "Matterbridge plugin manager for Matter",
   "author": "https://github.com/Luligu",
   "license": "Apache-2.0",