homebridge 2.0.0-alpha.41 → 2.0.0-alpha.43

package/dist/server.js

@@ -5,11 +5,10 @@ import qrcode from 'qrcode-terminal';
 import { HomebridgeAPI } from './api.js';
 import { BridgeService } from './bridgeService.js';
 import { ChildBridgeService } from './childBridgeService.js';
-import { ChildMatterBridgeService } from './childMatterBridgeService.js';
 import { ExternalPortService } from './externalPortService.js';
 import { IpcService } from './ipcService.js';
 import { Logger } from './logger.js';
-import { MatterConfigValidator } from './matter/matterConfigValidator.js';
+import { MatterConfigValidator, MatterServer } from './matter/index.js';
 import { PluginManager } from './pluginManager.js';
 import { User } from './user.js';
 import { validMacAddress } from './util/mac.js';
@@ -39,8 +38,12 @@ export class Server {
     externalPortService;
     config;
     // used to keep track of child bridges
+    // Key is either HAP username (MAC address) or Matter-only identifier (e.g., "matter-plugin-platform")
     childBridges = new Map();
-    childMatterBridges = new Map();
+    // Matter server instance for main bridge (if enabled)
+    matterServer;
+    // Cache for Matter bridge identifier -> ChildBridgeService lookups
+    matterBridgeCache = new Map();
     // Track platform configurations for routing accessories
     platformConfigs = new Map();
     // current server status
@@ -70,12 +73,15 @@ export class Server {
         // shallow copy the homebridge options to the bridge options object
         Object.assign(bridgeConfig, this.options);
         this.bridgeService = new BridgeService(this.api, this.pluginManager, this.externalPortService, bridgeConfig, this.config.bridge, this.config);
-        // Matter is handled via _matter configuration, not API events
-        // Intercept platform accessory registration to route to Matter bridges if needed
+        // Handle platform accessory registration
         this.api.on("registerPlatformAccessories" /* InternalAPIEvent.REGISTER_PLATFORM_ACCESSORIES */, this.handleRegisterPlatformAccessories.bind(this));
         this.api.on("unregisterPlatformAccessories" /* InternalAPIEvent.UNREGISTER_PLATFORM_ACCESSORIES */, this.handleUnregisterPlatformAccessories.bind(this));
-        // Handle external accessories (cameras, etc.) for Matter
+        // Handle external accessories (cameras, etc.)
         this.api.on("publishExternalAccessories" /* InternalAPIEvent.PUBLISH_EXTERNAL_ACCESSORIES */, this.handlePublishExternalAccessories.bind(this));
+        // Handle Matter accessory registration
+        this.api.on("registerMatterAccessory" /* InternalAPIEvent.REGISTER_MATTER_ACCESSORY */, this.handleRegisterMatterAccessory.bind(this));
+        this.api.on("unregisterMatterAccessory" /* InternalAPIEvent.UNREGISTER_MATTER_ACCESSORY */, this.handleUnregisterMatterAccessory.bind(this));
+        this.api.on("updateMatterAccessoryState" /* InternalAPIEvent.UPDATE_MATTER_ACCESSORY_STATE */, this.handleUpdateMatterAccessoryState.bind(this));
         // watch bridge events to check when server is online
         this.bridgeService.bridge.on("advertised" /* AccessoryEventTypes.ADVERTISED */, () => {
             this.setServerStatus("ok" /* ServerStatus.OK */);
@@ -95,14 +101,6 @@ export class Server {
      */
     setServerStatus(status) {
         this.serverStatus = status;
-        // Collect child Matter bridge statuses
-        const childMatterBridgeStatuses = Array.from(this.childMatterBridges.values()).map(bridge => bridge.getMetadata());
-        // Get Matter bridges status (child bridges only)
-        const matterStatus = childMatterBridgeStatuses.length > 0
-            ? {
-                children: childMatterBridgeStatuses,
-            }
-            : undefined;
         this.ipcService.sendMessage("serverStatusUpdate" /* IpcOutgoingEvent.SERVER_STATUS_UPDATE */, {
             type: 'hap', // Main bridge is HAP
             status: this.serverStatus,
@@ -111,78 +109,29 @@ export class Server {
             name: this.bridgeService?.bridge?.displayName || this.config.bridge.name,
             username: this.config.bridge.username,
             pin: this.config.bridge.pin,
-            matterStatus,
         });
     }
     async start() {
         if (this.config.bridge.disableIpc !== true) {
             this.initializeIpcEventHandlers();
         }
-        // Track existing Matter bridges before loading new configuration
-        const existingMatterBridgeIds = new Set(this.childMatterBridges.keys());
-        // Validate child Matter configurations
-        const matterValidation = MatterConfigValidator.validateAllChildMatterConfigs(this.config.platforms, this.config.accessories);
-        if (!matterValidation.isValid) {
-            log.error('Child Matter configuration validation failed. Please fix the errors above.');
-            // Continue anyway but child Matter bridges may not work properly
-        }
         const promises = [];
         // load the cached accessories
         await this.bridgeService.loadCachedPlatformAccessoriesFromDisk();
         // initialize plugins
         await this.pluginManager.initializeInstalledPlugins();
+        // Initialize Matter server for main bridge if enabled
+        await this.initializeMatterServer();
         if (this.config.platforms.length > 0) {
             promises.push(...this.loadPlatforms());
         }
         if (this.config.accessories.length > 0) {
             this.loadAccessories();
         }
-        // Track which Matter bridges are still in the configuration
-        const currentMatterBridgeIds = new Set();
-        // Check platforms for Matter bridges
-        this.config.platforms.forEach((platformConfig) => {
-            if (platformConfig._matter && platformConfig.platform) {
-                try {
-                    const plugin = this.pluginManager.getPluginForPlatform(platformConfig.platform);
-                    const matterIdentifier = `${plugin.getPluginIdentifier()}-${platformConfig.platform}`;
-                    currentMatterBridgeIds.add(matterIdentifier);
-                }
-                catch {
-                    // Plugin not found, skip
-                }
-            }
-        });
-        // Check accessories for Matter bridges
-        this.config.accessories.forEach((accessoryConfig) => {
-            if (accessoryConfig._matter && accessoryConfig.accessory) {
-                try {
-                    const plugin = this.pluginManager.getPluginForAccessory(accessoryConfig.accessory);
-                    const matterIdentifier = `${plugin.getPluginIdentifier()}-${accessoryConfig.accessory}`;
-                    currentMatterBridgeIds.add(matterIdentifier);
-                }
-                catch {
-                    // Plugin not found, skip
-                }
-            }
-        });
-        // Clean up Matter bridges that were removed from configuration
-        for (const bridgeId of existingMatterBridgeIds) {
-            if (!currentMatterBridgeIds.has(bridgeId) && this.childMatterBridges.has(bridgeId)) {
-                const removedBridge = this.childMatterBridges.get(bridgeId);
-                log.info(`Matter bridge "${bridgeId}" was removed from configuration, cleaning up...`);
-                // Stop and clean up the removed bridge (with permanent flag)
-                await removedBridge.teardown(true);
-                this.childMatterBridges.delete(bridgeId);
-            }
-        }
         // start child HAP bridges
         for (const childBridge of this.childBridges.values()) {
             childBridge.start();
         }
-        // start child Matter bridges
-        for (const childMatterBridge of this.childMatterBridges.values()) {
-            promises.push(childMatterBridge.start());
-        }
         // restore cached accessories
         this.bridgeService.restoreCachedPlatformAccessories();
         this.api.signalFinished();
@@ -191,157 +140,144 @@ export class Server {
             .then(() => this.publishBridge());
     }
     /**
-     * Get the status of all Matter bridges (child bridges only)
+     * Initialize Matter server for main bridge if enabled
      */
-    getMatterBridgesStatus() {
-        return Array.from(this.childMatterBridges.values()).map(bridge => bridge.getMetadata());
+    async initializeMatterServer() {
+        // Check if main bridge has matter configuration
+        if (!this.config.bridge.matter) {
+            return;
+        }
+        try {
+            log.info('Initializing Matter server for main bridge...');
+            // Allocate port from pool if not explicitly configured
+            let matterPort = this.config.bridge.matter.port;
+            if (!matterPort) {
+                matterPort = await this.externalPortService.requestPort(`${this.config.bridge.username}:MATTER`);
+                if (!matterPort) {
+                    matterPort = 5540; // Default Matter port
+                    log.warn('No port available from pool for main Matter bridge, using default port 5540');
+                }
+                else {
+                    log.info(`Allocated port ${matterPort} from pool for main Matter bridge`);
+                }
+            }
+            // Create Matter server instance
+            this.matterServer = new MatterServer({
+                storagePath: User.matterPath(),
+                port: matterPort,
+                uniqueId: 'main-bridge',
+                name: this.config.bridge.matter.name || (this.config.bridge.name ? `${this.config.bridge.name} (Matter)` : 'Homebridge Matter Bridge'),
+            });
+            // Start the Matter server
+            await this.matterServer.start();
+            log.info('Matter server initialized for main bridge');
+            // Inform the API that Matter is enabled
+            this.api._setMatterEnabled(true);
+            // Send Matter status update to notify UI that Matter server is ready
+            if (this.config.bridge.disableIpc !== true) {
+                this.sendMainBridgeMatterStatusUpdate();
+            }
+        }
+        catch (error) {
+            log.error('Failed to initialize Matter server for main bridge:', error);
+            // Provide user-friendly guidance for common errors
+            if (error.message && error.message.includes('corrupted')) {
+                log.error('');
+                log.error('╔════════════════════════════════════════════════════════════════════════════╗');
+                log.error('║  MATTER STORAGE CORRUPTED                                                  ║');
+                log.error('╠════════════════════════════════════════════════════════════════════════════╣');
+                log.error('║  Your Matter storage has become corrupted. This can happen when:          ║');
+                log.error('║  • Matter.js library version changes                                       ║');
+                log.error('║  • Storage format upgrades occur                                           ║');
+                log.error('║  • Incomplete writes during shutdown                                       ║');
+                log.error('║                                                                            ║');
+                log.error('║  To fix this, delete the corrupted storage directory:                     ║');
+                log.error('║  rm -rf ~/.homebridge/matter/main-bridge                                   ║');
+                log.error('║                                                                            ║');
+                log.error('║  Note: You will need to re-pair your Matter devices after deletion.       ║');
+                log.error('╚════════════════════════════════════════════════════════════════════════════╝');
+                log.error('');
+            }
+        }
+    }
+    /**
+     * Send Matter status update for main bridge
+     */
+    sendMainBridgeMatterStatusUpdate() {
+        if (!this.matterServer || !this.matterServer.isServerRunning()) {
+            return;
+        }
+        const commissioningInfo = this.matterServer.getCommissioningInfo();
+        // Transform property names to match UI expectations
+        const statusUpdate = {
+            type: 'matter',
+            status: 'ok',
+            port: this.config.bridge.matter?.port || 5540,
+            setupUri: commissioningInfo.qrCode, // Map qrCode -> setupUri for UI
+            pin: commissioningInfo.manualPairingCode, // Map manualPairingCode -> pin for UI
+            serialNumber: commissioningInfo.serialNumber,
+            passcode: commissioningInfo.passcode,
+            discriminator: commissioningInfo.discriminator,
+            name: this.config.bridge.matter?.name || (this.config.bridge.name ? `${this.config.bridge.name} (Matter)` : 'Homebridge Matter Bridge'),
+            plugin: 'main-bridge',
+            identifier: 'main-bridge',
+            deviceCount: this.matterServer.getAccessories().length,
+            commissioned: commissioningInfo.commissioned,
+        };
+        this.ipcService.sendMessage("matterBridgeStatusUpdate" /* IpcOutgoingEvent.MATTER_BRIDGE_STATUS_UPDATE */, statusUpdate);
     }
-    teardown() {
+    async teardown() {
         this.bridgeService.teardown();
-        // Stop all child Matter bridges
-        for (const childMatterBridge of this.childMatterBridges.values()) {
-            childMatterBridge.teardown().catch((error) => {
-                log.error(`Failed to stop child Matter bridge ${childMatterBridge.getDisplayName()}:`, error);
-            });
+        // Stop main Matter server if running
+        if (this.matterServer) {
+            try {
+                await this.matterServer.stop();
+            }
+            catch (error) {
+                log.error('Failed to stop Matter server:', error);
+            }
         }
+        // Child bridge Matter servers are stopped by their own forked processes
         this.setServerStatus("down" /* ServerStatus.DOWN */);
     }
     publishBridge() {
         this.bridgeService.publishBridge();
+        // Main bridge always has a pin (validated in loadConfig)
         this.printSetupInfo(this.config.bridge.pin);
     }
-    // Matter accessories are managed via _matter configuration, not API methods
     handlePublishExternalAccessories(accessories) {
         log.info(`Publishing ${accessories.length} external accessories`);
-        // External accessories are only published to child Matter bridges, not main bridge
-        // Group accessories by plugin
-        const accessoriesByPlugin = new Map();
-        accessories.forEach((accessory) => {
-            const pluginIdentifier = accessory._associatedPlugin;
-            if (!pluginIdentifier) {
-                log.warn(`External accessory "${accessory.displayName}" has no plugin identifier`);
-                return;
-            }
-            if (!accessoriesByPlugin.has(pluginIdentifier)) {
-                accessoriesByPlugin.set(pluginIdentifier, []);
-            }
-            accessoriesByPlugin.get(pluginIdentifier).push(accessory);
-        });
-        // Process each plugin's external accessories
-        accessoriesByPlugin.forEach((pluginAccessories, pluginIdentifier) => {
-            // Check if there's already an external Matter bridge for this plugin
-            const externalMatterBridgeId = `${pluginIdentifier}-external`;
-            let externalMatterBridge = this.childMatterBridges.get(externalMatterBridgeId);
-            if (!externalMatterBridge) {
-                // Check if this plugin has any Matter-enabled platform config
-                let hasMatterConfig = false;
-                let baseMatterConfig = {};
-                // Look for any platform with Matter config from this plugin
-                for (const [bridgeId, childBridge] of this.childMatterBridges) {
-                    if (bridgeId.startsWith(`${pluginIdentifier}-`) && childBridge.type === "platform" /* PluginType.PLATFORM */) {
-                        hasMatterConfig = true;
-                        // Use existing Matter bridge configuration as template
-                        baseMatterConfig = {
-                        // Port will be auto-allocated
-                        };
-                        break;
-                    }
-                }
-                // If plugin has Matter-enabled platforms, create external bridge automatically
-                if (hasMatterConfig) {
-                    log.info(`Automatically creating external Matter bridge for ${pluginIdentifier}`);
-                    const plugin = this.pluginManager.getPlugin(pluginIdentifier);
-                    if (!plugin) {
-                        log.warn(`Could not find plugin ${pluginIdentifier} to create external Matter bridge`);
-                        return;
-                    }
-                    // Create synthetic config for external bridge
-                    const externalConfig = {
-                        platform: '__external__',
-                        name: `${pluginIdentifier} External`,
-                        _matter: {
-                            ...baseMatterConfig,
-                            name: `${pluginIdentifier} External Matter`,
-                        },
-                    };
-                    externalMatterBridge = new ChildMatterBridgeService("platform" /* PluginType.PLATFORM */, plugin, externalConfig._matter, externalConfig, this.api, this.externalPortService, this.options, this.ipcService, this.config);
-                    this.childMatterBridges.set(externalMatterBridgeId, externalMatterBridge);
-                    // Start the external bridge
-                    externalMatterBridge.start().catch((error) => {
-                        log.error(`Failed to start external Matter bridge for ${pluginIdentifier}:`, error);
-                    });
-                }
-            }
-            // Publish accessories to appropriate bridge
-            if (externalMatterBridge) {
-                pluginAccessories.forEach((accessory) => {
-                    externalMatterBridge.addAccessory(accessory);
-                    log.info(`External accessory "${accessory.displayName}" added to automatic external Matter bridge`);
-                });
-            }
-            else {
-                // Check if any child Matter bridge from this plugin can handle it
-                let publishedToChildBridge = false;
-                for (const [bridgeId, childBridge] of this.childMatterBridges) {
-                    if (bridgeId.startsWith(`${pluginIdentifier}-`)) {
-                        pluginAccessories.forEach((accessory) => {
-                            childBridge.addAccessory(accessory);
-                            log.info(`External accessory "${accessory.displayName}" added to plugin's Matter bridge`);
-                        });
-                        publishedToChildBridge = true;
-                        break;
-                    }
-                }
-                // External accessories are only published to child Matter bridges, not main bridge
-                if (!publishedToChildBridge) {
-                    pluginAccessories.forEach((accessory) => {
-                        log.debug(`External accessory "${accessory.displayName}" not published to Matter - configure _matter property for Matter support`);
-                    });
-                }
-            }
-        });
+        // External accessories are published via HAP
+        // Plugins should use api.matter to register Matter accessories explicitly
     }
     handleRegisterPlatformAccessories(accessories) {
-        // Route to HAP bridge (default behavior)
+        // Route to HAP bridge
         this.bridgeService.handleRegisterPlatformAccessories(accessories);
-        // Check if we need to also route to Matter bridges
-        for (const accessory of accessories) {
-            const platformKey = `${accessory._associatedPlugin}-${accessory._associatedPlatform}`;
-            const platformConfig = this.platformConfigs.get(platformKey);
-            if (platformConfig) {
-                // Check if platform has child Matter bridge
-                if (platformConfig._matter && typeof platformConfig._matter === 'object') {
-                    const matterIdentifier = `${accessory._associatedPlugin}-${accessory._associatedPlatform}`;
-                    const childMatterBridge = this.childMatterBridges.get(matterIdentifier);
-                    if (childMatterBridge) {
-                        childMatterBridge.addAccessory(accessory).catch((error) => {
-                            log.error(`Failed to add accessory "${accessory.displayName}" to child Matter bridge:`, error);
-                        });
-                    }
-                }
-            }
-        }
     }
     handleUnregisterPlatformAccessories(accessories) {
-        // Route to HAP bridge (default behavior)
+        // Route to HAP bridge
         this.bridgeService.handleUnregisterPlatformAccessories(accessories);
-        // Check if we need to also unregister from Matter bridges
-        for (const accessory of accessories) {
-            const platformKey = `${accessory._associatedPlugin}-${accessory._associatedPlatform}`;
-            const platformConfig = this.platformConfigs.get(platformKey);
-            if (platformConfig) {
-                // Check if platform has child Matter bridge
-                if (platformConfig._matter && typeof platformConfig._matter === 'object') {
-                    const matterIdentifier = `${accessory._associatedPlugin}-${accessory._associatedPlatform}`;
-                    const childMatterBridge = this.childMatterBridges.get(matterIdentifier);
-                    if (childMatterBridge) {
-                        childMatterBridge.removeAccessory(accessory).catch((error) => {
-                            log.error(`Failed to remove accessory "${accessory.displayName}" from child Matter bridge:`, error);
-                        });
-                    }
-                }
-            }
+    }
+    handleRegisterMatterAccessory(accessory) {
+        if (!this.matterServer) {
+            log.warn('Cannot register Matter accessory - Matter server is not running');
+            return;
+        }
+        this.matterServer.registerAccessory(accessory);
+    }
+    handleUnregisterMatterAccessory(uuid) {
+        if (!this.matterServer) {
+            log.warn('Cannot unregister Matter accessory - Matter server is not running');
+            return;
         }
+        this.matterServer.unregisterAccessory(uuid);
+    }
+    handleUpdateMatterAccessoryState(uuid, cluster, attributes) {
+        if (!this.matterServer) {
+            log.warn('Cannot update Matter accessory state - Matter server is not running');
+            return;
+        }
+        this.matterServer.updateAccessoryState(uuid, cluster, attributes);
     }
     static loadConfig() {
         // Look for the configuration file
@@ -386,6 +322,7 @@ export class Server {
         bridge.username = bridge.username || defaultBridge.username;
         bridge.pin = bridge.pin || defaultBridge.pin;
         config.bridge = bridge;
+        // Main bridge username is always required and must be valid
         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.`);
@@ -401,6 +338,48 @@ export class Server {
             config.platforms = [];
         }
         log.info('Loaded config.json with %s accessories and %s platforms.', config.accessories.length, config.platforms.length);
+        // Validate Matter configuration for port conflicts
+        if (config.bridge.matter || config.platforms.some((p) => p._bridge?.matter) || config.accessories.some((a) => a._bridge?.matter)) {
+            // Validate main bridge Matter config
+            if (config.bridge.matter) {
+                // Apply default name before validation if not set
+                if (!config.bridge.matter.name) {
+                    config.bridge.matter.name = config.bridge.name ? `${config.bridge.name} (Matter)` : 'Homebridge Matter Bridge';
+                }
+                const validation = MatterConfigValidator.validate(config.bridge.matter);
+                if (!validation.isValid) {
+                    log.error('Main bridge Matter configuration is invalid. Matter will not be enabled for the main bridge.');
+                    delete config.bridge.matter;
+                }
+            }
+            // Validate all child bridge Matter configs and check for port conflicts
+            const childMatterValidation = MatterConfigValidator.validateAllChildMatterConfigs(config.platforms, config.accessories);
+            if (!childMatterValidation.isValid) {
+                log.error('Some child bridge Matter configurations are invalid. Check the errors above.');
+            }
+            // Additionally, check for conflicts between main bridge Matter port and child bridge ports
+            if (config.bridge.matter?.port) {
+                const mainMatterPort = config.bridge.matter.port;
+                const childMatterPorts = [];
+                for (const platform of config.platforms) {
+                    if (platform._bridge?.matter?.port) {
+                        childMatterPorts.push(platform._bridge.matter.port);
+                    }
+                }
+                for (const accessory of config.accessories) {
+                    if (accessory._bridge?.matter?.port) {
+                        childMatterPorts.push(accessory._bridge.matter.port);
+                    }
+                }
+                if (childMatterPorts.includes(mainMatterPort)) {
+                    log.error(`Main bridge Matter port ${mainMatterPort} conflicts with a child bridge Matter port. Please use unique ports.`);
+                }
+                // Check for conflict with main bridge HAP port
+                if (config.bridge.port && Math.abs(config.bridge.port - mainMatterPort) < 10) {
+                    log.warn(`Main bridge HAP port ${config.bridge.port} and Matter port ${mainMatterPort} are very close. Consider spacing them further apart.`);
+                }
+            }
+        }
         if (config.bridge.advertiser) {
             if (![
                 "bonjour-hap" /* MDNSAdvertiser.BONJOUR */,
@@ -455,63 +434,37 @@ export class Server {
             }
             const logger = Logger.withPrefix(displayName);
             logger('Initializing %s accessory...', accessoryIdentifier);
+            // Handle child bridge (HAP, Matter-only, or HAP+Matter)
             if (accessoryConfig._bridge) {
-                // ensure the username is always uppercase
-                accessoryConfig._bridge.username = accessoryConfig._bridge.username.toUpperCase();
+                // Ensure the username is always uppercase if it exists (HAP bridges only)
+                if (accessoryConfig._bridge.username) {
+                    accessoryConfig._bridge.username = accessoryConfig._bridge.username.toUpperCase();
+                }
+                // Generate unique key for this child bridge
+                const bridgeKey = this.getChildBridgeKey("accessory" /* PluginType.ACCESSORY */, accessoryIdentifier, plugin.getPluginIdentifier(), accessoryConfig._bridge);
                 try {
-                    this.validateChildBridgeConfig("accessory" /* PluginType.ACCESSORY */, accessoryIdentifier, accessoryConfig._bridge);
+                    this.validateChildBridgeConfig("accessory" /* PluginType.ACCESSORY */, accessoryIdentifier, plugin.getPluginIdentifier(), accessoryConfig._bridge, bridgeKey);
                 }
                 catch (error) {
                     log.error(error.message);
                     return;
                 }
                 let childBridge;
-                if (this.childBridges.has(accessoryConfig._bridge.username)) {
-                    childBridge = this.childBridges.get(accessoryConfig._bridge.username);
-                    logger(`Adding to existing child bridge ${accessoryConfig._bridge.username}`);
+                if (this.childBridges.has(bridgeKey)) {
+                    childBridge = this.childBridges.get(bridgeKey);
+                    logger(`Adding to existing child bridge ${bridgeKey}`);
                 }
                 else {
-                    logger(`Initializing child bridge ${accessoryConfig._bridge.username}`);
+                    const bridgeType = accessoryConfig._bridge.matterOnly ? 'Matter-only' : 'HAP';
+                    logger(`Initializing ${bridgeType} child bridge ${bridgeKey}`);
                     childBridge = new ChildBridgeService("accessory" /* PluginType.ACCESSORY */, accessoryIdentifier, plugin, accessoryConfig._bridge, this.config, this.options, this.api, this.ipcService, this.externalPortService);
-                    this.childBridges.set(accessoryConfig._bridge.username, childBridge);
+                    this.childBridges.set(bridgeKey, childBridge);
                 }
                 // add config to child bridge service
                 childBridge.addConfig(accessoryConfig);
-                // If _matter is not defined, we're done - this accessory only uses HAP child bridge
-                if (!accessoryConfig._matter) {
-                    return;
-                }
-            }
-            // Handle child Matter bridge for accessories
-            if (accessoryConfig._matter && typeof accessoryConfig._matter === 'object') {
-                const matterIdentifier = `${plugin.getPluginIdentifier()}-${accessoryIdentifier}`;
-                logger(`Initializing child Matter bridge for accessory ${accessoryIdentifier}`);
-                // Ensure Matter config has proper name
-                // Try to get a human-friendly name from the accessory
-                // Convert CamelCase accessory identifier to spaces
-                const formattedAccessoryId = accessoryIdentifier.replace(/([A-Z])/g, ' $1').trim();
-                // Get plugin name without 'homebridge-' prefix and replace dashes with spaces
-                const pluginDisplayName = plugin.getPluginIdentifier()
-                    .replace('homebridge-', '')
-                    .replace(/-/g, ' ')
-                    .split(' ')
-                    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-                    .join(' ');
-                const defaultName = accessoryConfig.name || formattedAccessoryId || pluginDisplayName;
-                const matterConfig = {
-                    ...accessoryConfig._matter,
-                    name: accessoryConfig._matter.name || defaultName,
-                };
-                const childMatterBridge = new ChildMatterBridgeService("accessory" /* PluginType.ACCESSORY */, plugin, matterConfig, accessoryConfig, this.api, this.externalPortService, this.options, this.ipcService);
-                this.childMatterBridges.set(matterIdentifier, childMatterBridge);
-                // If _bridge is also defined, we're done - accessory uses both protocols
-                if (accessoryConfig._bridge) {
-                    return;
-                }
-            }
-            // If both _bridge and _matter are defined, the accessory is handled by child bridges
-            if (accessoryConfig._bridge || accessoryConfig._matter) {
-                return;
+                // Matter for child bridges is handled inside the forked child process (childBridgeFork.ts)
+                // to maintain isolation - each child process manages its own Matter server
+                return; // Done - child bridge
             }
             const accessoryInstance = new constructor(logger, accessoryConfig, this.api);
             // pass accessoryIdentifier for UUID generation, and optional parameter uuid_base which can be used instead of displayName for UUID generation
@@ -568,59 +521,29 @@ export class Server {
             }
             const logger = Logger.withPrefix(displayName);
             logger('Initializing %s platform...', platformIdentifier);
-            // Store platform config for later routing
-            const platformKey = `${plugin.getPluginIdentifier()}-${platformIdentifier}`;
-            this.platformConfigs.set(platformKey, platformConfig);
-            // Handle child HAP bridge
+            // Handle child bridge (HAP, Matter-only, or HAP+Matter)
             if (platformConfig._bridge) {
-                // ensure the username is always uppercase
-                platformConfig._bridge.username = platformConfig._bridge.username.toUpperCase();
+                // Ensure the username is always uppercase if it exists (HAP bridges only)
+                if (platformConfig._bridge.username) {
+                    platformConfig._bridge.username = platformConfig._bridge.username.toUpperCase();
+                }
+                // Generate unique key for this child bridge
+                const bridgeKey = this.getChildBridgeKey("platform" /* PluginType.PLATFORM */, platformIdentifier, plugin.getPluginIdentifier(), platformConfig._bridge);
                 try {
-                    this.validateChildBridgeConfig("platform" /* PluginType.PLATFORM */, platformIdentifier, platformConfig._bridge);
+                    this.validateChildBridgeConfig("platform" /* PluginType.PLATFORM */, platformIdentifier, plugin.getPluginIdentifier(), platformConfig._bridge, bridgeKey);
                 }
                 catch (error) {
                     log.error(error.message);
                     return;
                 }
-                logger(`Initializing child bridge ${platformConfig._bridge.username}`);
+                const bridgeType = platformConfig._bridge.matterOnly ? 'Matter-only' : 'HAP';
+                logger(`Initializing ${bridgeType} child bridge ${bridgeKey}`);
                 const childBridge = new ChildBridgeService("platform" /* PluginType.PLATFORM */, platformIdentifier, plugin, platformConfig._bridge, this.config, this.options, this.api, this.ipcService, this.externalPortService);
-                this.childBridges.set(platformConfig._bridge.username, childBridge);
+                this.childBridges.set(bridgeKey, childBridge);
                 // add config to child bridge service
                 childBridge.addConfig(platformConfig);
-                // If _matter is not defined, we're done - this platform only uses HAP child bridge
-                if (!platformConfig._matter) {
-                    return;
-                }
-            }
-            // Handle child Matter bridge
-            if (platformConfig._matter && typeof platformConfig._matter === 'object') {
-                const matterIdentifier = `${plugin.getPluginIdentifier()}-${platformIdentifier}`;
-                logger(`Initializing child Matter bridge for ${platformIdentifier}`);
-                // Ensure Matter config has proper name
-                // Try to get a human-friendly name from the platform
-                // Convert CamelCase platform identifier to spaces (e.g., "Ring" stays "Ring", "MySmartHome" becomes "My Smart Home")
-                const formattedPlatformId = platformIdentifier.replace(/([A-Z])/g, ' $1').trim();
-                // Get plugin name without 'homebridge-' prefix and replace dashes with spaces
-                const pluginDisplayName = plugin.getPluginIdentifier()
-                    .replace('homebridge-', '')
-                    .replace(/-/g, ' ')
-                    .split(' ')
-                    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-                    .join(' ');
-                const defaultName = platformConfig.name || formattedPlatformId || pluginDisplayName;
-                const matterConfig = {
-                    ...platformConfig._matter,
-                    name: platformConfig._matter.name || defaultName,
-                };
-                const childMatterBridge = new ChildMatterBridgeService("platform" /* PluginType.PLATFORM */, plugin, matterConfig, platformConfig, this.api, this.externalPortService, this.options, this.ipcService);
-                this.childMatterBridges.set(matterIdentifier, childMatterBridge);
-                // If _bridge is also defined, we're done - platform uses both protocols
-                if (platformConfig._bridge) {
-                    return;
-                }
-            }
-            // If both _bridge and _matter are defined, the platform is handled by child bridges
-            if (platformConfig._bridge || platformConfig._matter) {
+                // Matter for child bridges is handled inside the forked child process (childBridgeFork.ts)
+                // to maintain isolation - each child process manages its own Matter server
                 return;
             }
             const platform = new constructor(logger, platformConfig, this.api);
@@ -637,16 +560,48 @@ export class Server {
         });
         return promises;
     }
+    /**
+     * Generate a unique identifier for a child bridge
+     * - For HAP bridges: returns the uppercase MAC address
+     * - For Matter-only bridges: returns "matter-{plugin}-{identifier}"
+     */
+    getChildBridgeKey(type, identifier, pluginName, bridgeConfig) {
+        if (bridgeConfig.matterOnly) {
+            // Matter-only bridge: generate identifier from plugin and platform/accessory name
+            return `matter-${pluginName}-${identifier}`;
+        }
+        // HAP bridge: use MAC address (already validated and uppercased)
+        return bridgeConfig.username.toUpperCase();
+    }
     /**
      * Validate an external bridge config
      */
-    validateChildBridgeConfig(type, identifier, bridgeConfig) {
+    validateChildBridgeConfig(type, identifier, pluginName, bridgeConfig, bridgeKey) {
+        // Matter-only bridges don't require HAP fields
+        if (bridgeConfig.matterOnly) {
+            if (!bridgeConfig.matter) {
+                throw new Error(`Error loading the ${type} "${identifier}" requested in your config.json - `
+                    + 'Matter-only bridge must have a "matter" configuration block in _bridge.matter.');
+            }
+            // Check for duplicate Matter-only bridges
+            if (this.childBridges.has(bridgeKey)) {
+                throw new Error(`Error loading the ${type} "${identifier}" requested in your config.json - `
+                    + 'A Matter-only bridge with this plugin and platform/accessory combination already exists. Each Matter-only bridge must be unique.');
+            }
+            // Matter-only bridges don't need username/pin validation
+            return;
+        }
+        // HAP bridges (or HAP+Matter bridges) require username and pin
+        if (!bridgeConfig.username) {
+            throw new Error(`Error loading the ${type} "${identifier}" requested in your config.json - `
+                + 'Missing required field "_bridge.username". Set "matterOnly": true if you want a Matter-only bridge.');
+        }
         if (!validMacAddress(bridgeConfig.username)) {
             throw new Error(`Error loading the ${type} "${identifier}" requested in your config.json - `
                 + `not a valid username in _bridge.username: "${bridgeConfig.username}". Must be 6 pairs of colon-separated hexadecimal chars (A-F 0-9), like a MAC address.`);
         }
-        if (this.childBridges.has(bridgeConfig.username)) {
-            const childBridge = this.childBridges.get(bridgeConfig.username);
+        if (this.childBridges.has(bridgeKey)) {
+            const childBridge = this.childBridges.get(bridgeKey);
             if (type === "platform" /* PluginType.PLATFORM */) {
                 // only a single platform can exist on one child bridge
                 throw new Error(`Error loading the ${type} "${identifier}" requested in your config.json - `
@@ -658,6 +613,8 @@ export class Server {
                     + `Duplicate username found in _bridge.username: "${bridgeConfig.username}". You can only group accessories of the same type in a child bridge.`);
             }
         }
+        // Check that child bridge username doesn't conflict with main bridge
+        // Main bridge always has a username (validated in loadConfig)
         if (bridgeConfig.username === this.config.bridge.username.toUpperCase()) {
             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.`);
@@ -674,7 +631,9 @@ export class Server {
             // noinspection SuspiciousTypeOfGuard
             if (typeof username === 'string') {
                 const childBridge = this.childBridges.get(username.toUpperCase());
-                childBridge?.restartChildBridge();
+                if (childBridge) {
+                    childBridge.restartChildBridge();
+                }
             }
         });
         // handle stop child bridge event
@@ -682,7 +641,9 @@ export class Server {
             // noinspection SuspiciousTypeOfGuard
             if (typeof username === 'string') {
                 const childBridge = this.childBridges.get(username.toUpperCase());
-                childBridge?.stopChildBridge();
+                if (childBridge) {
+                    childBridge.stopChildBridge();
+                }
             }
         });
         // handle start child bridge event
@@ -690,110 +651,176 @@ export class Server {
             // noinspection SuspiciousTypeOfGuard
             if (typeof username === 'string') {
                 const childBridge = this.childBridges.get(username.toUpperCase());
-                childBridge?.startChildBridge();
+                if (childBridge) {
+                    childBridge.startChildBridge();
+                }
             }
         });
         this.ipcService.on("childBridgeMetadataRequest" /* IpcIncomingEvent.CHILD_BRIDGE_METADATA_REQUEST */, () => {
-            this.ipcService.sendMessage("childBridgeMetadataResponse" /* IpcOutgoingEvent.CHILD_BRIDGE_METADATA_RESPONSE */, Array.from(this.childBridges.values()).map(x => x.getMetadata()));
+            const childBridgeMetadata = Array.from(this.childBridges.values()).map(x => x.getMetadata());
+            this.ipcService.sendMessage("childBridgeMetadataResponse" /* IpcOutgoingEvent.CHILD_BRIDGE_METADATA_RESPONSE */, childBridgeMetadata);
         });
         // Matter bridge IPC handlers
+        // Main bridge Matter server runs in this process alongside HAP
+        // Child bridge Matter servers run in forked child processes (see childBridgeFork.ts)
         this.ipcService.on("restartMatterBridge" /* IpcIncomingEvent.RESTART_MATTER_BRIDGE */, (matterBridgeId) => {
-            log.info(`Received restart request for Matter bridge: ${matterBridgeId}`);
-            if (typeof matterBridgeId === 'string') {
-                const matterBridge = this.childMatterBridges.get(matterBridgeId);
-                if (matterBridge) {
-                    log.info(`Restarting Matter bridge: ${matterBridgeId}`);
-                    matterBridge.restartChildBridge();
+            if (matterBridgeId === 'main-bridge') {
+                // Main Matter bridge runs in the main process, so restart the entire Homebridge instance
+                log.info('Restarting Homebridge (Matter bridge restart requested)...');
+                process.kill(process.pid, 'SIGTERM');
+            }
+            else {
+                // Handle child bridge using cache for efficient lookup
+                const childBridge = this.matterBridgeCache.get(matterBridgeId);
+                if (childBridge) {
+                    childBridge.restartChildBridge();
                 }
                 else {
-                    log.warn(`Matter bridge not found: ${matterBridgeId}`);
-                    log.debug('Available Matter bridges:', Array.from(this.childMatterBridges.keys()));
+                    log.warn(`Child bridge ${matterBridgeId} not found for Matter restart`);
                 }
             }
         });
         this.ipcService.on("stopMatterBridge" /* IpcIncomingEvent.STOP_MATTER_BRIDGE */, (matterBridgeId) => {
-            log.info(`Received stop request for Matter bridge: ${matterBridgeId}`);
-            if (typeof matterBridgeId === 'string') {
-                const matterBridge = this.childMatterBridges.get(matterBridgeId);
-                if (matterBridge) {
-                    log.info(`Stopping Matter bridge: ${matterBridgeId}`);
-                    matterBridge.stopChildBridge();
+            if (matterBridgeId === 'main-bridge') {
+                log.warn('Stop requested for main Matter bridge - this is not supported');
+                log.info('The main Matter bridge runs alongside the HAP bridge and cannot be stopped independently');
+            }
+            else {
+                // Handle child bridge using cache for efficient lookup
+                const childBridge = this.matterBridgeCache.get(matterBridgeId);
+                if (childBridge) {
+                    childBridge.stopChildBridge();
                 }
                 else {
-                    log.warn(`Matter bridge not found: ${matterBridgeId}`);
+                    log.warn(`Child bridge ${matterBridgeId} not found for Matter stop`);
                 }
             }
         });
         this.ipcService.on("startMatterBridge" /* IpcIncomingEvent.START_MATTER_BRIDGE */, (matterBridgeId) => {
-            log.info(`Received start request for Matter bridge: ${matterBridgeId}`);
-            if (typeof matterBridgeId === 'string') {
-                const matterBridge = this.childMatterBridges.get(matterBridgeId);
-                if (matterBridge) {
-                    log.info(`Starting Matter bridge: ${matterBridgeId}`);
-                    matterBridge.startChildBridge();
+            if (matterBridgeId === 'main-bridge') {
+                log.warn('Start requested for main Matter bridge - this is not supported');
+                log.info('The main Matter bridge starts automatically with Homebridge');
+            }
+            else {
+                // Handle child bridge using cache for efficient lookup
+                const childBridge = this.matterBridgeCache.get(matterBridgeId);
+                if (childBridge) {
+                    childBridge.startChildBridge();
                 }
                 else {
-                    log.warn(`Matter bridge not found: ${matterBridgeId}`);
+                    log.warn(`Child bridge ${matterBridgeId} not found for Matter start`);
                 }
             }
         });
         this.ipcService.on("matterBridgeMetadataRequest" /* IpcIncomingEvent.MATTER_BRIDGE_METADATA_REQUEST */, () => {
-            // Return all child Matter bridge metadata
-            this.ipcService.sendMessage("matterBridgeMetadataResponse" /* IpcOutgoingEvent.MATTER_BRIDGE_METADATA_RESPONSE */, Array.from(this.childMatterBridges.values()).map(x => x.getMetadata()));
+            const matterBridges = [];
+            // Add main bridge Matter metadata if enabled
+            if (this.matterServer && this.matterServer.isServerRunning()) {
+                const commissioningInfo = this.matterServer.getCommissioningInfo();
+                matterBridges.push({
+                    type: 'matter',
+                    status: 'ok',
+                    port: this.config.bridge.matter?.port || 5540,
+                    setupUri: commissioningInfo.qrCode,
+                    pin: commissioningInfo.manualPairingCode,
+                    serialNumber: commissioningInfo.serialNumber,
+                    name: this.config.bridge.name,
+                    plugin: 'main-bridge',
+                    identifier: 'main-bridge',
+                    deviceCount: this.matterServer.getAccessories().length,
+                    commissioned: commissioningInfo.commissioned,
+                    matterEnabled: true,
+                });
+            }
+            // Add child bridge Matter metadata
+            for (const childBridge of this.childBridges.values()) {
+                const matterInfo = childBridge.getCommissioningInfo();
+                const matterConfig = childBridge.getMatterConfig();
+                if (matterInfo && matterConfig) {
+                    const metadata = childBridge.getMetadata();
+                    // Use plugin-identifier format to match storage
+                    const childIdentifier = `${metadata.plugin}-${childBridge.identifier}`;
+                    // Populate cache for efficient lookups
+                    this.matterBridgeCache.set(childIdentifier, childBridge);
+                    matterBridges.push({
+                        type: 'matter',
+                        status: metadata.status === 'ok' ? 'ok' : 'pending',
+                        port: matterConfig.port,
+                        setupUri: matterInfo.qrCode,
+                        pin: matterInfo.manualPairingCode,
+                        serialNumber: matterInfo.serialNumber,
+                        name: matterConfig.name || metadata.name,
+                        plugin: metadata.plugin,
+                        identifier: childIdentifier,
+                        commissioned: matterInfo.commissioned,
+                        username: metadata.username,
+                        matterEnabled: true,
+                    });
+                }
+            }
+            this.ipcService.sendMessage("matterBridgeMetadataResponse" /* IpcOutgoingEvent.MATTER_BRIDGE_METADATA_RESPONSE */, matterBridges);
         });
         this.ipcService.on("matterAccessoriesRequest" /* IpcIncomingEvent.MATTER_ACCESSORIES_REQUEST */, () => {
-            // Collect Matter accessories from all child bridges
+            // Return Matter accessories from all bridges
             const allMatterAccessories = {
                 children: {},
             };
-            // Add child bridge accessories
-            for (const [bridgeId, childBridge] of this.childMatterBridges) {
-                allMatterAccessories.children[bridgeId] = childBridge.getMatterAccessories ? childBridge.getMatterAccessories() : [];
+            // Add main bridge accessories
+            if (this.matterServer) {
+                allMatterAccessories.children['main-bridge'] = this.matterServer.getAccessories();
             }
+            // Child bridge accessories are managed by child processes
             this.ipcService.sendMessage("matterAccessoriesResponse" /* IpcOutgoingEvent.MATTER_ACCESSORIES_RESPONSE */, allMatterAccessories);
         });
-        // Handle new Matter IPC events
-        this.ipcService.on("toggleMatterDevice" /* IpcIncomingEvent.TOGGLE_MATTER_DEVICE */, (data) => {
-            if (data && data.uuid) {
-                // This would toggle Matter for a specific device
-                // Implementation depends on how devices are managed
-                log.debug(`Toggle Matter for device ${data.uuid}: ${data.enabled}`);
-                // Send status update
-                this.ipcService.sendMessage("matterDeviceStatusUpdate" /* IpcOutgoingEvent.MATTER_DEVICE_STATUS_UPDATE */, {
-                    uuid: data.uuid,
-                    matterEnabled: data.enabled,
-                });
-            }
-        });
         this.ipcService.on("matterCommissioningInfoRequest" /* IpcIncomingEvent.MATTER_COMMISSIONING_INFO_REQUEST */, (matterBridgeId) => {
-            let commissioningInfo = null;
-            // Get child bridge commissioning info
-            const childBridge = this.childMatterBridges.get(matterBridgeId);
-            if (childBridge && childBridge.getCommissioningInfo) {
-                commissioningInfo = childBridge.getCommissioningInfo();
+            let rawInfo = { commissioned: false };
+            // Handle main bridge
+            if (matterBridgeId === 'main-bridge') {
+                if (this.matterServer && this.matterServer.isServerRunning()) {
+                    rawInfo = this.matterServer.getCommissioningInfo();
+                }
+                else {
+                    log.debug(`[Matter] Server not available when commissioning info requested for: ${matterBridgeId}`);
+                }
+            }
+            else {
+                // Handle child bridge using plugin-identifier format (e.g., homebridge-virtual-accessories-VirtualAccessoriesForHomebridge)
+                // Use cache for efficient O(1) lookup
+                const childBridge = this.matterBridgeCache.get(matterBridgeId);
+                if (childBridge) {
+                    rawInfo = childBridge.getCommissioningInfo() || { commissioned: false };
+                }
+                else {
+                    log.debug(`[Matter] Child bridge ${matterBridgeId} not found when commissioning info requested`);
+                }
             }
-            this.ipcService.sendMessage("matterCommissioningInfoResponse" /* IpcOutgoingEvent.MATTER_COMMISSIONING_INFO_RESPONSE */, commissioningInfo || { commissioned: false });
+            // Transform property names to match MatterCommissioningInfo interface
+            const commissioningInfo = {
+                commissioned: rawInfo.commissioned || false,
+                pin: rawInfo.manualPairingCode, // Map manualPairingCode -> pin
+                setupUri: rawInfo.qrCode, // Map qrCode -> setupUri
+                serialNumber: rawInfo.serialNumber,
+            };
+            this.ipcService.sendMessage("matterCommissioningInfoResponse" /* IpcOutgoingEvent.MATTER_COMMISSIONING_INFO_RESPONSE */, commissioningInfo);
         });
     }
     printSetupInfo(pin) {
-        /* eslint-disable no-console */
-        console.log('Setup Payload:');
-        console.log(this.bridgeService.bridge.setupURI());
+        log.info('Setup Payload:');
+        log.info(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:');
+            log.info('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:');
+            log.info('Or enter this code with your HomeKit app on your iOS device to pair with Homebridge:');
         }
         else {
-            console.log('Enter this code with your HomeKit app on your iOS device to pair with Homebridge:');
+            log.info('Enter this code with your HomeKit app on your iOS device to pair with Homebridge:');
         }
-        console.log(chalk.black.bgWhite('                       '));
-        console.log(chalk.black.bgWhite('    ┌────────────┐     '));
-        console.log(chalk.black.bgWhite(`    │ ${pin} │     `));
-        console.log(chalk.black.bgWhite('    └────────────┘     '));
-        console.log(chalk.black.bgWhite('                       '));
-        /* eslint-enable no-console */
+        log.info(chalk.black.bgWhite('                       '));
+        log.info(chalk.black.bgWhite('    ┌────────────┐     '));
+        log.info(chalk.black.bgWhite(`    │ ${pin} │     `));
+        log.info(chalk.black.bgWhite('    └────────────┘     '));
+        log.info(chalk.black.bgWhite('                       '));
     }
 }
 //# sourceMappingURL=server.js.map