matterbridge 3.0.6 → 3.0.7-dev-20250615-2a6da14

package/CHANGELOG.md

@@ -8,6 +8,26 @@ If you like this project and find it useful, please consider giving it a star on
   <img src="bmc-button.svg" alt="Buy me a coffee" width="120">
 </a>
 
+## [3.0.7] - 2025-06-??
+
+### Breaking Changes
+
+- [devices]: The single devices (i.e. Rvc, Evse etc...) are exported from matterbridge/devices. Please update your imports to use the new export path. Refer to the [documentation](README-DEV.md) for details on imports.
+
+### Added
+
+### Changed
+
+- [package]: Updated dependencies.
+- [package]: Downgrade jest to 29.7.0.
+- [energy]: Added parameter for cumulativeEnergyExported to the helper. For solar power device.
+
+### Fixed
+
+<a href="https://www.buymeacoffee.com/luligugithub">
+  <img src="bmc-button.svg" alt="Buy me a coffee" width="80">
+</a>
+
 ## [3.0.6] - 2025-06-13
 
 ### Added

package/README-DEV.md

@@ -18,49 +18,53 @@
 
 Matterbridge exports from:
 
-"matterbridge"
+### "matterbridge"
 
 - Matterbridge and all Matterbridge related classes.
 
-"matterbridge/matter"
+### "matterbridge/devices"
 
-- All relevant matter.js exports.
+- All single device classes like the Rvc, LaundryWasher, etc...
 
-"matterbridge/matter/behaviors"
+### "matterbridge/clusters"
 
-- All matter.js behaviors.
+- All clusters not present in matter.js or modified.
 
-"matterbridge/matter/clusters"
+### "matterbridge/utils"
 
-- All matter.js clusters.
+- All general utils and colorUtils functions.
 
-"matterbridge/matter/devices"
+### "matterbridge/logger"
 
-- All matter.js devices.
+- AnsiLogger class.
 
-"matterbridge/matter/endpoints"
+### "matterbridge/storage"
 
-- All matter.js endpoints.
+- NodeStorageManager and NodeStorage classes.
 
-"matterbridge/matter/types"
+### "matterbridge/matter"
 
-- All matter.js types.
+- All relevant matter.js exports.
 
-"matterbridge/cluster"
+### "matterbridge/matter/behaviors"
 
-- All clusters not present in matter.js or modified.
+- All matter.js behaviors.
 
-"matterbridge/utils"
+### "matterbridge/matter/clusters"
 
-- All general utils and colorUtils functions.
+- All matter.js clusters.
 
-"matterbridge/logger"
+### "matterbridge/matter/devices"
 
-- AnsiLogger class.
+- All matter.js devices.
 
-"matterbridge/storage"
+### "matterbridge/matter/endpoints"
 
-- NodeStorageManager and NodeStorage classes.
+- All matter.js endpoints.
+
+### "matterbridge/matter/types"
+
+- All matter.js types.
 
 # \***\*\*\*\*\***
 
@@ -72,7 +76,7 @@ Additionally, when Matterbridge updates the `matter.js` version, it should be co
 
 A plugin must never install Matterbridge (neither as a dependency, devDependency, nor peerDependency).
 
-Matterbridge must be linked to the plugin in development only.
+Matterbridge must be linked to the plugin in development only. At runtime the plugin is loaded directly from the running Mattebridge instance.
 
 ```json
 "scripts": {
@@ -82,9 +86,9 @@ Matterbridge must be linked to the plugin in development only.
 }
 ```
 
-On the machine you use for development you should also have matterbridge installed globally or built locally and linked (npm link from the package root).
+On the machine you use for development of your plugin, you need to clone matterbridge, built it locally and link it globally (npm link from the matterbridge package root).
 
-Dev and edge branches of matterbridge are not suitable for developemnt cause they are published for production without types. If you want to develop a plugin using the dev or edge branch of matterbridge, you have to clone the dev or edge branch of matterbridge, build locally and link (npm run deepCleanBuild).
+If you want to develop a plugin using the dev branch of matterbridge, you have to clone the dev branch of matterbridge, build it locally and link it (npm run deepCleanBuild).
 
 # \***\*\*\*\*\***
 
@@ -114,7 +118,7 @@ On windows:
 cd $HOME\Matterbridge
 ```
 
-On linux:
+On linux or macOS:
 
 ```
 cd ~/Matterbridge
