matterbridge 1.5.3 → 1.5.5

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project will be documented in this file.
 
 If you like this project and find it useful, please consider giving it a star on GitHub at https://github.com/Luligu/matterbridge and sponsoring it.
 
+### Home Assistant Community Add-ons
+
+The Home Assistant Community Add-ons and plugins are not verified to work with Matterbridge. I strongly advise against using them. If you do use them and encounter an issue (which is likely because some do not meet the Matterbridge guidelines), please do not open an issue in the Matterbridge repository.
+
+## [1.5.5] - 2024-09-09
+
+### Changed
+
+- [matterbridge]: Changed startMatterInterval from 30 to 60 seconds.
+- [package]: Update matter-node.js to 0.10.1.
+- [package]: Update matter-history to 1.1.11.
+- [package]: Update dependencies.
+
+<a href="https://www.buymeacoffee.com/luligugithub">
+  <img src="./yellow-button.png" alt="Buy me a coffee" width="120">
+</a>
+
+## [1.5.4] - 2024-09-05
+
+### Changed
+
+- [package]: Update dependencies.
+- [package]: Final update to matter-node.js 0.10.0.
+- [package]: Removed all local matter 1.3 clusters now present in matter.js.
+
+<a href="https://www.buymeacoffee.com/luligugithub">
+  <img src="./yellow-button.png" alt="Buy me a coffee" width="120">
+</a>
+
 ## [1.5.3] - 2024-09-04
 
 ### Added

package/README-DEV.md

@@ -16,10 +16,10 @@
 
 ## Guidelines on imports/exports
 
-Matterbridge export from:
+Matterbridge exports from:
 
 "matterbridge"
-- Matterbridge and MatterbridgeDevice class.
+- Matterbridge and all Matterbridge related classes.
 - All relevant matter-node.js or matter.js clusters, classes and functions.
 
 "matterbridge/cluster"
@@ -38,12 +38,21 @@ Matterbridge export from:
 - NodeStorage classes.
 
 # **********
-A plugin will never ever install and import from matter-node.js or matter.js directly cause this leads to a second instance of matter.js that causes instability and unpredictable errors like "The only instance is Enpoint". 
+A plugin must never install or import from `matter-node.js` or `matter.js` directly, as this leads to a second instance of `matter.js`, causing instability and unpredictable errors such as "The only instance is Endpoint". Additionally, when Matterbridge updates the `matter.js` version, it should be consistent across all plugins.
+# **********
+A plugin must never install Matterbridge (neither as dependencies nor as devDependencies). Matterbridge must be linked to the plugin:
+```json
+"scripts": {
+    '''
+    "install": "node link-matterbridge-script.js",
+    '''
+}    
+```
 # **********
 
 In the next releases I will remove the duplicated exports so please update your plugins.
 
-I will also add some error messages when a plugin has wrong imports.
+I added some error messages when a plugin has wrong imports or configurations and the plugin will be disabled to prevent instability and crashes.
 
 ## Guidelines on the migration to matter.js V8
 

package/README.md

