matterbridge 3.4.4 → 3.4.5-dev-20251223-f84f73d

package/CHANGELOG.md

@@ -28,6 +28,21 @@ Advantages:
 - individual plugin isolation in childbridge mode;
 - ability to update the plugin in childbridge mode without restarting matterbridge;
 
+## [3.4.5] - Dev branch
+
+### Added
+
+- [DevContainer]: Refactored Dev Container setup. The Matterbridge instance can now be paired on native Linux hosts or WSL 2 with Docker engine CLI integration. On Docker Desktop on Windows or macOS is not possible cause Docker Desktop runs inside a VM and not directly on the host so mDNS is not supported.
+- [DevContainer]: Since is now possible to pair from Dev Container, named volumes have been added to persist storage and plugins across rebuilds.
+
+### Changed
+
+- [package]: Updated dependencies.
+
+### Fixed
+
+<a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/bmc-button.svg" alt="Buy me a coffee" width="80"></a>
+
 ## [3.4.4] - 2025-12-19
 
 ### Added

package/README-DEV.md

@@ -52,12 +52,32 @@ To start the Dev Container, simply open the project folder in [Visual Studio Cod
 
 > **Note:** The first time you use the Dev Container, it may take a while to download all the required Docker images and set up the environment. Subsequent starts will be as fast as from the local folder.
 
-Since Dev Container doesn't run in network mode 'host', it is not possible to pair Mattebridge running inside the Dev Container.
+## Dev containers networking limitations
+
+Dev containers have networking limitations depending on the host OS and Docker setup.
+
+• Docker Desktop on Windows or macOS:
+
+- Runs inside a VM
+- Host networking mode is NOT available
+- Matterbridge and plugins can run but:
+  ❌ Pairing with Matter controllers will NOT work cause of missing mDNS support
+  ✅ Remote and local network access (cloud services, internet APIs) works normally
+  ✅ Matterbridge frontend works normally
+
+• Native Linux or WSL 2 with Docker Engine CLI integration:
+
+- Host networking IS available
+- Full local network access is supported with mDNS
+- Matterbridge and plugins work correctly, including pairing
+- Matterbridge frontend works normally
+
+## How to pair the plugin
 
-When you want to test your plugin with a paired controller, you have several options:
+When you want to test your plugin with a paired controller and you cannot use native Linux or WSL 2 with Docker Engine, you have several other 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.
+- publish the plugin 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

package/README.md

@@ -533,6 +533,17 @@ Examples:
 /error|warning/   -> match either "error" OR "warning" (double search)
 ```
 
+## Window Covering cluster and position explained
+
+In Matter spec the Window Covering cluster uses:
+
+- 10000 = fully closed
+- 0 = fully opened
+
+So depending on the controller you pair with, you should see 100 for fully closed and 0 for fully open.
+
+Some controllers invert the position so you need to verify your controller.
+
 # Known general issues
 
 ## Session XYZ does not exist or Cannot find a session for ID XYZ
@@ -577,11 +588,15 @@ So far is the only controller supporting all Matter 1.2, 1.3 and 1.4 device type
 
 ## Google Home
 
-If you face a problem pairing to Google Home from Ios app the solution is there https://github.com/Luligu/matterbridge/issues/61.
+If you face a problem pairing to Google Home from iOS app the solution is there https://github.com/Luligu/matterbridge/issues/61.
 
 If you face a problem changing the brightness check this for the explanation: https://github.com/Luligu/matterbridge-zigbee2mqtt/issues/80
 
-No other issues reported so far.
+If you encounter a “Something Went Wrong” screen while commissioning MatterBridge devices in Google Home on Android, it’s due to an Android bug. Android fails to send the country code, which is mandatory under the Matter specification.
+
+### Workaround
+
+Install Google Home on an iPhone and complete the commissioning there. Once set up, the devices will appear and function normally on your Android phone and other Nest devices in your home. By [Artem Kovalov](https://github.com/artemkovalyov).
 
 ## Alexa
 

package/dist/broadcastServer.js

@@ -1,27 +1,3 @@
-/**
- * This file contains the BroadcastServer class.
- *
- * @file broadcastServer.ts
- * @author Luca Liguori
- * @created 2025-10-05
- * @version 2.0.1
- * @license Apache-2.0
- *
- * 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.
- */
-// eslint-disable-next-line no-console
 if (process.argv.includes('--loader') || process.argv.includes('-loader'))
     console.log('\u001B[32mBroadcastServer loaded.\u001B[40;0m');
 import { EventEmitter } from 'node:events';
@@ -29,9 +5,6 @@ import { BroadcastChannel } from 'node:worker_threads';
 import { CYAN, db, debugStringify, er } from 'node-ansi-logger';
 import { hasParameter } from './utils/commandLine.js';
 import { logError } from './utils/error.js';
-/**
- * BroadcastServer class to handle broadcast messages between workers with BroadcastChannel.
- */
 export class BroadcastServer extends EventEmitter {
     name;
     log;
@@ -40,40 +13,21 @@ export class BroadcastServer extends EventEmitter {
     closed = false;
     debug = hasParameter('debug') || hasParameter('verbose');
     verbose = hasParameter('verbose');
-    /**
-     * Creates an instance of BroadcastServer.
-     *
-     * @param {string} name - The name of the broadcast server.
-     * @param {AnsiLogger} log - The logger instance to use for logging.
-     * @param {string} channel - The channel name for the broadcast. Default is 'broadcast-channel'.
-     */
     constructor(name, log, channel = 'broadcast-channel') {
         super();
         this.name = name;
         this.log = log;
         this.channel = channel;
         this.broadcastChannel = new BroadcastChannel(this.channel);
-        // this.broadcastChannel.unref();
         this.broadcastChannel.onmessage = this.broadcastMessageHandler.bind(this);
         this.broadcastChannel.onmessageerror = this.broadcastMessageErrorHandler.bind(this);
     }
-    /**
-     * Closes the broadcast channel.
-     *
-     * @returns {void}
-     */
     close() {
         this.broadcastChannel.onmessage = null;
         this.broadcastChannel.onmessageerror = null;
         this.broadcastChannel.close();
         this.closed = true;
     }
-    /**
-     * Handles incoming broadcast messages.
-     *
-     * @param {MessageEvent} event - The message event containing the broadcast message.
-     * @returns {void}
-     */
     broadcastMessageHandler(event) {
         const msg = event.data;
         if (msg.dst === this.name || msg.dst === 'all') {
@@ -86,30 +40,13 @@ export class BroadcastServer extends EventEmitter {
                 this.log.debug(`Server ${CYAN}${this.name}${db} received unrelated broadcast message: ${debugStringify(msg)}`);
         }
     }
-    /**
-     * Handles incoming broadcast error messages.
-     *
-     * @param {MessageEvent} event - The message event containing the broadcast message.
-     * @returns {void}
-     */
     broadcastMessageErrorHandler(event) {
         const msg = event.data;
         this.log.error(`Server ${CYAN}${this.name}${db} received message error: ${debugStringify(msg)}`);
     }
-    /**
-     * Generate a pseudo-random identifier between 100,000,000 and 999,999,999.
-     *
-     * @returns {number} A nine-digit identifier.
-     */
     getUniqueId() {
         return Math.floor(Math.random() * 900000000) + 100000000;
     }
-    /**
-     * Type guard to verify a value matches the WorkerMessageRequest structure.
-     *
-     * @param {unknown} value Value to test.
-     * @returns {value is WorkerMessageRequest} True when the value looks like a request message.
-     */
     isWorkerRequest(value) {
         if (typeof value !== 'object' || value === null) {
             return false;
@@ -120,22 +57,9 @@ export class BroadcastServer extends EventEmitter {
         }
         return message.result === undefined && message.error === undefined;
     }
-    /**
-     * Type guard to verify a value matches a specific WorkerMessageRequest structure.
-     *
-     * @param {unknown} value Value to test.
-     * @param {K} type Worker message type to match.
-     * @returns {value is WorkerMessageRequest<K>} True when the value looks like a request message of the requested type.
-     */
     isWorkerRequestOfType(value, type) {
         return this.isWorkerRequest(value) && value.type === type;
     }
-    /**
-     * Type guard to verify a value matches the WorkerMessageResponse structure.
-     *
-     * @param {unknown} value Value to test.
-     * @returns {value is WorkerMessageResponse} True when the value looks like a response message.
-     */
     isWorkerResponse(value) {
         if (typeof value !== 'object' || value === null) {
             return false;
@@ -148,24 +72,9 @@ export class BroadcastServer extends EventEmitter {
         const hasResult = message.result !== undefined;
         return hasError !== hasResult;
     }
-    /**
-     * Type guard to verify a value matches a specific WorkerMessageResponse structure.
-     *
-     * @param {unknown} value Value to test.
-     * @param {K} type Worker message type to match.
-     * @returns {value is WorkerMessageResponse<K>} True when the value looks like a response message of the requested type.
-     */
     isWorkerResponseOfType(value, type) {
         return this.isWorkerResponse(value) && value.type === type;
     }
-    /**
-     * Broadcast a message to all workers.
-     *
-     * @param {WorkerMessage} message - The message to broadcast.
-     * @returns {void}
-     *
-     * @remarks No checks are performed on the message structure.
-     */
     broadcast(message) {
         if (this.closed) {
             this.log.error('Broadcast channel is closed');
@@ -187,13 +96,6 @@ export class BroadcastServer extends EventEmitter {
             logError(this.log, `Failed to broadcast message ${debugStringify(message)}${er}`, error);
         }
     }
-    /**
-     * Send a request message from the worker implementation.
-     *
-     * @template K
-     * @param {WorkerMessageRequest<K>} message The request message to send.
-     * @returns {void}
-     */
     request(message) {
         if (this.closed) {
             this.log.error('Broadcast channel is closed');
@@ -219,14 +121,6 @@ export class BroadcastServer extends EventEmitter {
             logError(this.log, `Failed to broadcast request message ${debugStringify(message)}${er}`, error);
         }
     }
-    /**
-     * Send a response message from the worker implementation.
-     * It also calculates the elapsed time since the request was sent and swaps the source and destination fields.
-     *
-     * @template K
-     * @param {WorkerMessageResponse<K>} message The response message to send.
-     * @returns {void}
-     */
     respond(message) {
         if (this.closed) {
             this.log.error('Broadcast channel is closed');
@@ -255,16 +149,6 @@ export class BroadcastServer extends EventEmitter {
             logError(this.log, `Failed to broadcast response message ${debugStringify(message)}${er}`, error);
         }
     }
-    /**
-     * Fetch data from a worker.
-     * It broadcasts a request message and waits for a valid response with the same id.
-     *
-     * @template K
-     * @param {WorkerMessageRequest<K>} message - The typed request message to fetch.
-     * @param {number} timeout - The timeout in milliseconds to wait for a response. Default is 250ms.
-     * @returns {Promise<WorkerMessageResponseSuccess<K>>} A promise that resolves with the successful response from the worker or rejects on timeout.
-     * @throws {Error} If the fetch operation times out after 250ms or if an error response is received or if the response is malformed.
-     */
     async fetch(message, timeout = 250) {
         if (this.closed) {
             return Promise.reject(new Error('Broadcast channel is closed'));
@@ -305,4 +189,3 @@ export class BroadcastServer extends EventEmitter {
         });
     }
 }
-//# sourceMappingURL=broadcastServer.js.map

package/dist/broadcastServerTypes.js

@@ -1,25 +1 @@
-/**
- * This file contains the BroadcastServer types.
- *
- * @file broadcastServerTypes.ts
- * @author Luca Liguori
- * @created 2025-10-05
- * @version 2.0.0
- * @license Apache-2.0
- *
- * Copyright 2025, 2026, 2027 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 {};
-//# sourceMappingURL=broadcastServerTypes.js.map

package/dist/cli.js

@@ -1,33 +1,6 @@
-/**
- * This file contains the CLI entry point of Matterbridge.
- *
- * @file cli.ts
- * @author Luca Liguori
- * @created 2023-12-29
- * @version 3.0.0
- * @license Apache-2.0
- *
- * 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.
- */
-/* eslint-disable no-console */
-/* eslint-disable n/no-process-exit */
 if (process.argv.includes('--loader') || process.argv.includes('-loader'))
     console.log('\u001B[32mCli loaded.\u001B[40;0m');
-// AnsiLogger module
 import { AnsiLogger } from 'node-ansi-logger';
-// Cli
 import { cliEmitter } from './cliEmitter.js';
 import { hasParameter, hasAnyParameter } from './utils/commandLine.js';
 import { inspectError } from './utils/error.js';
@@ -37,10 +10,7 @@ import { formatBytes, formatUptime } from './utils/format.js';
 export let instance;
 export const tracker = new Tracker('Cli', false, false);
 export const inspector = new Inspector('Cli', false, false);
-const log = new AnsiLogger({ logName: 'Cli', logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: hasParameter('debug') ? "debug" /* LogLevel.DEBUG */ : "info" /* LogLevel.INFO */ });
-/**
- * Starts the CPU and memory tracker.
- */
+const log = new AnsiLogger({ logName: 'Cli', logTimestampFormat: 4, logLevel: hasParameter('debug') ? "debug" : "info" });
 function startCpuMemoryCheck() {
     log.debug(`Cpu memory check starting...`);
     tracker.start();
@@ -53,50 +23,26 @@ function startCpuMemoryCheck() {
     });
     log.debug(`Cpu memory check started`);
 }
-/**
- * Stops the CPU and memory tracker.
- */
 function stopCpuMemoryCheck() {
     log.debug(`Cpu memory check stopping...`);
     tracker.stop();
     tracker.removeAllListeners();
     log.debug(`Cpu memory check stopped`);
 }
-/**
- * Starts the inspector for heap sampling.
- * This function is called when the -inspect parameter is passed.
- */
 async function startInspector() {
     await inspector.start();
 }
-/**
- * Stops the heap sampling and saves the profile.
- * This function is called when the -inspect parameter is passed.
- */
 async function stopInspector() {
     await inspector.stop();
 }
-/**
- * Takes a heap snapshot
- */
 async function takeHeapSnapshot() {
     await inspector.takeHeapSnapshot();
 }
-/**
- * Triggers a manual garbage collection.
- * This function is working only if the node process is started with --expose_gc.
- *
- * @remarks To check the effect of the garbage collection, add also --trace_gc or --trace_gc_verbose.
- */
 function triggerGarbageCollection() {
     inspector.runGarbageCollector();
 }
-/**
- * Registers event handlers for the Matterbridge instance.
- */
 function registerHandlers() {
     log.debug('Registering event handlers...');
-    // istanbul ignore next cause registerHandlers is called only if instance is defined
     if (!instance)
         return;
     instance.on('shutdown', () => shutdown());
@@ -110,9 +56,6 @@ function registerHandlers() {
     instance.on('triggergarbagecollection', () => triggerGarbageCollection());
     log.debug('Registered event handlers');
 }
-/**
- * Shuts down the Matterbridge instance and exits the process.
- */
 async function shutdown() {
     log.debug('Received shutdown event, exiting...');
     if (hasParameter('inspect'))
@@ -121,56 +64,26 @@ async function shutdown() {
     cliEmitter.emit('shutdown');
     process.exit(0);
 }
-/**
- * Restarts the Matterbridge instance.
- */
 async function restart() {
     log.debug('Received restart event, loading...');
     const { Matterbridge } = await import('./matterbridge.js');
     instance = await Matterbridge.loadInstance(true);
     registerHandlers();
 }
-/**
- * Updates the Matterbridge instance.
- */
 async function update() {
     log.debug('Received update event, updating...');
-    // TODO: Implement update logic outside of matterbridge
     const { Matterbridge } = await import('./matterbridge.js');
     instance = await Matterbridge.loadInstance(true);
     registerHandlers();
 }
-/**
- * Starts the CPU and memory check when the -startmemorycheck parameter is passed.
- */
 function start() {
     log.debug('Received start memory check event');
     startCpuMemoryCheck();
 }
-/**
- * Stops the CPU and memory check when the -stopmemorycheck parameter is passed.
- */
 function stop() {
     log.debug('Received stop memory check event');
     stopCpuMemoryCheck();
 }
-/**
- * Main function that initializes the Matterbridge instance and starts the CLI.
- *
- * @remarks
- *
- * Debug parameters:
- *
- * --debug enables debug logging.
- *
- * --verbose enables verbose logging.
- *
- * --loader enables loader logging.
- *
- * --inspect enables the inspector for heap sampling.
- *
- * --snapshotinterval <milliseconds> can be used to set the heap snapshot interval. Default is undefined. Minimum is 30000 ms.
- */
 async function main() {
     log.debug(`Cli main() started`);
     startCpuMemoryCheck();
@@ -180,7 +93,6 @@ async function main() {
     const { Matterbridge } = await import('./matterbridge.js');
     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();
     }
@@ -198,18 +110,11 @@ main().catch((error) => {
     inspectError(log, 'Matterbridge.loadInstance() failed with error', error);
     shutdown();
 });
-/**
- * Displays the version.
- */
 async function version() {
-    // Dynamic JSON import (Node >= 20) with import attributes
     const { default: pkg } = await import('../package.json', { with: { type: 'json' } });
     console.log(`Matterbridge version ${pkg.version}`);
     process.exit(0);
 }
-/**
- * Displays the help.
- */
 function help() {
     console.log(`
   Usage: matterbridge [options] [command] 
@@ -265,4 +170,3 @@ function help() {
   `);
     process.exit(0);
 }
-//# sourceMappingURL=cli.js.map

package/dist/cliEmitter.js

@@ -1,49 +1,12 @@
-/**
- * This file contains the CLI emitter.
- *
- * @file cliEmitter.ts
- * @author Luca Liguori
- * @created 2025-07-04
- * @version 1.0.2
- * @license Apache-2.0
- *
- * Copyright 2025, 2026, 2027 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.
- */
-// eslint-disable-next-line no-console
 if (process.argv.includes('--loader') || process.argv.includes('-loader'))
     console.log('\u001B[32mCli emitter loaded.\u001B[40;0m');
 import { EventEmitter } from 'node:events';
 export const cliEmitter = new EventEmitter();
 export let lastOsCpuUsage = 0;
 export let lastProcessCpuUsage = 0;
-/**
- * Sets the last os CPU usage.
- *
- * @param {number} val - The os CPU usage percentage to set.
- * @returns {void}
- */
 export function setLastOsCpuUsage(val) {
     lastOsCpuUsage = val;
 }
-/**
- * Sets the last process CPU usage.
- *
- * @param {number} val - The process CPU usage percentage to set.
- * @returns {void}
- */
 export function setLastProcessCpuUsage(val) {
     lastProcessCpuUsage = val;
 }
-//# sourceMappingURL=cliEmitter.js.map

package/dist/cliHistory.js

@@ -1,40 +1,9 @@
-/**
- * This file contains the CLI history page generator.
- *
- * @file cliHistory.ts
- * @author Luca Liguori
- * @created 2025-10-09
- * @version 1.0.1
- * @license Apache-2.0
- *
- * Copyright 2025, 2026, 2027 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.
- */
-// eslint-disable-next-line no-console
 if (process.argv.includes('--loader') || process.argv.includes('-loader'))
     console.log('\u001B[32mCli history loaded.\u001B[40;0m');
 import { writeFileSync } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { Tracker } from './utils/tracker.js';
-/**
- * Generates a static HTML dashboard displaying CPU and memory history.
- *
- * @param {GenerateHistoryPageOptions} [options] - Optional configuration for output path, page title, and refresh interval.
- *
- * @returns {string | undefined} The absolute path to the generated HTML file, or undefined if no samples exist.
- */
 export function generateHistoryPage(options = {}) {
     const pageTitle = options.pageTitle ?? 'Matterbridge CPU & Memory History';
     const hostname = options.hostname ?? os.hostname();
@@ -814,13 +783,6 @@ export function generateHistoryPage(options = {}) {
     writeFileSync(outputPath, html, { encoding: 'utf-8' });
     return outputPath;
 }
-/**
- * Escapes HTML special characters to prevent breaking embedded markup.
- *
- * @param {string} input - The string to escape.
- * @returns {string} The escaped string safe for HTML contexts.
- */
 function escapeHtml(input) {
     return input.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
 }
-//# sourceMappingURL=cliHistory.js.map

package/dist/clusters/export.js

@@ -1,3 +1 @@
 export {};
-// Nothing to export right now, but this file is here to make it easier to add exports in the future
-//# sourceMappingURL=export.js.map