@@ -126,6 +130,7 @@ then clone the plugin
 git clone https://github.com/Luligu/matterbridge-example-accessory-platform
 cd matterbridge-example-accessory-platform
 npm install
+npm link matterbridge
 npm run build
 ```
 
@@ -150,37 +155,63 @@ The plugin platform type.
 The plugin config (loaded before the platform constructor is called and saved after onShutdown() is called).
 Here you can store your plugin configuration (see matterbridge-zigbee2mqtt for example)
 
+### constructor(matterbridge: Matterbridge, log: AnsiLogger, config: PlatformConfig)
+
+The contructor is called when is plugin is loaded.
+
 ### async onStart(reason?: string)
 
-The method onStart() is where you have to create your MatterbridgeDevice and add all needed clusters and command handlers.
+The method onStart() is where you have to create your MatterbridgeEndpoint and add all needed clusters.
+
+After add the command handlers and subscribe to the attributes when needed.
 
-The MatterbridgeDevice class has the create cluster methods already done and all command handlers needed (see plugin examples).
+The MatterbridgeEndpoint class has the create cluster methods already done and all command handlers needed (see plugin examples).
 
 The method is called when Matterbridge load the plugin.
 
 ### async onConfigure()
 
-The method onConfigure() is where you can configure or initialize your device.
+The method onConfigure() is where you can configure your matter device.
 
-The method is called when the platform is commissioned.
+The method is called when the server node the platform belongs to is online.
+
+Since the persistent attributes are loaded from the storage when the server node goes online, you may need to set them in onConfigure().
 
 ### async onShutdown(reason?: string)
 
-The method onShutdown() is where you have to eventually cleanup some resources.
+The method onShutdown() is where you have to stop your platform and cleanup all the used resources.
+
+The method is called when Matterbridge is shutting down or when the plugin is disabled.
+
+Since the frontend can enable and disable the plugin many times, you need to clean all resources (i.e. handlers, intervals, timers...) here.
+
+### async onChangeLoggerLevel(logLevel: LogLevel)
+
+It is called when the user changes the logger level in the frontend.
+
+### async onAction(action: string, value?: string, id?: string, formData?: PlatformConfig)
+
+It is called when a plugin config includes an action button or an action button with text field.
+
+### async onConfigChanged(config: PlatformConfig)
+
+It is called when the plugin config has been updated.
+
+### hasDeviceName(deviceName: string): boolean
 
-The method is called when Matterbridge is shutting down.
+Checks if a device with this name is already registered in the platform.
 
-### async registerDevice(device: MatterbridgeDevice)
+### async registerDevice(device: MatterbridgeEndpoint)
 
-After you created your device, add it to the platform.
+After you have created your device, add it to the platform.
 
-### async unregisterDevice(device: MatterbridgeDevice)
+### async unregisterDevice(device: MatterbridgeEndpoint)
 
 You can unregister one or more device.
 
 ### async unregisterAllDevices()
 
-You can unregister all devices you added.
+You can unregister all the devices you added.
 
 It can be useful to call this method from onShutdown() if you don't want to keep all the devices during development.
 

package/README.md

@@ -5,7 +5,7 @@
 [![Docker Version](https://img.shields.io/docker/v/luligu/matterbridge?label=docker%20version&sort=semver)](https://hub.docker.com/r/luligu/matterbridge)
 [![Docker Pulls](https://img.shields.io/docker/pulls/luligu/matterbridge.svg)](https://hub.docker.com/r/luligu/matterbridge)
 ![Node.js CI](https://github.com/Luligu/matterbridge/actions/workflows/build.yml/badge.svg)
-![Coverage](https://img.shields.io/badge/Jest%20coverage-88%25-brightgreen)
+![Coverage](https://img.shields.io/badge/Jest%20coverage-89%25-brightgreen)
 
 [![power by](https://img.shields.io/badge/powered%20by-matter--history-blue)](https://www.npmjs.com/package/matter-history)
 [![power by](https://img.shields.io/badge/powered%20by-node--ansi--logger-blue)](https://www.npmjs.com/package/node-ansi-logger)

package/dist/cli.js

@@ -1,46 +1,20 @@
 #!/usr/bin/env node
-/**
- * This file contains the CLI entry point of Matterbridge.
- *
- * @file cli.ts
- * @author Luca Liguori
- * @date 2023-12-29
- * @version 2.0.1
- *
- * 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. *
- */
-// Matterbridge
 import { Matterbridge } from './matterbridge.js';
 import { getIntParameter, hasParameter } from './utils/export.js';
-// AnsiLogger module
 import { AnsiLogger, BRIGHT, CYAN, db, YELLOW } from './logger/export.js';
 import os from 'node:os';
 import { EventEmitter } from 'node:events';
 import { inspect } from 'node:util';
 export const cliEmitter = new EventEmitter();
 export let instance;
-// Inspectop
 let session;
 let snapshotInterval;
-// Cpu and memory check
 let memoryCheckInterval;
 let prevCpus;
 export let lastCpuUsage = 0;
 let peakCpu = 0;
 let peakRss = 0;
-const log = new AnsiLogger({ logName: 'Cli', logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: hasParameter('debug') ? "debug" /* LogLevel.DEBUG */ : "info" /* LogLevel.INFO */ });
+const log = new AnsiLogger({ logName: 'Cli', logTimestampFormat: 4, logLevel: hasParameter('debug') ? "debug" : "info" });
 const formatMemoryUsage = (bytes) => {
     if (bytes >= 1024 ** 3) {
         return `${(bytes / 1024 ** 3).toFixed(2)} GB`;
@@ -68,16 +42,13 @@ const formatOsUpTime = (seconds) => {
     return `${seconds} second${seconds !== 1 ? 's' : ''}`;
 };
 async function startCpuMemoryCheck() {
-    // const os = await import('node:os');
     log.debug(`Cpu memory check started`);
     prevCpus = os.cpus();
     clearInterval(memoryCheckInterval);
     const interval = () => {
-        // Get the os uptime
         const systemUptime = formatOsUpTime(Math.floor(os.uptime()));
         const processUptime = formatOsUpTime(Math.floor(process.uptime()));
         cliEmitter.emit('uptime', systemUptime, processUptime);
-        // Get the memory usage
         const totalMememory = formatMemoryUsage(os.totalmem());
         const freeMemory = formatMemoryUsage(os.freemem());
         const memoryUsageRaw = process.memoryUsage();
@@ -89,12 +60,10 @@ async function startCpuMemoryCheck() {
         if (memoryUsageRaw.rss > peakRss)
             peakRss = memoryUsageRaw.rss;
         cliEmitter.emit('memory', totalMememory, freeMemory, rss, heapTotal, heapUsed, external, arrayBuffers);
-        // Get the cpu usage
         const currCpus = os.cpus();
-        // log.debug(`Cpus: ${JSON.stringify(currCpus)}`);
         let cpuUsageLog;
         if (currCpus.length !== prevCpus.length) {
-            prevCpus = currCpus; // Reset the previous cpus
+            prevCpus = currCpus;
             log.debug(`Cpu check length failed, resetting previous cpus`);
             return;
         }
@@ -120,7 +89,6 @@ async function startCpuMemoryCheck() {
             cliEmitter.emit('cpu', lastCpuUsage);
         }
         prevCpus = currCpus;
-        // Show the cpu and memory usage
         log.debug(`***${YELLOW}${BRIGHT}Cpu usage:${db} ${CYAN}${cpuUsageLog.padStart(6, ' ')} %${db} ${YELLOW}${BRIGHT}Memory usage:${db} rss ${CYAN}${rss}${db} heapTotal ${CYAN}${heapTotal}${db} heapUsed ${CYAN}${heapUsed}${db} external ${external} arrayBuffers ${arrayBuffers}`);
     };
     interval();
@@ -131,15 +99,10 @@ async function stopCpuMemoryCheck() {
     log.debug(`***Cpu memory check stopped. Peak cpu: ${CYAN}${peakCpu.toFixed(2)} %${db}. Peak rss: ${CYAN}${formatMemoryUsage(peakRss)}${db}.`);
     clearInterval(memoryCheckInterval);
 }
-/**
- * Starts the inspector for heap sampling.
- * This function is called when the -inspect parameter is passed.
- */
 async function startInspector() {
     const { Session } = await import('node:inspector');
     const { mkdirSync } = await import('node:fs');
     log.debug(`***Starting heap sampling...`);
-    // Create the heap snapshots directory if it doesn't exist
     mkdirSync('heap_profile', { recursive: true });
     try {
         session = new Session();
@@ -148,7 +111,6 @@ async function startInspector() {
             session?.post('HeapProfiler.startSampling', (err) => (err ? reject(err) : resolve()));
         });
         log.debug(`***Started heap sampling`);
-        // Set an interval to take heap snapshots
         const interval = getIntParameter('snapshotinterval');
         if (interval && interval >= 30000) {
             log.debug(`***Started heap snapshot interval of ${CYAN}${interval}${db} ms`);
@@ -166,19 +128,13 @@ async function startInspector() {
         return;
     }
 }
-/**
- * Stops the heap sampling and saves the profile to a file.
- * This function is called when the inspector is stopped.
- */
 async function stopInspector() {
     const { writeFileSync } = await import('node:fs');
     const path = await import('node:path');
     log.debug(`***Stopping heap sampling...`);
     if (snapshotInterval) {
         log.debug(`***Clearing heap snapshot interval...`);
-        // Clear the snapshot interval if it exists
         clearInterval(snapshotInterval);
-        // Take a final heap snapshot before stopping
         await takeHeapSnapshot();
     }
     if (!session) {
@@ -186,7 +142,6 @@ async function stopInspector() {
         return;
     }
     try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const result = await new Promise((resolve, reject) => {
             session?.post('HeapProfiler.stopSampling', (err, result) => (err ? reject(err) : resolve(result)));
         });
@@ -204,13 +159,6 @@ async function stopInspector() {
         log.debug(`***Stopped heap sampling`);
     }
 }
-/**
- * Takes a heap snapshot and saves it to the file name Heap-snapshot-<timestamp>.heapsnapshot.
- * This function is called periodically based on the -snapshotinterval parameter.
- * The -snapshotinterval parameter must at least 30000 ms.
- * The snapshot is saved in the heap_profile directory that is created in the current working directory.
- * The snapshot can be analyzed using vscode or Chrome DevTools or other tools that support heap snapshots.
- */
 async function takeHeapSnapshot() {
     const { writeFileSync } = await import('node:fs');
     const path = await import('node:path');
@@ -242,10 +190,6 @@ async function takeHeapSnapshot() {
         });
     });
 }
-/**
- * Triggers a manual garbage collection.
- * This function is working only if the process is started with --expose-gc.
- */
 function triggerGarbageCollection() {
     if (typeof global.gc === 'function') {
         global.gc();
@@ -292,7 +236,6 @@ async function restart() {
 }
 async function update() {
     log.debug('Received update event, updating...');
-    // TODO: Implement update logic outside of matterbridge
     instance = await Matterbridge.loadInstance(true);
     registerHandlers();
 }
@@ -312,7 +255,6 @@ async function main() {
     log.debug(`***Matterbridge.loadInstance(true) called`);
     instance = await Matterbridge.loadInstance(true);
     log.debug(`***Matterbridge.loadInstance(true) exited`);
-    // Check if the instance needs to shut down from parseCommandLine()
     if (!instance || instance.shutdown) {
         shutdown();
     }
@@ -321,11 +263,9 @@ async function main() {
         cliEmitter.emit('ready');
     }
 }
-// Run the main function
 process.title = 'matterbridge';
 main().catch((error) => {
     const errorMessage = error instanceof Error ? error.message : error;
     const errorInspect = inspect(error, { depth: 10 });
     log.error(`Matterbridge.loadInstance() failed with error: ${errorMessage}\nstack: ${errorInspect}`);
 });
-//# sourceMappingURL=cli.js.map

package/dist/clusters/export.js

@@ -0,0 +1 @@
+export {};

package/dist/defaultConfigSchema.js

@@ -1,25 +1,3 @@
-/**
- * This file contains the default config for the plugins.
- *
- * @file defaultConfigSchema.ts
- * @author Luca Liguori
- * @date 2024-05-07
- * @version 1.0.1
- *
- * Copyright 2024, 2025, 2026 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. *
- */
 export const zigbee2mqtt_config = {
     name: 'matterbridge-zigbee2mqtt',
     type: 'DynamicPlatform',
@@ -78,4 +56,3 @@ export const shelly_config = {
     debugWs: false,
     unregisterOnShutdown: false,
 };
-//# sourceMappingURL=defaultConfigSchema.js.map

package/dist/deviceManager.js

@@ -1,89 +1,28 @@
-/**
- * This file contains the DeviceManager class.
- *
- * @file devices.ts
- * @author Luca Liguori
- * @date 2024-07-26
- * @version 1.0.10
- *
- * Copyright 2024, 2025, 2026 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. *
- */
-// AnsiLogger module
 import { AnsiLogger, BLUE, er } from './logger/export.js';
 import { dev } from './matterbridgeTypes.js';
-/**
- * Manages Matterbridge devices.
- */
 export class DeviceManager {
     _devices = new Map();
     matterbridge;
     nodeContext;
     log;
-    /**
-     * Creates an instance of DeviceManager.
-     *
-     * @param {Matterbridge} matterbridge - The Matterbridge instance.
-     * @param {NodeStorage} nodeContext - The node storage context.
-     */
     constructor(matterbridge, nodeContext) {
         this.matterbridge = matterbridge;
         this.nodeContext = nodeContext;
-        this.log = new AnsiLogger({ logName: 'DeviceManager', logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: matterbridge.log.logLevel });
+        this.log = new AnsiLogger({ logName: 'DeviceManager', logTimestampFormat: 4, logLevel: matterbridge.log.logLevel });
         this.log.debug('Matterbridge device manager starting...');
     }
-    /**
-     * Gets the number of devices.
-     *
-     * @returns {number} The number of devices.
-     */
     get length() {
         return this._devices.size;
     }
-    /**
-     * Gets the number of devices.
-     *
-     * @returns {number} The number of devices.
-     */
     get size() {
         return this._devices.size;
     }
-    /**
-     * Checks if a device with the specified unique ID exists.
-     *
-     * @param {string} uniqueId - The unique ID of the device.
-     * @returns {boolean} True if the device exists, false otherwise.
-     */
     has(uniqueId) {
         return this._devices.has(uniqueId);
     }
-    /**
-     * Gets a device by its unique ID.
-     *
-     * @param {string} uniqueId - The unique ID of the device.
-     * @returns {MatterbridgeEndpoint | undefined} The device, or undefined if not found.
-     */
     get(uniqueId) {
         return this._devices.get(uniqueId);
     }
-    /**
-     * Adds a device to the manager.
-     *
-     * @param {MatterbridgeEndpoint} device - The device to add.
-     * @returns {MatterbridgeEndpoint} The added device.
-     * @throws {Error} If the device does not have a unique ID.
-     */
     set(device) {
         if (!device.uniqueId)
             throw new Error(`The device ${dev}${device.deviceName}${er} has not been initialized: uniqueId is required`);
@@ -92,13 +31,6 @@ export class DeviceManager {
         this._devices.set(device.uniqueId, device);
         return device;
     }
-    /**
-     * Removes a device from the manager.
-     *
-     * @param {MatterbridgeEndpoint} device - The device to remove.
-     * @returns {boolean} True if the device was removed, false otherwise.
-     * @throws {Error} If the device does not have a unique ID.
-     */
     remove(device) {
         if (!device.uniqueId)
             throw new Error(`The device ${dev}${device.deviceName}${er} has not been initialized: uniqueId is required`);
@@ -106,34 +38,15 @@ export class DeviceManager {
             this.log.error(`The device ${dev}${device.deviceName}${er} with uniqueId ${BLUE}${device.uniqueId}${er} serialNumber ${BLUE}${device.serialNumber}${er} is not registered in the device manager`);
         return this._devices.delete(device.uniqueId);
     }
-    /**
-     * Clears all devices from the manager.
-     */
     clear() {
         this._devices.clear();
     }
-    /**
-     * Gets an array of all devices.
-     *
-     * @returns {MatterbridgeEndpoint[]} An array of all devices.
-     */
     array() {
         return Array.from(this._devices.values());
     }
-    /**
-     * Iterates over all devices.
-     *
-     * @returns {IterableIterator<MatterbridgeEndpoint>} An iterator for the devices.
-     */
     [Symbol.iterator]() {
         return this._devices.values();
     }
-    /**
-     * Asynchronously iterates over each device and calls the provided callback function.
-     *
-     * @param {(device: MatterbridgeEndpoint) => Promise<void>} callback - The callback function to call with each device.
-     * @returns {Promise<void>} A promise that resolves when all callbacks have been called.
-     */
     async forEach(callback) {
         if (this.size === 0)
             return;
@@ -147,13 +60,7 @@ export class DeviceManager {
         });
         await Promise.all(tasks);
     }
-    /**
-     * Sets the log level.
-     *
-     * @param {LogLevel} logLevel - The log level to set.
-     */
     set logLevel(logLevel) {
         this.log.logLevel = logLevel;
     }
 }
-//# sourceMappingURL=deviceManager.js.map

package/dist/devices/export.js

@@ -0,0 +1,4 @@
+export * from '../roboticVacuumCleaner.js';
+export * from '../laundryWasher.js';
+export * from '../waterHeater.js';
+export * from '../evse.js';