matterbridge 3.2.3-dev-20250813-34745fd → 3.2.3-dev-20250816-3639b16

package/CHANGELOG.md

@@ -12,9 +12,12 @@ If you like this project and find it useful, please consider giving it a star on
 
 ### Added
 
-- [Oven]: Added Oven class and Jest test. It is not supported by the Home app.
-- [MicrowaveOven]: Added MicrowaveOven class and Jest test. It is not supported by the Home app.
-- [Matter]: Added Matter Specification Version 1.4 pdf files.
+- [Oven]: Added Oven() class and Jest test. It is not supported by the Home app.
+- [MicrowaveOven]: Added MicrowaveOven() class and Jest test. It is not supported by the Home app.
+- [Cooktop]: Added Cooktop() class and Jest test. It is not supported by the Home app.
+- [Refrigerator]: Added Refrigerator() class and Jest test. It is not supported by the Home app.
+- [Pages]: Added first draft of https://luligu.github.io/matterbridge.
+- [Matter]: Added Matter Specification Version 1.0, 1.1, 1.2, 1.3, 1.4 and 1.4.1 pdf files.
 
 ### Changed
 

package/README-DEV.md

@@ -357,6 +357,57 @@ The schema file is loaded from the root of the plugin package. The file must be
 
 The properties of the schema file shall correspond to the properties of the config file.
 
+# Frequently asked questions
+
+## Why plugins cannot install matterbridge as a dependency, devDependency or peerDependency
+
+There must be one and only one instance of Matterbridge and matter.js in the node_modules directory.
+
+### What happens when matterbridge or matter.js are present like a devDependencies
+
+The plugins can be globally installed in different ways:
+
+- from npm (all devDependencies are installed in node_modules if the plugin is not correctly published)
+- from a tarball (all devDependencies are installed in node_modules if the tarball is not correctly built)
+- from a local path (devDependencies are always installed in node_modules!)
+
+In all these cases the devDependencies are always installed by npm and show up in the plugins `node_modules`:
+
+- npm install -g ./yourplugin
+- npm install -g git+https://github.com/you/yourplugin.git
+- npm install -g yourplugin
+
+In the first 2 cases the devDependeincies are always installed in node_modules!
+
+In the last (most dangerous case) they are installed when the user forgets to add --omit=dev or doesn't have NODE_ENV=production.
+
+This is also the reason why to be safe 100% all official plugins are published for production removing also devDependencies from package.json.
+
+I also lock the dependencies with npm shrinkwrap cause npm installs always the latest versions that mach your range in package.json but sometimes this just breaks the plugin. This permits to be sure that the user host machine has exactly the same dependencies you coded your plugin with.
+
+### The technical reason we cannot have matterbridge or @matter in the plugin node_modules.
+
+Module Resolution in Matterbridge Plugin System.
+When Matterbridge loads plugins on demand as ESM modules, the module resolution follows Node.js's standard module resolution algorithm. Here's how it works:
+
+**1. Plugin Loading Process**
+From the code in pluginManager.ts (lines 628-632), Matterbridge:
+
+Resolves the plugin's main entry point from its package.json
+Converts the file path to a URL using pathToFileURL()
+Uses dynamic import: await import(pluginUrl.href)
+
+**2. Module Resolution Priority**
+When the plugin code runs import statements, Node.js follows this resolution order:
+
+Plugin's local node_modules - Checked first
+Parent directories - Walks up the directory tree looking for node_modules
+Matterbridge's node_modules - Only reached if not found in plugin's dependencies
+
+**3. Key Behavior**
+Plugin's node_modules takes precedence - If a package exists in the plugin's own node_modules, that version will be used.
+Matterbridge's node_modules is used as fallback.
+
 # Contribution Guidelines
 
 Thank you for your interest in contributing to my project!

package/dist/devices/cooktop.js

@@ -0,0 +1,21 @@
+import { cookSurface, cooktop, powerSource } from '../matterbridgeDeviceTypes.js';
+import { MatterbridgeEndpoint } from '../matterbridgeEndpoint.js';
+import { createLevelTemperatureControlClusterServer } from './temperatureControl.js';
+export class Cooktop extends MatterbridgeEndpoint {
+    constructor(name, serial) {
+        super([cooktop, powerSource], { uniqueStorageKey: `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}` }, true);
+        this.createDefaultIdentifyClusterServer();
+        this.createDefaultBasicInformationClusterServer(name, serial, 0xfff1, 'Matterbridge', 0x8000, 'Cooktop');
+        this.createDefaultPowerSourceWiredClusterServer();
+        this.createOffOnlyOnOffClusterServer(true);
+        this.addFixedLabel('composed', 'Cooktop');
+    }
+    addSurface(name, tagList, selectedTemperatureLevel = 2, supportedTemperatureLevels = ['Level 1', 'Level 2', 'Level 3', 'Level 4', 'Level 5']) {
+        const surface = this.addChildDeviceType(name, cookSurface, { tagList }, true);
+        surface.log.logName = name;
+        createLevelTemperatureControlClusterServer(surface, selectedTemperatureLevel, supportedTemperatureLevels);
+        surface.createDefaultTemperatureMeasurementClusterServer(2000);
+        surface.createOffOnlyOnOffClusterServer(true);
+        return surface;
+    }
+}

