homebridge 2.0.3-beta.9 → 2.1.0

package/dist/server.d.ts

@@ -38,6 +38,7 @@ export declare class Server {
     private readonly externalMatterBridgeRegistry;
     private matterMonitoringActive;
     private matterMonitoringClients;
+    private readonly pendingMatterAccessoryInfoLookups;
     private serverStatus;
     constructor(options?: HomebridgeOptions);
     /**
@@ -55,12 +56,16 @@ export declare class Server {
     private handleTriggerMatterCommand;
     /**
      * Whether HAP should be published for the given bridge configuration.
-     * HAP is on by default; users opt out via `bridge.hap: false`.
+     * HAP is on by default; users opt out via `bridge.hap.enabled: false`.
+     * In externalsOnly mode the bridge accessory itself is not published, so
+     * this returns false there too — externals are handled separately by
+     * BridgeService.
      */
     static isHapEnabled(bridgeConfig: BridgeConfiguration): boolean;
     /**
-     * Whether Matter is configured for the given bridge.
-     * Matter is opt-in: a `bridge.matter` block must be present.
+     * Whether Matter is enabled for the given bridge.
+     * Matter is opt-in: a `bridge.matter` block must be present and not
+     * explicitly disabled via `bridge.matter.enabled: false`.
      */
     static isMatterEnabledForBridge(bridgeConfig: BridgeConfiguration): boolean;
     private static loadConfig;
@@ -76,12 +81,20 @@ export declare class Server {
     private initializeIpcEventHandlers;
     /**
      * Handle start Matter monitoring request from UI
-     * Only starts monitoring if this is the first client
+     * Only starts monitoring if this is the first client.
+     *
+     * The UI parks each `startMatterMonitoring` request under a `correlationId`
+     * so it can route the ack back to the matching waiter and gate its first
+     * `getMatterAccessories` on it; echo it on the reply so the UI's dispatcher
+     * (which drops events without a correlationId) can deliver it.
      */
     private handleStartMatterMonitoring;
     /**
      * Handle stop Matter monitoring request from UI
-     * Only stops monitoring when no more clients
+     * Only stops monitoring when no more clients.
+     *
+     * Echo the request's `correlationId` for the same reason as
+     * `handleStartMatterMonitoring`.
      */
     private handleStopMatterMonitoring;
     /**
@@ -92,8 +105,17 @@ export declare class Server {
      */
     registerExternalMatterBridge(externalBridgeUsername: string, ownerUsername: string): void;
     /**
-     * Get Matter accessories for a specific bridge or all bridges
-     * @param bridgeUsername - Optional: specific bridge username (MAC format)
+     * Cancel the pending fallback timer for a forwarded Matter accessory lookup.
+     * Called by ChildBridgeService when a child responds with accessoryInfoData
+     * so the 2s "Timed out" event isn't sent after a successful response.
+     */
+    private cancelPendingMatterAccessoryInfoLookup;
+    /**
+     * Get Matter accessories for a specific bridge or all bridges.
+     *
+     * The UI parks each request under a `correlationId` and routes responses
+     * back to the matching waiter; events without the original correlationId
+     * are dropped, so every emitted `accessoriesData` event must echo it.
      */
     private handleGetMatterAccessories;
     /**

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,mBAAmB,EAAmC,MAAM,oBAAoB,CAAA;AAiB9F,OAAO,EAAsC,UAAU,EAAsB,MAAM,iBAAiB,CAAA;AAepG,MAAM,WAAW,iBAAiB;IAChC,6BAA6B,CAAC,EAAE,OAAO,CAAA;IACvC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACjC;AAGD,0BAAkB,YAAY;IAC5B;;OAEG;IACH,OAAO,YAAY;IAEnB;;OAEG;IACH,EAAE,OAAO;IAET;;OAEG;IACH,IAAI,SAAS;CACd;AAED,qBAAa,MAAM;IA8Bf,OAAO,CAAC,OAAO;IA7BjB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAE/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAIzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6C;IAI1E,OAAO,CAAC,aAAa,CAAC,CAAqB;IAK3C,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAAiC;IAG9E,OAAO,CAAC,sBAAsB,CAAQ;IACtC,OAAO,CAAC,uBAAuB,CAAI;IAGnC,OAAO,CAAC,YAAY,CAAqC;gBAG/C,OAAO,GAAE,iBAAsB;IA6DzC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAsBV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqFtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtC,OAAO,CAAC,aAAa;IAKrB;;;OAGG;YACW,0BAA0B;IAOxC;;;OAGG;WACW,YAAY,CAAC,YAAY,EAAE,mBAAmB,GAAG,OAAO;IAItE;;;OAGG;WACW,wBAAwB,CAAC,YAAY,EAAE,mBAAmB,GAAG,OAAO;IAIlF,OAAO,CAAC,MAAM,CAAC,UAAU;IAsGzB,OAAO,CAAC,eAAe;IAuGvB,OAAO,CAAC,aAAa;IA+FrB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAsDjC;;OAEG;IACH,OAAO,CAAC,0BAA0B;IA4DlC;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IA8BnC;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IAyClC;;;;;OAKG;IACI,4BAA4B,CAAC,sBAAsB,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAOhG;;;OAGG;YACW,0BAA0B;IAkExC;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAsEpC;;OAEG;YACW,4BAA4B;IAmK1C,OAAO,CAAC,cAAc;CAoBvB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,mBAAmB,EAAmC,MAAM,oBAAoB,CAAA;AAiB9F,OAAO,EAAsC,UAAU,EAAsB,MAAM,iBAAiB,CAAA;AAUpG,MAAM,WAAW,iBAAiB;IAChC,6BAA6B,CAAC,EAAE,OAAO,CAAA;IACvC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACjC;AAGD,0BAAkB,YAAY;IAC5B;;OAEG;IACH,OAAO,YAAY;IAEnB;;OAEG;IACH,EAAE,OAAO;IAET;;OAEG;IACH,IAAI,SAAS;CACd;AAED,qBAAa,MAAM;IAmCf,OAAO,CAAC,OAAO;IAlCjB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAE/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAIzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6C;IAI1E,OAAO,CAAC,aAAa,CAAC,CAAqB;IAK3C,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAAiC;IAG9E,OAAO,CAAC,sBAAsB,CAAQ;IACtC,OAAO,CAAC,uBAAuB,CAAI;IAKnC,OAAO,CAAC,QAAQ,CAAC,iCAAiC,CAAwD;IAG1G,OAAO,CAAC,YAAY,CAAqC;gBAG/C,OAAO,GAAE,iBAAsB;IA8DzC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAsBV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2FtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBtC,OAAO,CAAC,aAAa;IAKrB;;;OAGG;YACW,0BAA0B;IAOxC;;;;;;OAMG;WACW,YAAY,CAAC,YAAY,EAAE,mBAAmB,GAAG,OAAO;IAItE;;;;OAIG;WACW,wBAAwB,CAAC,YAAY,EAAE,mBAAmB,GAAG,OAAO;IAIlF,OAAO,CAAC,MAAM,CAAC,UAAU;IAoGzB,OAAO,CAAC,eAAe;IAyGvB,OAAO,CAAC,aAAa;IAiGrB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IA4DjC;;OAEG;IACH,OAAO,CAAC,0BAA0B;IA4DlC;;;;;;;;OAQG;IACH,OAAO,CAAC,2BAA2B;IAiCnC;;;;;;OAMG;IACH,OAAO,CAAC,0BAA0B;IA8ClC;;;;;OAKG;IACI,4BAA4B,CAAC,sBAAsB,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAOhG;;;;OAIG;IACH,OAAO,CAAC,sCAAsC;IAQ9C;;;;;;OAMG;YACW,0BAA0B;IAyExC;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAuFpC;;OAEG;YACW,4BAA4B;IAwK1C,OAAO,CAAC,cAAc;CAqBvB"}

package/dist/server.js

@@ -3,19 +3,15 @@ import process from 'node:process';
 import chalk from 'chalk';
 import qrcode from 'qrcode-terminal';
 import { HomebridgeAPI } from './api.js';
-import { BridgeService } from './bridgeService.js';
+import { BridgeService, isHapConfigEnabled, isHapExternalsOnly, validateHapConfig } from './bridgeService.js';
 import { ChildBridgeService } from './childBridgeService.js';
 import { ExternalPortService } from './externalPortService.js';
 import { IpcService } from './ipcService.js';
 import { Logger } from './logger.js';
-import { MatterConfigCollector } from './matter/config.js';
+import { isMatterActive, isMatterConfigEnabled, MatterConfigCollector } from './matter/config.js';
 import { PluginManager } from './pluginManager.js';
 import { User } from './user.js';
 import { validMacAddress } from './util/mac.js';
-// HAP specifies QR error-correction level M or higher for ECC. Set once at
-// module load — qrcode-terminal stores this on the (process-global) module,
-// so re-setting it on every printSetupInfo call was redundant.
-qrcode.setErrorLevel('M');
 const log = Logger.internal;
 const matterLogger = Logger.withPrefix('Matter/MainManager');
 // eslint-disable-next-line no-restricted-syntax
@@ -55,6 +51,10 @@ export class Server {
     // Matter monitoring state (for UI accessories page)
     matterMonitoringActive = false;
     matterMonitoringClients = 0;
+    // Fallback timers for child-bridge Matter accessory lookups. Keyed by uuid
+    // so that a child's accessoryInfoData (success or error) can cancel the
+    // timer before it fires a spurious "Timed out" event at the UI.
+    pendingMatterAccessoryInfoLookups = new Map();
     // current server status
     serverStatus = "pending" /* ServerStatus.PENDING */;
     constructor(options = {}) {
@@ -80,6 +80,7 @@ export class Server {
         const bridgeConfig = {
             cachedAccessoriesDir: User.cachedAccessoryPath(),
             cachedAccessoriesItemName: 'cachedAccessories',
+            externalAccessoriesItemName: 'externalAccessories',
         };
         // shallow copy the homebridge options to the bridge options object
         Object.assign(bridgeConfig, this.options);
@@ -178,9 +179,16 @@ export class Server {
             this.publishBridge();
         }
         else {
-            // HAP is opted out. The bridge ADVERTISED listener won't fire, so move
-            // server status to OK explicitly — Matter is the only protocol up here.
-            log.info('HAP is disabled for the main bridge (bridge.hap=false); skipping HAP publish.');
+            // HAP is opted out (or externalsOnly mode is set). The bridge ADVERTISED
+            // listener won't fire for the bridge itself, so move server status to OK
+            // explicitly. Matter may or may not be up — if both protocols are
+            // suppressed the bridge simply advertises nothing of its own.
+            if (isHapExternalsOnly(this.config.bridge.hap)) {
+                log.info('HAP externalsOnly mode for the main bridge; bridge accessory will not publish but external accessories will.');
+            }
+            else {
+                log.info('HAP is disabled for the main bridge (bridge.hap.enabled=false); skipping HAP publish.');
+            }
             this.setServerStatus("ok" /* ServerStatus.OK */);
         }
     }
@@ -188,6 +196,14 @@ export class Server {
         this.bridgeService.teardown();
         // Teardown Matter servers (main bridge and external accessories)
         await this.matterManager?.teardown();
+        // Cancel any in-flight Matter accessory info fallback timers so they
+        // don't fire `accessoryInfoData` events at the IPC channel after the
+        // service has stopped. The timers are already unref()'d so they don't
+        // hold the loop open — this is for tidiness, not a real leak.
+        for (const timer of this.pendingMatterAccessoryInfoLookups.values()) {
+            clearTimeout(timer);
+        }
+        this.pendingMatterAccessoryInfoLookups.clear();
         this.ipcService.stop();
         this.setServerStatus("down" /* ServerStatus.DOWN */);
     }
@@ -207,17 +223,21 @@ export class Server {
     }
     /**
      * Whether HAP should be published for the given bridge configuration.
-     * HAP is on by default; users opt out via `bridge.hap: false`.
+     * HAP is on by default; users opt out via `bridge.hap.enabled: false`.
+     * In externalsOnly mode the bridge accessory itself is not published, so
+     * this returns false there too — externals are handled separately by
+     * BridgeService.
      */
     static isHapEnabled(bridgeConfig) {
-        return bridgeConfig.hap !== false;
+        return isHapConfigEnabled(bridgeConfig.hap) && !isHapExternalsOnly(bridgeConfig.hap);
     }
     /**
-     * Whether Matter is configured for the given bridge.
-     * Matter is opt-in: a `bridge.matter` block must be present.
+     * Whether Matter is enabled for the given bridge.
+     * Matter is opt-in: a `bridge.matter` block must be present and not
+     * explicitly disabled via `bridge.matter.enabled: false`.
      */
     static isMatterEnabledForBridge(bridgeConfig) {
-        return !!bridgeConfig.matter;
+        return isMatterConfigEnabled(bridgeConfig.matter);
     }
     static loadConfig() {
         // Look for the configuration file
@@ -262,24 +282,24 @@ export class Server {
         bridge.username = bridge.username || defaultBridge.username;
         bridge.pin = bridge.pin || defaultBridge.pin;
         config.bridge = bridge;
-        // Protocol-enablement validation: at least one of HAP or Matter must be on.
-        // HAP is enabled by default; users opt out via `bridge.hap: false`.
-        // Matter is enabled when `bridge.matter` is configured.
-        if (!Server.isHapEnabled(config.bridge) && !Server.isMatterEnabledForBridge(config.bridge)) {
-            throw new Error('At least one protocol (HAP or Matter) must be enabled. '
-                + 'Set `bridge.hap` to true or add a `bridge.matter` configuration.');
-        }
         // Validate Matter port pool configuration. Must run after bridge defaults
         // are filled in, since the cast to HomebridgeConfig only becomes honest at
         // that point.
         MatterConfigCollector.validateMatterPortsPool(config);
         // Normalise the main bridge username to uppercase so downstream comparisons
         // (validMacAddress, registry lookups, child-bridge dedup) stay case-consistent.
-        config.bridge.username = config.bridge.username.toUpperCase();
+        // Guarded so a malformed (non-string) value falls through to `validMacAddress`
+        // below and produces the proper "Not a valid username" error rather than a
+        // raw TypeError from calling toUpperCase on a number/boolean.
+        if (typeof config.bridge.username === 'string') {
+            config.bridge.username = config.bridge.username.toUpperCase();
+        }
         const username = config.bridge.username;
         if (!validMacAddress(username)) {
             throw new Error(`Not a valid username: ${username}. Must be 6 pairs of colon-separated hexadecimal chars (A-F 0-9), like a MAC address.`);
         }
+        // Validate the main bridge HAP config (shape + externalsOnly/enabled coherence).
+        validateHapConfig(config.bridge, { bridgeLabel: 'main bridge' });
         config.accessories = config.accessories || [];
         config.platforms = config.platforms || [];
         if (!Array.isArray(config.accessories)) {
@@ -365,6 +385,8 @@ export class Server {
                     childBridge = new ChildBridgeService("accessory" /* PluginType.ACCESSORY */, accessoryIdentifier, plugin, accessoryConfig._bridge, this.config, this.options, this.api, this.ipcService, this.externalPortService);
                     // Set callback for external Matter bridge registration
                     childBridge.onExternalBridgeRegistered = this.registerExternalMatterBridge.bind(this);
+                    // Cancel the parent-side fallback timer when this child answers a lookup
+                    childBridge.onAccessoryInfoResponse = this.cancelPendingMatterAccessoryInfoLookup.bind(this);
                     this.childBridges.set(accessoryConfig._bridge.username, childBridge);
                 }
                 // add config to child bridge service
@@ -440,6 +462,8 @@ export class Server {
                 const childBridge = new ChildBridgeService("platform" /* PluginType.PLATFORM */, platformIdentifier, plugin, platformConfig._bridge, this.config, this.options, this.api, this.ipcService, this.externalPortService);
                 // Set callback for external Matter bridge registration
                 childBridge.onExternalBridgeRegistered = this.registerExternalMatterBridge.bind(this);
+                // Cancel the parent-side fallback timer when this child answers a lookup
+                childBridge.onAccessoryInfoResponse = this.cancelPendingMatterAccessoryInfoLookup.bind(this);
                 this.childBridges.set(platformConfig._bridge.username, childBridge);
                 // add config to child bridge service
                 childBridge.addConfig(platformConfig);
@@ -468,15 +492,13 @@ export class Server {
             throw new Error(`Error loading the ${type} "${identifier}" requested in your config.json - `
                 + 'Missing required field "_bridge.username".');
         }
-        // At least one of HAP or Matter must be enabled per child bridge.
-        // Note: Matter is unsupported on accessory-style child bridges (warned about
-        // in childBridgeFork.ts), so for ACCESSORY child bridges only HAP counts.
-        const hapOk = Server.isHapEnabled(bridgeConfig);
-        const matterOk = type === "platform" /* PluginType.PLATFORM */ && Server.isMatterEnabledForBridge(bridgeConfig);
-        if (!hapOk && !matterOk) {
-            throw new Error(`Error loading the ${type} "${identifier}" requested in your config.json - `
-                + 'at least one protocol must be enabled on this child bridge. '
-                + 'Set `_bridge.hap` to true or add a `_bridge.matter` configuration.');
+        // Normalise the child username to uppercase, mirroring the main bridge
+        // (loadConfig). validMacAddress only accepts A-F, so without this a lowercase
+        // MAC in _bridge.username would be rejected here even though the identical
+        // value is accepted on the main bridge. Guarded so a non-string value still
+        // falls through to the proper "not a valid username" error below.
+        if (typeof bridgeConfig.username === 'string') {
+            bridgeConfig.username = bridgeConfig.username.toUpperCase();
         }
         if (!validMacAddress(bridgeConfig.username)) {
             throw new Error(`Error loading the ${type} "${identifier}" requested in your config.json - `
@@ -495,10 +517,19 @@ export class Server {
                     + `Duplicate username found in _bridge.username: "${bridgeConfig.username}". You can only group accessories of the same type in a child bridge.`);
             }
         }
-        if (bridgeConfig.username === this.config.bridge.username.toUpperCase()) {
+        // Both usernames are normalised to uppercase (main in loadConfig, child
+        // above), so a direct comparison is case-consistent.
+        if (bridgeConfig.username === this.config.bridge.username) {
             throw new Error(`Error loading the ${type} "${identifier}" requested in your config.json - `
                 + `Username found in _bridge.username: "${bridgeConfig.username}" is the same as the main bridge. Each child bridge platform/accessory must have it's own unique username.`);
         }
+        // Validate the child bridge HAP config (shape + externalsOnly/enabled coherence).
+        // For accessory child bridges, `hap.externalsOnly` is stripped with a warning
+        // since externals are not supported via the accessory plugin API.
+        validateHapConfig(bridgeConfig, {
+            bridgeLabel: `${type} "${identifier}" child bridge`,
+            isAccessoryPlugin: type === "accessory" /* PluginType.ACCESSORY */,
+        });
     }
     /**
      * Takes care of the IPC Events sent to Homebridge
@@ -534,14 +565,14 @@ export class Server {
             this.ipcService.sendMessage("childBridgeMetadataResponse" /* IpcOutgoingEvent.CHILD_BRIDGE_METADATA_RESPONSE */, Array.from(this.childBridges.values(), x => x.getMetadata()));
         });
         // Matter monitoring lifecycle handlers
-        this.ipcService.on("startMatterMonitoring" /* IpcIncomingEvent.START_MATTER_MONITORING */, () => {
-            this.handleStartMatterMonitoring();
+        this.ipcService.on("startMatterMonitoring" /* IpcIncomingEvent.START_MATTER_MONITORING */, (data) => {
+            this.handleStartMatterMonitoring(data);
         });
-        this.ipcService.on("stopMatterMonitoring" /* IpcIncomingEvent.STOP_MATTER_MONITORING */, () => {
-            this.handleStopMatterMonitoring();
+        this.ipcService.on("stopMatterMonitoring" /* IpcIncomingEvent.STOP_MATTER_MONITORING */, (data) => {
+            this.handleStopMatterMonitoring(data);
         });
         this.ipcService.on("getMatterAccessories" /* IpcIncomingEvent.GET_MATTER_ACCESSORIES */, (data) => {
-            void this.handleGetMatterAccessories(data?.bridgeUsername);
+            void this.handleGetMatterAccessories(data);
         });
         this.ipcService.on("getMatterAccessoryInfo" /* IpcIncomingEvent.GET_MATTER_ACCESSORY_INFO */, (data) => {
             this.handleGetMatterAccessoryInfo(data?.uuid);
@@ -552,9 +583,15 @@ export class Server {
     }
     /**
      * Handle start Matter monitoring request from UI
-     * Only starts monitoring if this is the first client
+     * Only starts monitoring if this is the first client.
+     *
+     * The UI parks each `startMatterMonitoring` request under a `correlationId`
+     * so it can route the ack back to the matching waiter and gate its first
+     * `getMatterAccessories` on it; echo it on the reply so the UI's dispatcher
+     * (which drops events without a correlationId) can deliver it.
      */
-    handleStartMatterMonitoring() {
+    handleStartMatterMonitoring(data) {
+        const correlationId = data?.correlationId;
         this.matterMonitoringClients++;
         // Only setup monitoring if this is the first client
         if (this.matterMonitoringClients === 1) {
@@ -567,6 +604,7 @@ export class Server {
             }
             const event = {
                 type: 'monitoringStarted',
+                correlationId,
                 data: { success: true },
             };
             this.ipcService.sendMessage("matterEvent" /* IpcOutgoingEvent.MATTER_EVENT */, event);
@@ -575,6 +613,7 @@ export class Server {
             // Already monitoring, just acknowledge
             const event = {
                 type: 'monitoringStarted',
+                correlationId,
                 data: { success: true, alreadyActive: true },
             };
             this.ipcService.sendMessage("matterEvent" /* IpcOutgoingEvent.MATTER_EVENT */, event);
@@ -582,14 +621,19 @@ export class Server {
     }
     /**
      * Handle stop Matter monitoring request from UI
-     * Only stops monitoring when no more clients
+     * Only stops monitoring when no more clients.
+     *
+     * Echo the request's `correlationId` for the same reason as
+     * `handleStartMatterMonitoring`.
      */
-    handleStopMatterMonitoring() {
+    handleStopMatterMonitoring(data) {
+        const correlationId = data?.correlationId;
         if (this.matterMonitoringClients <= 0) {
             // Nothing to do, but still acknowledge so the UI doesn't sit waiting
             // for a confirmation event that never comes.
             const event = {
                 type: 'monitoringStopped',
+                correlationId,
                 data: { success: true, alreadyStopped: true },
             };
             this.ipcService.sendMessage("matterEvent" /* IpcOutgoingEvent.MATTER_EVENT */, event);
@@ -607,6 +651,7 @@ export class Server {
             }
             const event = {
                 type: 'monitoringStopped',
+                correlationId,
                 data: { success: true },
             };
             this.ipcService.sendMessage("matterEvent" /* IpcOutgoingEvent.MATTER_EVENT */, event);
@@ -615,6 +660,7 @@ export class Server {
             // Other clients still monitoring
             const event = {
                 type: 'monitoringStopped',
+                correlationId,
                 data: { success: true, othersActive: true },
             };
             this.ipcService.sendMessage("matterEvent" /* IpcOutgoingEvent.MATTER_EVENT */, event);
@@ -633,15 +679,33 @@ export class Server {
         this.externalMatterBridgeRegistry.set(normalizedExternal, normalizedOwner);
     }
     /**
-     * Get Matter accessories for a specific bridge or all bridges
-     * @param bridgeUsername - Optional: specific bridge username (MAC format)
+     * Cancel the pending fallback timer for a forwarded Matter accessory lookup.
+     * Called by ChildBridgeService when a child responds with accessoryInfoData
+     * so the 2s "Timed out" event isn't sent after a successful response.
+     */
+    cancelPendingMatterAccessoryInfoLookup(uuid) {
+        const timer = this.pendingMatterAccessoryInfoLookups.get(uuid);
+        if (timer) {
+            clearTimeout(timer);
+            this.pendingMatterAccessoryInfoLookups.delete(uuid);
+        }
+    }
+    /**
+     * Get Matter accessories for a specific bridge or all bridges.
+     *
+     * The UI parks each request under a `correlationId` and routes responses
+     * back to the matching waiter; events without the original correlationId
+     * are dropped, so every emitted `accessoriesData` event must echo it.
      */
-    async handleGetMatterAccessories(bridgeUsername) {
+    async handleGetMatterAccessories(data) {
+        const bridgeUsername = data?.bridgeUsername;
+        const correlationId = data?.correlationId;
         // Check if monitoring is active
         if (!this.matterMonitoringActive) {
             matterLogger.warn('Matter monitoring not active - cannot get accessories');
             const event = {
                 type: 'accessoriesData',
+                correlationId,
                 data: {
                     bridgeUsername,
                     error: 'Matter monitoring not active',
@@ -654,6 +718,7 @@ export class Server {
         if (!this.api.isMatterEnabled() && this.childBridges.size === 0) {
             const event = {
                 type: 'accessoriesData',
+                correlationId,
                 data: {
                     bridgeUsername,
                     accessories: [],
@@ -676,6 +741,7 @@ export class Server {
             }
             const event = {
                 type: 'accessoriesData',
+                correlationId,
                 data: {
                     bridgeUsername: bridgeUsername || 'all',
                     accessories: allAccessories,
@@ -687,6 +753,7 @@ export class Server {
             matterLogger.error('Failed to get Matter accessories:', error);
             const event = {
                 type: 'accessoriesData',
+                correlationId,
                 data: {
                     bridgeUsername,
                     error: error instanceof Error ? error.message : 'Unknown error',
@@ -720,13 +787,19 @@ export class Server {
                 this.ipcService.sendMessage("matterEvent" /* IpcOutgoingEvent.MATTER_EVENT */, event);
                 return;
             }
-            // If not found on main bridge, forward to child bridges with Matter enabled.
+            // If not found on main bridge, forward to child bridges whose Matter is
+            // actually active. A child with `matter: { enabled: false }` still carries
+            // a matterConfig block but never starts a Matter message handler, so it
+            // would never answer — forwarding to it would only make the UI wait out
+            // the 2s fallback instead of getting an immediate "not found". Gate on
+            // isMatterActive (enabled or externalsOnly), which mirrors the condition
+            // under which the child actually creates its Matter handler.
             // The matching child responds directly to the UI via the existing
             // MATTER_EVENT forwarding path; schedule a fallback error so the UI
             // doesn't hang if no child knows the UUID either.
             let forwardedToChildren = false;
             for (const childBridge of this.childBridges.values()) {
-                if (childBridge.getMetadata().matterConfig) {
+                if (isMatterActive(childBridge.getMetadata().matterConfig)) {
                     childBridge.getMatterAccessoryInfo(uuid);
                     forwardedToChildren = true;
                 }
@@ -740,8 +813,17 @@ export class Server {
             }
             // 2s is comfortably longer than a healthy child response and short
             // enough that the UI doesn't feel stuck. Use unref() so a late
-            // shutdown doesn't wait on this timer.
-            setTimeout(() => {
+            // shutdown doesn't wait on this timer. The timer is registered in
+            // pendingMatterAccessoryInfoLookups so a child's accessoryInfoData
+            // response (routed via ChildBridgeService.onAccessoryInfoResponse) can
+            // cancel it before it fires a spurious timed-out event. A second
+            // concurrent request for the same uuid replaces the existing timer.
+            const existing = this.pendingMatterAccessoryInfoLookups.get(uuid);
+            if (existing) {
+                clearTimeout(existing);
+            }
+            const fallback = setTimeout(() => {
+                this.pendingMatterAccessoryInfoLookups.delete(uuid);
                 this.ipcService.sendMessage("matterEvent" /* IpcOutgoingEvent.MATTER_EVENT */, {
                     type: 'accessoryInfoData',
                     data: {
@@ -750,7 +832,9 @@ export class Server {
                         timedOut: true,
                     },
                 });
-            }, 2000).unref();
+            }, 2000);
+            fallback.unref();
+            this.pendingMatterAccessoryInfoLookups.set(uuid, fallback);
         }
         catch (error) {
             matterLogger.error('Failed to get Matter accessory info:', error);
@@ -896,8 +980,13 @@ export class Server {
             });
         }
         catch (error) {
-            // Main bridge doesn't have accessory - forward to child bridges with Matter enabled
-            const matterChildBridges = [...this.childBridges.values()].filter(bridge => bridge.getMetadata().matterConfig);
+            // Main bridge doesn't have accessory - forward to child bridges whose
+            // Matter is actually active. A child with `matter: { enabled: false }`
+            // still carries a matterConfig block but never starts a Matter handler,
+            // so forwarding a control request to it would just be dropped. Gate on
+            // isMatterActive (enabled or externalsOnly) — the same condition under
+            // which the child creates its Matter handler.
+            const matterChildBridges = [...this.childBridges.values()].filter(bridge => isMatterActive(bridge.getMetadata().matterConfig));
             if (matterChildBridges.length > 0) {
                 matterLogger.debug(`Main bridge doesn't have accessory ${data.uuid}, forwarding to ${matterChildBridges.length} child bridge(s) with Matter enabled`);
                 for (const childBridge of matterChildBridges) {
@@ -923,6 +1012,7 @@ export class Server {
         console.log(this.bridgeService.bridge.setupURI());
         if (!this.options.hideQRCode) {
             console.log('Scan this code with your HomeKit app on your iOS device to pair with Homebridge:');
+            qrcode.setErrorLevel('M'); // HAP specifies level M or higher for ECC
             qrcode.generate(this.bridgeService.bridge.setupURI());
             console.log('Or enter this code with your HomeKit app on your iOS device to pair with Homebridge:');
         }