@@ -132,6 +132,10 @@ Config editor:
 
 [Advanced configurations](https://github.com/Luligu/matterbridge/blob/main/README-DOCKER.md)
 
+### Home Assistant Community Add-ons
+
+The Home Assistant Community Add-ons and plugins are not verified to work with Matterbridge. I strongly advise against using them. If you do use them and encounter an issue (which is likely because some do not meet the Matterbridge guidelines), please do not open an issue in the Matterbridge repository.
+
 ## Development
 
 [Development](https://github.com/Luligu/matterbridge/blob/main/README-DEV.md)
@@ -201,14 +205,29 @@ An Accessory platform plugin only exposes one device.
 
 This an example of a dynamic platform plugin.
 
-It exposes a switch with onOff, a light with onOff-levelControl-colorControl, an outlet with onOff and a WindoweCovering device.
+It exposes:
+- a switch with onOff cluster
+- a light with onOff
+- a light with onOff and levelControl (dimmer)
+- a light with onOff, levelControl and colorControl (with XY, HS and CT) clusters
+- a light with onOff, levelControl and colorControl (with HS only) clusters
+- a light with onOff, levelControl and colorControl (with XY only) clusters
+- a light with onOff, levelControl and colorControl (with CT only) clusters
+- an outlet (plug) with onOff cluster
+- a cover with windowCovering cluster
+- a lock with doorLock cluster
+- a thermo with thermostat cluster and 3 sub endpoints with flowMeasurement cluster, temperatureMeasurement cluster
+  and relativeHumidityMeasurement cluster (to show how to create a composed device with sub endpoints)
+- a fan with FanControl cluster
+- a rainSensor device
+- a waterFreezeDetector device
+- a waterLeakDetector device
+- a smokeCoAlarm device
 
 All these virtual devices continuously change state and position. The plugin also shows how to use all the command handlers (you can control all the devices).
 
 A Dynamic platform plugin exposes as many devices as you need (the limit for the Home app is 150 accessories for bridge).
 
-Matterbridge can run as many plugins as you want.
-
 [See the plugin homepage here](https://github.com/Luligu/matterbridge-example-dynamic-platform)
 
 ### Example plugins to show the usage of history in matter
@@ -231,7 +250,6 @@ The Eve app only shows the history when the plugins run like an AccessoryPlatfor
 
 Just open the frontend on the link provided in the log, select a plugin and click install.
 
-
 ## How to install and add a plugin manually from a terminal (from npm)
 
 To install i.e. https://github.com/Luligu/matterbridge-zigbee2mqtt
@@ -314,15 +332,18 @@ All issues have been solved from the version 17.5 of the HomePod/AppleTV. Now th
 
 So far is the only controller supporting some Matter 1.2 and 1.3 device type:
 
-- air quality sensor (Matter 1.2)
-
-Also supports (probably only like BooleanState cluster):
+- airQualitySensor code 0x002c (Matter 1.2)
+- waterFreezeDetector code 0x0041 (Matter 1.3 with only BooleanState cluster)
+- waterLeakDetector code 0x0043 (Matter 1.3 with only BooleanState cluster)
+- rainSensor code 0x0044 (Matter 1.3 with only BooleanState cluster)
+- deviceEnergyManagement code 0x050d (Matter 1.3 with only DeviceEnergyManagementMode cluster)
 
-- waterFreezeDetector (Matter 1.3)
-- waterLeakDetector (Matter 1.3)
-- rainSensor (Matter 1.3)
+Electrical measurements:
+- electrical measurements from EveHistoryCluster (used in Matterbridge plugins)
+- electricalSensor code 0x0510 with clusters: ElectricalPowerMeasurement and ElectricalEnergyMeasurement (still in dev but fully working!)
 
-HA also support electrical measurements from EveHistoryCluster (used in Matterbridge plugins)
+Other supported cluster:
+- ModeSelect
 
 ## Home Assistant issues (Matter Server for HA is still in Beta)
 

package/dist/cluster/export.d.ts

@@ -1,22 +1,2 @@
-export * from './AirQualityCluster.js';
-export * from './CarbonDioxideConcentrationMeasurementCluster.js';
-export * from './CarbonMonoxideConcentrationMeasurementCluster.js';
-export * from './ConcentrationMeasurementCluster.js';
-export * from './DeviceEnergyManagementCluster.js';
-export * from './DeviceEnergyManagementModeCluster.js';
-export * from './ElectricalEnergyMeasurementCluster.js';
-export * from './ElectricalPowerMeasurementCluster.js';
-export * from './FormaldehydeConcentrationMeasurementCluster.js';
-export * from './MeasurementAccuracy.js';
-export * from './MeasurementAccuracyRange.js';
-export * from './MeasurementType.js';
-export * from './NitrogenDioxideConcentrationMeasurementCluster.js';
-export * from './OzoneConcentrationMeasurementCluster.js';
-export * from './Pm10ConcentrationMeasurementCluster.js';
-export * from './Pm1ConcentrationMeasurementCluster.js';
-export * from './Pm25ConcentrationMeasurementCluster.js';
-export * from './PowerTopologyCluster.js';
-export * from './RadonConcentrationMeasurementCluster.js';
-export * from './SmokeCoAlarmCluster.js';
-export * from './TvocCluster.js';
+export {};
 //# sourceMappingURL=export.d.ts.map

package/dist/cluster/export.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/cluster/export.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,mDAAmD,CAAC;AAClE,cAAc,oDAAoD,CAAC;AACnE,cAAc,sCAAsC,CAAC;AACrD,cAAc,oCAAoC,CAAC;AACnD,cAAc,wCAAwC,CAAC;AACvD,cAAc,yCAAyC,CAAC;AACxD,cAAc,wCAAwC,CAAC;AACvD,cAAc,kDAAkD,CAAC;AACjE,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,qDAAqD,CAAC;AACpE,cAAc,2CAA2C,CAAC;AAC1D,cAAc,0CAA0C,CAAC;AACzD,cAAc,yCAAyC,CAAC;AACxD,cAAc,0CAA0C,CAAC;AACzD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/cluster/export.ts"],"names":[],"mappings":""}

package/dist/cluster/export.js

@@ -1,22 +1,3 @@
-export * from './AirQualityCluster.js';
-export * from './CarbonDioxideConcentrationMeasurementCluster.js';
-export * from './CarbonMonoxideConcentrationMeasurementCluster.js';
-export * from './ConcentrationMeasurementCluster.js';
-export * from './DeviceEnergyManagementCluster.js';
-export * from './DeviceEnergyManagementModeCluster.js';
-export * from './ElectricalEnergyMeasurementCluster.js';
-export * from './ElectricalPowerMeasurementCluster.js';
-export * from './FormaldehydeConcentrationMeasurementCluster.js';
-export * from './MeasurementAccuracy.js';
-export * from './MeasurementAccuracyRange.js';
-export * from './MeasurementType.js';
-export * from './NitrogenDioxideConcentrationMeasurementCluster.js';
-export * from './OzoneConcentrationMeasurementCluster.js';
-export * from './Pm10ConcentrationMeasurementCluster.js';
-export * from './Pm1ConcentrationMeasurementCluster.js';
-export * from './Pm25ConcentrationMeasurementCluster.js';
-export * from './PowerTopologyCluster.js';
-export * from './RadonConcentrationMeasurementCluster.js';
-export * from './SmokeCoAlarmCluster.js';
-export * from './TvocCluster.js';
+export {};
+// Nothing to export
 //# sourceMappingURL=export.js.map

package/dist/cluster/export.js.map

@@ -1 +1 @@
-{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/cluster/export.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,mDAAmD,CAAC;AAClE,cAAc,oDAAoD,CAAC;AACnE,cAAc,sCAAsC,CAAC;AACrD,cAAc,oCAAoC,CAAC;AACnD,cAAc,wCAAwC,CAAC;AACvD,cAAc,yCAAyC,CAAC;AACxD,cAAc,wCAAwC,CAAC;AACvD,cAAc,kDAAkD,CAAC;AACjE,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,qDAAqD,CAAC;AACpE,cAAc,2CAA2C,CAAC;AAC1D,cAAc,0CAA0C,CAAC;AACzD,cAAc,yCAAyC,CAAC;AACxD,cAAc,0CAA0C,CAAC;AACzD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/cluster/export.ts"],"names":[],"mappings":";AAAA,oBAAoB"}

package/dist/matterbridge.js

@@ -219,7 +219,7 @@ export class Matterbridge extends EventEmitter {
         if (hasParameter('docker'))
             this.restartMode = 'docker';
         // Set the matterbridge directory
-        this.homeDirectory = os.homedir();
+        this.homeDirectory = getParameter('homedir') ?? os.homedir();
         this.matterbridgeDirectory = path.join(this.homeDirectory, '.matterbridge');
         // Initialize nodeStorage and nodeContext
         // this.log.debug(`Creating node storage manager: ${CYAN}${this.nodeStorageName}${db}`);
@@ -411,8 +411,8 @@ export class Matterbridge extends EventEmitter {
       - list:                  list the registered plugins
       - loginterfaces:         log the network interfaces (usefull for finding the name of the interface to use with -mdnsinterface option)
       - logstorage:            log the node storage
-      - sudo:                  force the use of sudo to install or update packages
-      - nosudo:                force not to use sudo to install or update packages
+      - sudo:                  force the use of sudo to install or update packages if the internal logic fails
+      - nosudo:                force not to use sudo to install or update packages if the internal logic fails
       - ssl:                   enable SSL for the frontend and WebSockerServer (certificates in .matterbridge/certs directory cert.pem, key.pem and ca.pem (optional))
       - add [plugin path]:     register the plugin from the given absolute or relative path
       - add [plugin name]:     register the globally installed plugin with the given name
@@ -600,7 +600,7 @@ export class Matterbridge extends EventEmitter {
                 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. Disabling it.`);
+                    this.log.error(`Plugin ${plg}${plugin.name}${er} not found or not validated. Disabling it.`);
                     plugin.enabled = false;
                     plugin.error = true;
                     continue;
@@ -638,7 +638,7 @@ export class Matterbridge extends EventEmitter {
                 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. Disabling it.`);
+                    this.log.error(`Plugin ${plg}${plugin.name}${er} not found or not validated. Disabling it.`);
                     plugin.enabled = false;
                     plugin.error = true;
                     continue;
@@ -756,7 +756,7 @@ export class Matterbridge extends EventEmitter {
         this.log.debug(`- Free Memory: ${this.systemInformation.freeMemory}`);
         this.log.debug(`- System Uptime: ${this.systemInformation.systemUptime}`);
         // Home directory
-        this.homeDirectory = os.homedir();
+        this.homeDirectory = getParameter('homedir') ?? os.homedir();
         this.matterbridgeInformation.homeDirectory = this.homeDirectory;
         this.log.debug(`Home Directory: ${this.homeDirectory}`);
         // Package root directory
@@ -1425,7 +1425,7 @@ export class Matterbridge extends EventEmitter {
     async startBridge() {
         // Plugins are loaded and started by loadPlugin on startup and plugin.loaded and plugin.started are set to true
         // Plugins are configured by a timer when matter server is started and plugin.configured is set to true
-        this.log.debug('***Starting startMatterInterval in bridge mode');
+        this.log.debug('Starting startMatterInterval in bridge mode');
         let failCount = 0;
         this.startMatterInterval = setInterval(async () => {
             for (const plugin of this.plugins) {
@@ -1435,16 +1435,16 @@ export class Matterbridge extends EventEmitter {
                 if (plugin.error) {
                     clearInterval(this.startMatterInterval);
                     this.startMatterInterval = undefined;
-                    this.log.debug('***Cleared startMatterInterval interval for Matterbridge for plugin in error state');
+                    this.log.debug('Cleared startMatterInterval interval for Matterbridge for plugin in error state');
                     this.log.error(`The plugin ${plg}${plugin.name}${er} is in error state.`);
                     this.log.error('The bridge will not start until the problem is solved to prevent the controllers from deleting all registered devices.');
                     this.log.error('If you want to start the bridge disable the plugin in error state and restart.');
                     return;
                 }
                 if (!plugin.loaded || !plugin.started) {
-                    this.log.debug(`***Waiting (failSafeCount=${failCount}/30) in startMatterInterval interval for plugin ${plg}${plugin.name}${db} loaded: ${plugin.loaded} started: ${plugin.started}...`);
+                    this.log.debug(`Waiting (failSafeCount=${failCount}/60) in startMatterInterval interval for plugin ${plg}${plugin.name}${db} loaded: ${plugin.loaded} started: ${plugin.started}...`);
                     failCount++;
-                    if (failCount > 30) {
+                    if (failCount > 60) {
                         this.log.error(`Error waiting for plugin ${plg}${plugin.name}${er} to load and start. Plugin is in error state.`);
                         plugin.error = true;
                     }
@@ -1453,7 +1453,7 @@ export class Matterbridge extends EventEmitter {
             }
             clearInterval(this.startMatterInterval);
             this.startMatterInterval = undefined;
-            this.log.debug('***Cleared startMatterInterval interval for Matterbridge');
+            this.log.debug('Cleared startMatterInterval interval for Matterbridge');
             await this.startMatterServer();
             this.log.notice('Matter server started');
             // Configure the plugins
@@ -1491,7 +1491,7 @@ export class Matterbridge extends EventEmitter {
         // Plugins are loaded and started by loadPlugin on startup and plugin.loaded and plugin.started are set to true
         // addDevice and addBridgedDeevice create the commissionig servers and add the devices to the the commissioning server or to the aggregator
         // Plugins are configured by a timer when matter server is started and plugin.configured is set to true
-        this.log.debug('***Starting start matter interval in childbridge mode...');
+        this.log.debug('Starting start matter interval in childbridge mode...');
         let failCount = 0;
         this.startMatterInterval = setInterval(async () => {
             let allStarted = true;
@@ -1502,18 +1502,18 @@ export class Matterbridge extends EventEmitter {
                 if (plugin.error) {
                     clearInterval(this.startMatterInterval);
                     this.startMatterInterval = undefined;
-                    this.log.debug('***Cleared startMatterInterval interval for Matterbridge for plugin in error state');
+                    this.log.debug('Cleared startMatterInterval interval for Matterbridge for plugin in error state');
                     this.log.error(`The plugin ${plg}${plugin.name}${er} is in error state.`);
                     this.log.error('The bridge will not start until the problem is solved to prevent the controllers from deleting all registered devices.');
                     this.log.error('If you want to start the bridge disable the plugin in error state and restart.');
                     return;
                 }
-                this.log.debug(`***Checking plugin ${plg}${plugin.name}${db} to start matter in childbridge mode...`);
+                this.log.debug(`Checking plugin ${plg}${plugin.name}${db} to start matter in childbridge mode...`);
                 if (!plugin.loaded || !plugin.started) {
                     allStarted = false;
-                    this.log.debug(`***Waiting (failSafeCount=${failCount}/30) for plugin ${plg}${plugin.name}${db} to load (${plugin.loaded}) and start (${plugin.started}) ...`);
+                    this.log.debug(`Waiting (failSafeCount=${failCount}/60) for plugin ${plg}${plugin.name}${db} to load (${plugin.loaded}) and start (${plugin.started}) ...`);
                     failCount++;
-                    if (failCount > 30) {
+                    if (failCount > 60) {
                         this.log.error(`Error waiting for plugin ${plg}${plugin.name}${er} to load and start. Plugin is in error mode.`);
                         plugin.error = true;
                     }
@@ -1523,7 +1523,7 @@ export class Matterbridge extends EventEmitter {
                 return;
             clearInterval(this.startMatterInterval);
             this.startMatterInterval = undefined;
-            this.log.debug('***Cleared startMatterInterval interval in childbridge mode');
+            this.log.debug('Cleared startMatterInterval interval in childbridge mode');
             await this.startMatterServer();
             this.log.notice('Matter server started');
             // Configure the plugins
@@ -2475,7 +2475,7 @@ export class Matterbridge extends EventEmitter {
                 this.wssSendMessage('spawn', this.log.now(), 'Matterbridge:spawn', `child process closed with code ${code} and signal ${signal}`);
                 if (code === 0) {
                     if (cmdLine.startsWith('npm install -g'))
-                        this.log.notice(`${cmdLine.replace('npm install -g ', '')} installed correctly`);
+                        this.log.notice(`${cmdLine.replace('npm install -g ', '').replace('--verbose', '')} installed correctly`);
                     this.log.debug(`Child process "${cmdLine}" closed with code ${code} and signal ${signal}`);
                     resolve();
                 }
@@ -3139,7 +3139,7 @@ export class Matterbridge extends EventEmitter {
             if (command === 'update') {
                 this.log.info('Updating matterbridge...');
                 try {
-                    await this.spawnCommand('npm', ['install', '-g', 'matterbridge']);
+                    await this.spawnCommand('npm', ['install', '-g', 'matterbridge', '--verbose']);
                     this.log.info('Matterbridge has been updated. Full restart required.');
                     // eslint-disable-next-line @typescript-eslint/no-unused-vars
                 }
@@ -3174,7 +3174,7 @@ export class Matterbridge extends EventEmitter {
                 param = param.replace(/\*/g, '\\');
                 this.log.info(`Installing plugin ${plg}${param}${nf}...`);
                 try {
-                    await this.spawnCommand('npm', ['install', '-g', param]);
+                    await this.spawnCommand('npm', ['install', '-g', param, '--verbose']);
                     this.log.info(`Plugin ${plg}${param}${nf} installed. Full restart required.`);
                     // eslint-disable-next-line @typescript-eslint/no-unused-vars
                 }