package/dist/devices/dishwasher.js

@@ -1,4 +1,3 @@
-import { TemperatureControl } from '@matter/main/clusters/temperature-control';
 import { ModeBase } from '@matter/main/clusters/mode-base';
 import { DishwasherModeServer } from '@matter/main/behaviors/dishwasher-mode';
 import { DishwasherAlarmServer } from '@matter/main/behaviors/dishwasher-alarm';
@@ -6,7 +5,7 @@ import { DishwasherMode } from '@matter/main/clusters/dishwasher-mode';
 import { dishwasher, powerSource } from '../matterbridgeDeviceTypes.js';
 import { MatterbridgeEndpoint } from '../matterbridgeEndpoint.js';
 import { MatterbridgeOnOffServer, MatterbridgeServer } from '../matterbridgeBehaviors.js';
-import { MatterbridgeLevelTemperatureControlServer, MatterbridgeNumberTemperatureControlServer } from './temperatureControl.js';
+import { createLevelTemperatureControlClusterServer, createNumberTemperatureControlClusterServer } from './temperatureControl.js';
 export class Dishwasher extends MatterbridgeEndpoint {
     constructor(name, serial, currentMode, supportedModes, selectedTemperatureLevel, supportedTemperatureLevels, temperatureSetpoint, minTemperature, maxTemperature, step, operationalState) {
         super([dishwasher, powerSource], { uniqueStorageKey: `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}` }, true);
@@ -17,27 +16,11 @@ export class Dishwasher extends MatterbridgeEndpoint {
         this.createDefaultDishwasherModeClusterServer(currentMode, supportedModes);
         this.createDefaultDishwasherAlarmClusterServer();
         if (temperatureSetpoint)
-            this.createNumberTemperatureControlClusterServer(temperatureSetpoint, minTemperature, maxTemperature, step);
+            createNumberTemperatureControlClusterServer(this, temperatureSetpoint, minTemperature, maxTemperature, step);
         else
-            this.createLevelTemperatureControlClusterServer(selectedTemperatureLevel, supportedTemperatureLevels);
+            createLevelTemperatureControlClusterServer(this, selectedTemperatureLevel, supportedTemperatureLevels);
         this.createDefaultOperationalStateClusterServer(operationalState);
     }
-    createLevelTemperatureControlClusterServer(selectedTemperatureLevel = 1, supportedTemperatureLevels = ['Cold', 'Warm', 'Hot', '30°', '40°', '60°', '80°']) {
-        this.behaviors.require(MatterbridgeLevelTemperatureControlServer.with(TemperatureControl.Feature.TemperatureLevel), {
-            selectedTemperatureLevel,
-            supportedTemperatureLevels,
-        });
-        return this;
-    }
-    createNumberTemperatureControlClusterServer(temperatureSetpoint = 40 * 100, minTemperature = 30 * 100, maxTemperature = 60 * 100, step = 10 * 100) {
-        this.behaviors.require(MatterbridgeNumberTemperatureControlServer.with(TemperatureControl.Feature.TemperatureNumber, TemperatureControl.Feature.TemperatureStep), {
-            temperatureSetpoint,
-            minTemperature,
-            maxTemperature,
-            step,
-        });
-        return this;
-    }
     createDefaultDishwasherModeClusterServer(currentMode = 2, supportedModes = [
         { label: 'Light', mode: 1, modeTags: [{ value: DishwasherMode.ModeTag.Light }] },
         { label: 'Normal', mode: 2, modeTags: [{ value: DishwasherMode.ModeTag.Normal }] },

package/dist/devices/export.js

@@ -4,6 +4,8 @@ export * from './extractorHood.js';
 export * from './dishwasher.js';
 export * from './microwaveOven.js';
 export * from './oven.js';
+export * from './cooktop.js';
+export * from './refrigerator.js';
 export * from './waterHeater.js';
 export * from './evse.js';
 export * from './solarPower.js';

package/dist/devices/laundryDryer.js

@@ -1,11 +1,10 @@
 import { LaundryWasherMode } from '@matter/main/clusters/laundry-washer-mode';
-import { TemperatureControl } from '@matter/main/clusters/temperature-control';
 import { LaundryDryerControls } from '@matter/main/clusters/laundry-dryer-controls';
 import { LaundryDryerControlsServer } from '@matter/main/behaviors/laundry-dryer-controls';
 import { laundryDryer, powerSource } from '../matterbridgeDeviceTypes.js';
 import { MatterbridgeEndpoint } from '../matterbridgeEndpoint.js';
 import { MatterbridgeLaundryWasherModeServer } from './laundryWasher.js';
-import { MatterbridgeLevelTemperatureControlServer, MatterbridgeNumberTemperatureControlServer } from './temperatureControl.js';
+import { createLevelTemperatureControlClusterServer, createNumberTemperatureControlClusterServer } from './temperatureControl.js';
 export class LaundryDryer extends MatterbridgeEndpoint {
     constructor(name, serial, currentMode, supportedModes, selectedTemperatureLevel, supportedTemperatureLevels, temperatureSetpoint, minTemperature, maxTemperature, step, operationalState) {
         super([laundryDryer, powerSource], { uniqueStorageKey: `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}` }, true);
@@ -16,9 +15,9 @@ export class LaundryDryer extends MatterbridgeEndpoint {
         this.createDefaultLaundryWasherModeClusterServer(currentMode, supportedModes);
         this.createDefaultLaundryDryerControlsClusterServer(1);
         if (temperatureSetpoint)
-            this.createNumberTemperatureControlClusterServer(temperatureSetpoint, minTemperature, maxTemperature, step);
+            createNumberTemperatureControlClusterServer(this, temperatureSetpoint, minTemperature, maxTemperature, step);
         else
-            this.createLevelTemperatureControlClusterServer(selectedTemperatureLevel, supportedTemperatureLevels);
+            createLevelTemperatureControlClusterServer(this, selectedTemperatureLevel, supportedTemperatureLevels);
         this.createDefaultOperationalStateClusterServer(operationalState);
     }
     createDefaultLaundryWasherModeClusterServer(currentMode = 2, supportedModes = [
@@ -40,20 +39,4 @@ export class LaundryDryer extends MatterbridgeEndpoint {
         });
         return this;
     }
-    createLevelTemperatureControlClusterServer(selectedTemperatureLevel = 1, supportedTemperatureLevels = ['Cold', 'Warm', 'Hot', '30°', '40°', '60°', '80°']) {
-        this.behaviors.require(MatterbridgeLevelTemperatureControlServer.with(TemperatureControl.Feature.TemperatureLevel), {
-            selectedTemperatureLevel,
-            supportedTemperatureLevels,
-        });
-        return this;
-    }
-    createNumberTemperatureControlClusterServer(temperatureSetpoint = 40 * 100, minTemperature = 30 * 100, maxTemperature = 60 * 100, step = 10 * 100) {
-        this.behaviors.require(MatterbridgeNumberTemperatureControlServer.with(TemperatureControl.Feature.TemperatureNumber, TemperatureControl.Feature.TemperatureStep), {
-            temperatureSetpoint,
-            minTemperature,
-            maxTemperature,
-            step,
-        });
-        return this;
-    }
 }

package/dist/devices/oven.js

@@ -13,6 +13,7 @@ export class Oven extends MatterbridgeEndpoint {
         this.createDefaultIdentifyClusterServer();
         this.createDefaultBasicInformationClusterServer(name, serial, 0xfff1, 'Matterbridge', 0x8000, 'Oven');
         this.createDefaultPowerSourceWiredClusterServer();
+        this.addFixedLabel('composed', 'Oven');
     }
     addCabinet(name, tagList, currentMode = 2, supportedModes = [
         { label: 'Bake', mode: 1, modeTags: [{ value: OvenMode.ModeTag.Bake }] },

package/dist/devices/refrigerator.js

@@ -0,0 +1,55 @@
+import { ModeBase } from '@matter/main/clusters/mode-base';
+import { RefrigeratorAndTemperatureControlledCabinetModeServer } from '@matter/main/behaviors/refrigerator-and-temperature-controlled-cabinet-mode';
+import { RefrigeratorAndTemperatureControlledCabinetMode } from '@matter/main/clusters/refrigerator-and-temperature-controlled-cabinet-mode';
+import { oven, powerSource, temperatureControlledCabinetCooler } from '../matterbridgeDeviceTypes.js';
+import { MatterbridgeEndpoint } from '../matterbridgeEndpoint.js';
+import { MatterbridgeServer } from '../matterbridgeBehaviors.js';
+import { createLevelTemperatureControlClusterServer } from './temperatureControl.js';
+export class Refrigerator extends MatterbridgeEndpoint {
+    constructor(name, serial) {
+        super([oven, powerSource], { uniqueStorageKey: `${name.replaceAll(' ', '')}-${serial.replaceAll(' ', '')}` }, true);
+        this.createDefaultIdentifyClusterServer();
+        this.createDefaultBasicInformationClusterServer(name, serial, 0xfff1, 'Matterbridge', 0x8000, 'Refrigerator');
+        this.createDefaultPowerSourceWiredClusterServer();
+        this.addFixedLabel('composed', 'Refrigerator');
+    }
+    addCabinet(name, tagList, currentMode = 1, supportedModes = [
+        { label: 'Auto', mode: 1, modeTags: [{ value: RefrigeratorAndTemperatureControlledCabinetMode.ModeTag.Auto }] },
+        { label: 'RapidCool', mode: 2, modeTags: [{ value: RefrigeratorAndTemperatureControlledCabinetMode.ModeTag.RapidCool }] },
+        { label: 'RapidFreeze', mode: 3, modeTags: [{ value: RefrigeratorAndTemperatureControlledCabinetMode.ModeTag.RapidFreeze }] },
+    ], selectedTemperatureLevel = 2, supportedTemperatureLevels = ['Level 1', 'Level 2', 'Level 3', 'Level 4', 'Level 5'], currentTemperature = 1000) {
+        const cabinet = this.addChildDeviceType(name, temperatureControlledCabinetCooler, { tagList }, true);
+        cabinet.log.logName = name;
+        cabinet.createDefaultIdentifyClusterServer();
+        createLevelTemperatureControlClusterServer(cabinet, selectedTemperatureLevel, supportedTemperatureLevels);
+        this.createDefaultRefrigeratorAndTemperatureControlledCabinetModeClusterServer(cabinet, currentMode, supportedModes);
+        cabinet.createDefaultTemperatureMeasurementClusterServer(currentTemperature);
+        return cabinet;
+    }
+    createDefaultRefrigeratorAndTemperatureControlledCabinetModeClusterServer(endpoint, currentMode, supportedModes) {
+        endpoint.behaviors.require(MatterbridgeRefrigeratorAndTemperatureControlledCabinetModeServer, {
+            supportedModes,
+            currentMode,
+        });
+        return endpoint;
+    }
+}
+export class MatterbridgeRefrigeratorAndTemperatureControlledCabinetModeServer extends RefrigeratorAndTemperatureControlledCabinetModeServer {
+    initialize() {
+        const device = this.endpoint.stateOf(MatterbridgeServer);
+        device.log.info('MatterbridgeRefrigeratorAndTemperatureControlledCabinetModeServer initialized');
+    }
+    changeToMode(request) {
+        const device = this.endpoint.stateOf(MatterbridgeServer);
+        const supportedMode = this.state.supportedModes.find((supportedMode) => supportedMode.mode === request.newMode);
+        if (supportedMode) {
+            device.log.info(`MatterbridgeRefrigeratorAndTemperatureControlledCabinetModeServer: changeToMode (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber}) called with mode ${supportedMode.mode} = ${supportedMode.label}`);
+            this.state.currentMode = request.newMode;
+            return { status: ModeBase.ModeChangeStatus.Success, statusText: 'Success' };
+        }
+        else {
+            device.log.error(`MatterbridgeRefrigeratorAndTemperatureControlledCabinetModeServer: changeToMode (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber}) called with invalid mode ${request.newMode}`);
+            return { status: ModeBase.ModeChangeStatus.InvalidInMode, statusText: 'Invalid mode' };
+        }
+    }
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "matterbridge",
-  "version": "3.2.3-dev-20250813-34745fd",
+  "version": "3.2.3-dev-20250816-3639b16",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "matterbridge",
-      "version": "3.2.3-dev-20250813-34745fd",
+      "version": "3.2.3-dev-20250816-3639b16",
       "license": "Apache-2.0",
       "dependencies": {
         "@matter/main": "0.15.3",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matterbridge",
-  "version": "3.2.3-dev-20250813-34745fd",
+  "version": "3.2.3-dev-20250816-3639b16",
   "description": "Matterbridge plugin manager for Matter",
   "author": "https://github.com/Luligu",
   "license": "Apache-2.0",