matterbridge 3.0.7-dev-20250614-0d145a8 → 3.0.7-dev-20250616-cd7fd1c

package/CHANGELOG.md

@@ -10,13 +10,20 @@ If you like this project and find it useful, please consider giving it a star on
 
 ## [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
 
+- [template]: Added the [Matterbridge Plugin Template](https://github.com/Luligu/matterbridge-plugin-template).
+
 ### Changed
 
 - [package]: Updated dependencies.
 - [package]: Downgrade jest to 29.7.0.
 - [energy]: Added parameter for cumulativeEnergyExported to the helper. For solar power device.
+- [platform]: Removed long deprecated methods: validateEntityBlackList and validateDeviceWhiteBlackList. Use validateDevice and validateEntity.
 
 ### Fixed
 

package/README-DEV.md

@@ -14,65 +14,83 @@
 
 # Development
 
+## How to create your plugin
+
+The easiest way is to clone the [Matterbridge Plugin Template](https://github.com/Luligu/matterbridge-plugin-template) that has **Dev Container support for instant development environment** and all tools and extensions (like Node.js, npm, TypeScript, ESLint, Prettier, Jest) already loaded and configured.
+
+Then change the name (keep matterbridge- at the beginning of the name), version, description, author, homepage, repository, bugs and funding in the package.json.
+
+It is possible to add two custom properties to the package.json: **help** and **changelog** with a url that will be used in the frontend instead of the default (/blob/main/README.md and /blob/main/CHANGELOG.md).
+
+Add your plugin logic in module.ts.
+
+The Matterbridge Plugin Template has an already configured Jest test (coverage 100%) that you can expand while you add your own plugin logic.
+
+It also has a workflow configured to run on push and pull request that build, lint and test the plugin on node 18, 20, 22 and 24 with ubuntu, macOS and windows.
+
 ## Guidelines on imports/exports
 
 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.
 
-# \***\*\*\*\*\***
+### WARNING \***\*\*\*\*\***
 
 A plugin must never install or import from `@matter` or `@project-chip` directly (neither as a dependency, devDependency, nor peerDependency), 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.
 
-# \***\*\*\*\*\***
+### WARNING \***\*\*\*\*\***
 
 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,27 +100,15 @@ 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).
+If you don't use Dev Container from the Matterbridge Plugin Template, 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 (I suggest you do it), you have to clone the dev branch of matterbridge, build it locally and link it (npm run deepCleanBuild does all necessary steps).
 
-# \***\*\*\*\*\***
-
-I added some error messages when a plugin has wrong imports or configurations and the plugin will be disabled to prevent instability and crashes.
-
-## How to create your plugin
+Always keep your local instance of matterbridge up to date.
 
-The easiest way is to clone:
+### WARNING \***\*\*\*\*\***
 
-- https://github.com/Luligu/matterbridge-example-accessory-platform if you want to create an Accessory Platform Plugin.
-
-- https://github.com/Luligu/matterbridge-example-dynamic-platform if you want to create a Dynamic Platform Plugin.
-
-Then change the name (keep matterbridge- at the beginning of the name), version, description, author and funding in the package.json.
-
-It is possible to add these custom properties to the package.json: help and changelog with a url that will be used in the frontend instead of the default (/blob/main/README.md and /blob/main/CHANGELOG.md).
-
-Add your plugin logic in platform.ts.
+Some error messages are logged on start when a plugin has wrong imports or configurations and the plugin will be disabled to prevent instability and crashes.
 
 ## How to install and register a plugin for development (from github)
 
@@ -114,7 +120,7 @@ On windows:
 cd $HOME\Matterbridge
 ```
 
-On linux:
+On linux or macOS:
 
 ```
 cd ~/Matterbridge
@@ -126,6 +132,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,41 +157,71 @@ 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.
 
-The MatterbridgeDevice class has the create cluster methods already done and all command handlers needed (see plugin examples).
+After add the command handlers and subscribe to the attributes when needed.
+
+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 server node the platform belongs to is online.
 
-The method is called when the platform is commissioned.
+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.
+
+### getDevices(): MatterbridgeEndpoint[]
+
+Retrieves the devices registered with the platform.
+
+### 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.
+You can unregister a 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.
 
-## MatterbridgeDevice api
+## MatterbridgeEndpoint api
 
 Work in progress...
 

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)
@@ -22,10 +22,10 @@ The developer just focuses on the device development extending the provided clas
 
 Just pair Matterbridge once, and it will load all your registered plugins.
 
-This project aims to allow the porting of homebridge plugins to matterbridge plugins without recoding everything.
+This project aims to allow the porting of homebridge plugins to matterbridge plugins without recoding everything ([Development](README-DEV.md)).
 
-It creates a device to pair in any ecosystem like Apple Home, Google Home, Amazon Alexa, or
-any other ecosystem supporting Matter like Home Assistant.
+It creates a device to pair in any ecosystem like Apple Home, Google Home, Amazon Alexa, Home Assistant or
+any other ecosystem supporting Matter.
 
 You don't need a hub or a dedicated new machine.
 

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';

package/dist/matterbridge.js

@@ -1598,10 +1598,10 @@ export class Matterbridge extends EventEmitter {
     }
     startEndAdvertiseTimer(matterServerNode) {
         if (this.endAdvertiseTimeout) {
-            this.log.debug(`***Clear ${matterServerNode.id} server node end advertise timer`);
+            this.log.debug(`Clear ${matterServerNode.id} server node end advertise timer`);
             clearTimeout(this.endAdvertiseTimeout);
         }
-        this.log.debug(`***Starting ${matterServerNode.id} server node end advertise timer`);
+        this.log.debug(`Starting ${matterServerNode.id} server node end advertise timer`);
         this.endAdvertiseTimeout = setTimeout(() => {
             if (matterServerNode.lifecycle.isCommissioned)
                 return;

package/dist/matterbridgePlatform.js

@@ -20,7 +20,6 @@ export class MatterbridgePlatform {
     ready;
     _registeredEndpoints = new Map();
     _registeredEndpointsByName = new Map();
-    _storedDevices = new Map();
     constructor(matterbridge, log, config) {
         this.matterbridge = matterbridge;
         this.log = log;
@@ -76,7 +75,6 @@ export class MatterbridgePlatform {
         this.selectEntity.clear();
         this._registeredEndpoints.clear();
         this._registeredEndpointsByName.clear();
-        this._storedDevices.clear();
         await this.context?.close();
         this.context = undefined;
         await this.storage?.close();
@@ -90,6 +88,9 @@ export class MatterbridgePlatform {
     async onConfigChanged(config) {
         this.log.debug(`The plugin ${CYAN}${config.name}${db} doesn't override onConfigChanged. Received new config.`);
     }
+    getDevices() {
+        return Array.from(this._registeredEndpoints.values());
+    }
     hasDeviceName(deviceName) {
         return this._registeredEndpointsByName.has(deviceName);
     }
@@ -207,9 +208,6 @@ export class MatterbridgePlatform {
             return false;
         return true;
     }
-    validateDeviceWhiteBlackList(device, log = true) {
-        return this.validateDevice(device, log);
-    }
     validateDevice(device, log = true) {
         if (!Array.isArray(device))
             device = [device];
@@ -239,9 +237,6 @@ export class MatterbridgePlatform {
             this.log.info(`Skipping device ${CYAN}${device.join(', ')}${nf} because not in whitelist`);
         return false;
     }
-    validateEntityBlackList(device, entity, log = true) {
-        return this.validateEntity(device, entity, log);
-    }
     validateEntity(device, entity, log = true) {
         if (isValidArray(this.config.entityBlackList, 1) && this.config.entityBlackList.find((e) => e === entity)) {
             if (log)

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "matterbridge",
-  "version": "3.0.7-dev-20250614-0d145a8",
+  "version": "3.0.7-dev-20250616-cd7fd1c",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "matterbridge",
-      "version": "3.0.7-dev-20250614-0d145a8",
+      "version": "3.0.7-dev-20250616-cd7fd1c",
       "license": "Apache-2.0",
       "dependencies": {
         "@matter/main": "0.14.0",
@@ -22,7 +22,7 @@
         "matterbridge": "dist/cli.js"
       },
       "engines": {
-        "node": ">=18.0.0 <19.0.0 || >=20.0.0 <21.0.0 || >=22.0.0"
+        "node": ">=18.0.0 <19.0.0 || >=20.0.0 <21.0.0 || >=22.0.0 <23.0.0 || >=24.0.0 <25.0.0"
       },
       "funding": {
         "type": "buymeacoffee",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matterbridge",
-  "version": "3.0.7-dev-20250614-0d145a8",
+  "version": "3.0.7-dev-20250616-cd7fd1c",
   "description": "Matterbridge plugin manager for Matter",
   "author": "https://github.com/Luligu",
   "license": "Apache-2.0",
@@ -45,13 +45,33 @@
     "matterbridge": "dist/cli.js"
   },
   "engines": {
-    "node": ">=18.0.0 <19.0.0 || >=20.0.0 <21.0.0 || >=22.0.0"
+    "node": ">=18.0.0 <19.0.0 || >=20.0.0 <21.0.0 || >=22.0.0 <23.0.0 || >=24.0.0 <25.0.0"
   },
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
+    "./devices": {
+      "import": "./dist/devices/export.js",
+      "types": "./dist/devices/export.d.ts"
+    },
+    "./clusters": {
+      "import": "./dist/clusters/export.js",
+      "types": "./dist/clusters/export.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils/export.js",
+      "types": "./dist/utils/export.d.ts"
+    },
+    "./logger": {
+      "import": "./dist/logger/export.js",
+      "types": "./dist/logger/export.d.ts"
+    },
+    "./storage": {
+      "import": "./dist/storage/export.js",
+      "types": "./dist/storage/export.d.ts"
+    },
     "./matter": {
       "import": "./dist/matter/export.js",
       "types": "./dist/matter/export.d.ts"
@@ -75,22 +95,6 @@
     "./matter/types": {
       "import": "./dist/matter/types.js",
       "types": "./dist/matter/types.d.ts"
-    },
-    "./cluster": {
-      "import": "./dist/cluster/export.js",
-      "types": "./dist/cluster/export.d.ts"
-    },
-    "./utils": {
-      "import": "./dist/utils/export.js",
-      "types": "./dist/utils/export.d.ts"
-    },
-    "./logger": {
-      "import": "./dist/logger/export.js",
-      "types": "./dist/logger/export.d.ts"
-    },
-    "./storage": {
-      "import": "./dist/storage/export.js",
-      "types": "./dist/storage/export.d.ts"
     }
   },
   "dependencies": {