@switchbot/homebridge-switchbot 5.0.0-beta.2 → 5.0.0-beta.21

package/src/irdevice/irdevice.ts

@@ -276,69 +276,108 @@ export abstract class irdeviceBase {
   /**
    * Logging for Device
    */
-  async infoLog(...log: any[]): Promise<void> {
-    if (await this.enablingDeviceLogging()) {
-      this.log.info(`${this.device.remoteType}: ${this.accessory.displayName}`, String(...log))
+  infoLog(...log: any[]): void {
+    if (!this.enablingDeviceLogging()) {
+      return
     }
+    // Delegate to a single helper that prefers platform-provided loggers.
+    this.logWith('info', `${this.device.remoteType}: ${this.accessory.displayName}`, undefined, String(...log))
   }
 
-  async successLog(...log: any[]): Promise<void> {
-    if (await this.enablingDeviceLogging()) {
-      this.log.success(`${this.device.remoteType}: ${this.accessory.displayName}`, String(...log))
+  successLog(...log: any[]): void {
+    if (!this.enablingDeviceLogging()) {
+      return
     }
+    this.logWith('success', `${this.device.remoteType}: ${this.accessory.displayName}`, undefined, String(...log))
   }
 
-  async debugSuccessLog(...log: any[]): Promise<void> {
-    if (await this.enablingDeviceLogging()) {
-      if (await this.loggingIsDebug()) {
-        this.log.success(`[DEBUG] ${this.device.remoteType}: ${this.accessory.displayName}`, String(...log))
-      }
+  debugSuccessLog(...log: any[]): void {
+    if (!this.enablingDeviceLogging()) {
+      return
+    }
+    if (!this.loggingIsDebug()) {
+      return
     }
+    this.logWith('success', `[DEBUG] ${this.device.remoteType}: ${this.accessory.displayName}`, 'debugSuccessLog', String(...log))
   }
 
-  async warnLog(...log: any[]): Promise<void> {
-    if (await this.enablingDeviceLogging()) {
-      this.log.warn(`${this.device.remoteType}: ${this.accessory.displayName}`, String(...log))
+  warnLog(...log: any[]): void {
+    if (!this.enablingDeviceLogging()) {
+      return
     }
+    this.logWith('warn', `${this.device.remoteType}: ${this.accessory.displayName}`, undefined, String(...log))
   }
 
-  async debugWarnLog(...log: any[]): Promise<void> {
-    if (await this.enablingDeviceLogging()) {
-      if (await this.loggingIsDebug()) {
-        this.log.warn(`[DEBUG] ${this.device.remoteType}: ${this.accessory.displayName}`, String(...log))
-      }
+  debugWarnLog(...log: any[]): void {
+    if (!this.enablingDeviceLogging() || !this.loggingIsDebug()) {
+      return
     }
+    this.logWith('warn', `[DEBUG] ${this.device.remoteType}: ${this.accessory.displayName}`, 'debugWarnLog', String(...log))
   }
 
-  async errorLog(...log: any[]): Promise<void> {
-    if (await this.enablingDeviceLogging()) {
-      this.log.error(`${this.device.remoteType}: ${this.accessory.displayName}`, String(...log))
+  errorLog(...log: any[]): void {
+    if (!this.enablingDeviceLogging()) {
+      return
     }
+    this.logWith('error', `${this.device.remoteType}: ${this.accessory.displayName}`, undefined, String(...log))
   }
 
-  async debugErrorLog(...log: any[]): Promise<void> {
-    if (await this.enablingDeviceLogging()) {
-      if (await this.loggingIsDebug()) {
-        this.log.error(`[DEBUG] ${this.device.remoteType}: ${this.accessory.displayName}`, String(...log))
-      }
+  debugErrorLog(...log: any[]): void {
+    if (!this.enablingDeviceLogging() || !this.loggingIsDebug()) {
+      return
     }
+    this.logWith('error', `[DEBUG] ${this.device.remoteType}: ${this.accessory.displayName}`, 'debugErrorLog', String(...log))
   }
 
-  async debugLog(...log: any[]): Promise<void> {
-    if (await this.enablingDeviceLogging()) {
-      if (this.deviceLogging === 'debug') {
-        this.log.info(`[DEBUG] ${this.device.remoteType}: ${this.accessory.displayName}`, String(...log))
-      } else if (this.deviceLogging === 'debugMode') {
-        this.log.debug(`${this.device.remoteType}: ${this.accessory.displayName}`, String(...log))
+  debugLog(...log: any[]): void {
+    if (!this.enablingDeviceLogging()) {
+      return
+    }
+    if (this.deviceLogging === 'debug') {
+      this.logWith('debug', `[DEBUG] ${this.device.remoteType}: ${this.accessory.displayName}`, 'debugLog', String(...log))
+    } else if (this.deviceLogging === 'debugMode') {
+      this.logWith('debug', `${this.device.remoteType}: ${this.accessory.displayName}`, 'debugLog', String(...log))
+    }
+  }
+
+  // Generic platform/local logger delegate
+  protected logWith(level: string, message: string, platformMethodName?: string, payload?: string): void {
+    const method = platformMethodName ?? `${level}Log`
+    const pFn = (this.platform as any)?.[method]
+    if (typeof pFn === 'function') {
+      try {
+        if (payload !== undefined) {
+          pFn(message, payload)
+        } else {
+          pFn(message)
+        }
+        return
+      } catch (_err) {
+        // fallthrough to local logger
+      }
+    }
+    const map: Record<string, string> = {
+      info: 'info',
+      success: 'success',
+      debug: 'debug',
+      warn: 'warn',
+      error: 'error',
+    }
+    const local = (this.log as any)[map[level] ?? level]
+    if (typeof local === 'function') {
+      if (payload !== undefined) {
+        local.call(this.log, message, payload)
+      } else {
+        local.call(this.log, message)
       }
     }
   }
 
-  async loggingIsDebug(): Promise<boolean> {
+  loggingIsDebug(): boolean {
     return this.deviceLogging === 'debugMode' || this.deviceLogging === 'debug'
   }
 
-  async enablingDeviceLogging(): Promise<boolean> {
+  enablingDeviceLogging(): boolean {
     return this.deviceLogging === 'debugMode' || this.deviceLogging === 'debug' || this.deviceLogging === 'standard'
   }
 }

package/src/platform-hap.ts

@@ -55,7 +55,7 @@ import { TV } from './irdevice/tv.js'
 import { VacuumCleaner } from './irdevice/vacuumcleaner.js'
 import { WaterHeater } from './irdevice/waterheater.js'
 import { PLATFORM_NAME, PLUGIN_NAME } from './settings.js'
-import { cleanDeviceConfig, formatDeviceIdAsMac, isBlindTiltDevice, isCurtainDevice, safeStringify, sleep } from './utils.js'
+import { cleanDeviceConfig, createPlatformLogger, formatDeviceIdAsMac, isBlindTiltDevice, isCurtainDevice, safeStringify, sleep } from './utils.js'
 
 /**
  * HomebridgePlatform
@@ -68,6 +68,18 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
   public readonly api: API
   public readonly log: Logging
 
+  // Logging helper functions (attached from utils.createPlatformLogger in constructor)
+  infoLog!: (...log: any[]) => Promise<void>
+  successLog!: (...log: any[]) => Promise<void>
+  debugSuccessLog!: (...log: any[]) => Promise<void>
+  warnLog!: (...log: any[]) => Promise<void>
+  debugWarnLog!: (...log: any[]) => Promise<void>
+  errorLog!: (...log: any[]) => Promise<void>
+  debugErrorLog!: (...log: any[]) => Promise<void>
+  debugLog!: (...log: any[]) => Promise<void>
+  loggingIsDebug!: () => Promise<boolean>
+  enablingPlatformLogging!: () => Promise<boolean>
+
   // Configuration properties
   platformConfig!: SwitchBotPlatformConfig
   platformLogging!: options['logging']
@@ -104,9 +116,22 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
     this.api = api
     this.log = log
 
+    // Attach shared platform logging helpers (moved to utils for reuse)
+    const _pl = createPlatformLogger(async () => this.platformLogging, this.log)
+    this.infoLog = _pl.infoLog
+    this.successLog = _pl.successLog
+    this.debugSuccessLog = _pl.debugSuccessLog
+    this.warnLog = _pl.warnLog
+    this.debugWarnLog = _pl.debugWarnLog
+    this.errorLog = _pl.errorLog
+    this.debugErrorLog = _pl.debugErrorLog
+    this.debugLog = _pl.debugLog
+    this.loggingIsDebug = _pl.loggingIsDebug
+    this.enablingPlatformLogging = _pl.enablingPlatformLogging
+
     // only load if configured
     if (!config) {
-      this.log.error('No configuration found for the plugin, please check your config.')
+      this.errorLog('No configuration found for the plugin, please check your config.')
       return
     }
 
@@ -205,7 +230,18 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
       this.debugLog('Executed didFinishLaunching callback')
       // run the method to discover / register your devices as accessories
       try {
-        await this.discoverDevices()
+        // Does the user have a version of Homebridge that is compatible with matter?
+        if (!this.api.isMatterAvailable?.()) {
+          this.debugLog(`Matter is not available in this version of Homebridge. Please update Homebridge to use this plugin, ${this.api.isMatterAvailable?.() ? '' : ' (Matter is not available in this version of Homebridge)'}`)
+        }
+        if (!this.api.isMatterEnabled?.()) {
+          this.debugLog(`Matter is not enabled in Homebridge. Please enable Matter in the Homebridge settings to use this plugin, ${this.api.isMatterEnabled?.() ? '' : ' (Matter is not enabled in Homebridge)'}`)
+        }
+        if (!this.api.isMatterAvailable?.() && !this.api.isMatterEnabled?.()) {
+          await this.discoverDevices()
+        } else {
+          this.infoLog('Matter is enabled in Homebridge. SwitchBot Matter devices will be handled by the Matter platform.')
+        }
       } catch (e: any) {
         this.errorLog(`Failed to Discover, Error Message: ${e.message ?? e}, Submit Bugs Here: ` + 'https://tinyurl.com/SwitchBotBug')
         this.debugErrorLog(`Failed to Discover, Error: ${e.message ?? e}`)
@@ -2913,74 +2949,4 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
       return value
     }
   }
-
-  /**
-   * If device level logging is turned on, log to log.warn
-   * Otherwise send debug logs to log.debug
-   */
-  async infoLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      this.log.info(String(...log))
-    }
-  }
-
-  async successLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      this.log.success(String(...log))
-    }
-  }
-
-  async debugSuccessLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      if (await this.loggingIsDebug()) {
-        this.log.success('[DEBUG]', String(...log))
-      }
-    }
-  }
-
-  async warnLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      this.log.warn(String(...log))
-    }
-  }
-
-  async debugWarnLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      if (await this.loggingIsDebug()) {
-        this.log.warn('[DEBUG]', String(...log))
-      }
-    }
-  }
-
-  async errorLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      this.log.error(String(...log))
-    }
-  }
-
-  async debugErrorLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      if (await this.loggingIsDebug()) {
-        this.log.error('[DEBUG]', String(...log))
-      }
-    }
-  }
-
-  async debugLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      if (this.platformLogging === 'debug') {
-        this.log.info('[DEBUG]', String(...log))
-      } else if (this.platformLogging === 'debugMode') {
-        this.log.debug(String(...log))
-      }
-    }
-  }
-
-  async loggingIsDebug(): Promise<boolean> {
-    return this.platformLogging === 'debugMode' || this.platformLogging === 'debug'
-  }
-
-  async enablingPlatformLogging(): Promise<boolean> {
-    return this.platformLogging === 'debugMode' || this.platformLogging === 'debug' || this.platformLogging === 'standard'
-  }
 }

package/src/platform-matter.cleanup.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from './platform-matter.js'
+import { formatDeviceIdAsMac } from './utils.js'
+
+describe('platform-matter lifecycle cleanup', () => {
+  it('clearDeviceResources removes timers, instances and BLE handler entries', async () => {
+    // Setup stubbed API and logs
+    const handlers: Record<string, (...args: any[]) => any> = {}
+    const api: any = {
+      matter: {
+        uuid: { generate: (s: string) => `uuid-${s}` },
+        registerPlatformAccessories: vi.fn(),
+        unregisterPlatformAccessories: vi.fn(),
+        clusterNames: { OnOff: 'OnOff' },
+      },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: (ev: string, fn: (...args: any[]) => any) => { handlers[ev] = fn },
+      _handlers: handlers,
+    }
+
+    const log = { info: vi.fn(), debug: vi.fn(), warn: vi.fn(), error: vi.fn(), success: vi.fn() }
+
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    // Insert a fake timer, accessory instance, and BLE handler
+    const deviceId = 'AA:BB:CC:11:22:33'
+    const nid = (platform as any).normalizeDeviceId(deviceId)
+
+    const timer = setInterval(() => {}, 100000)
+    ;(platform as any).refreshTimers.set(nid, timer)
+    ;(platform as any).accessoryInstances.set(nid, { dummy: true })
+    ;(platform as any).bleEventHandler[deviceId.toLowerCase()] = () => {}
+
+    // Ensure they exist prior
+    expect((platform as any).refreshTimers.get(nid)).toBeDefined()
+    expect((platform as any).accessoryInstances.get(nid)).toBeDefined()
+    expect((platform as any).bleEventHandler[deviceId.toLowerCase()]).toBeDefined()
+
+    // Call the private helper
+    ;(platform as any).clearDeviceResources(deviceId)
+
+    // Now they should be removed
+    expect((platform as any).refreshTimers.get(nid)).toBeUndefined()
+    expect((platform as any).accessoryInstances.get(nid)).toBeUndefined()
+    expect((platform as any).bleEventHandler[deviceId.toLowerCase()]).toBeUndefined()
+  })
+
+  it('shutdown handler clears all timers and handlers when invoked', async () => {
+    // Setup stubbed API and logs
+    const handlers: Record<string, (...args: any[]) => any> = {}
+    const api: any = {
+      matter: {
+        uuid: { generate: (s: string) => `uuid-${s}` },
+        registerPlatformAccessories: vi.fn(),
+        unregisterPlatformAccessories: vi.fn(),
+        clusterNames: { OnOff: 'OnOff' },
+      },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: (ev: string, fn: (...args: any[]) => any) => { handlers[ev] = fn },
+      _handlers: handlers,
+    }
+
+    const log = { info: vi.fn(), debug: vi.fn(), warn: vi.fn(), error: vi.fn(), success: vi.fn() }
+
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    // Add two timers to the platform (using normalized ids)
+    const ids = ['devA', 'devB']
+    for (const id of ids) {
+      const nid = (platform as any).normalizeDeviceId(id)
+      const t = setInterval(() => {}, 100000)
+      ;(platform as any).refreshTimers.set(nid, t)
+      ;(platform as any).accessoryInstances.set(nid, { dummy: true })
+      try {
+        const mac = formatDeviceIdAsMac(id).toLowerCase()
+        ;(platform as any).bleEventHandler[mac] = () => {}
+      } catch {
+        // ignore formatting errors in this test
+      }
+    }
+
+    // Invoke didFinishLaunching to ensure the platform registered its shutdown handler
+    await Promise.resolve(api._handlers.didFinishLaunching?.())
+
+    // Shutdown handler should now be registered on api._handlers.shutdown
+    expect(typeof api._handlers.shutdown).toBe('function')
+
+    // Call the shutdown handler
+    await Promise.resolve(api._handlers.shutdown())
+
+    // All refresh timers should be cleared
+    for (const id of ids) {
+      const nid = (platform as any).normalizeDeviceId(id)
+      expect((platform as any).refreshTimers.get(nid)).toBeUndefined()
+      expect((platform as any).accessoryInstances.get(nid)).toBeUndefined()
+    }
+  })
+})

package/src/platform-matter.mapping.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from './platform-matter.js'
+
+describe('platform-matter mapping helper', () => {
+  it('prefers accessory instance update methods for battery and falls back to api.matter.updateAccessoryState', async () => {
+    const updateAccessoryState = vi.fn()
+    const api: any = {
+      matter: {
+        uuid: { generate: (s: string) => `uuid-${s}` },
+        updateAccessoryState,
+        clusterNames: { OnOff: 'OnOff', LevelControl: 'LevelControl', ColorControl: 'ColorControl', PowerSource: 'powerSource' },
+      },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: () => {},
+    }
+
+    const log: any = { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn() }
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    // Create a fake accessory instance with updateBatteryPercentage
+    const deviceId = 'DEV123'
+    const nid = (platform as any).normalizeDeviceId(deviceId)
+    const fakeInstance = { updateBatteryPercentage: vi.fn() }
+    ;(platform as any).accessoryInstances.set(nid, fakeInstance)
+
+    // Call the private helper with different battery field names
+    await (platform as any).applyStatusToAccessory('uuid-test', { deviceId } as any, { batteryPercentage: 55 })
+    expect(fakeInstance.updateBatteryPercentage).toHaveBeenCalled()
+
+    // Remove instance to force fallback
+    ;(platform as any).accessoryInstances.delete(nid)
+    await (platform as any).applyStatusToAccessory('uuid-test', { deviceId } as any, { battery: 30 })
+    expect(updateAccessoryState).toHaveBeenCalled()
+  })
+
+  it('handles temperature and humidity synonyms', async () => {
+    const updateAccessoryState = vi.fn()
+    const api: any = {
+      matter: {
+        uuid: { generate: (s: string) => `uuid-${s}` },
+        updateAccessoryState,
+        clusterNames: {},
+      },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: () => {},
+    }
+
+    const log: any = { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn() }
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    const deviceId = 'DEV-TEMP'
+    await (platform as any).applyStatusToAccessory('uuid-temp', { deviceId } as any, { temp: 21.5, humid: 48 })
+
+    // Expect updateAccessoryState to have been called for temperature and humidity
+    expect(updateAccessoryState).toHaveBeenCalled()
+  })
+})

package/src/platform-matter.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from './platform-matter.js'
+import { PLATFORM_NAME, PLUGIN_NAME } from './settings.js'
+
+describe('platform-matter discovered devices', () => {
+  it('uses discovered devices and registers them (platform + robotic)', async () => {
+    const mockRegister = vi.fn()
+
+    const api: any = {
+      matter: {
+        uuid: { generate: (s: string) => `uuid-${s}` },
+        registerPlatformAccessories: mockRegister,
+        clusterNames: { OnOff: 'OnOff', LevelControl: 'LevelControl', ColorControl: 'ColorControl' },
+        deviceTypes: { RoboticVacuumCleaner: 'rvc' },
+      },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: () => {},
+    }
+
+    const log: any = {
+      info: vi.fn(),
+      warn: vi.fn(),
+      debug: vi.fn(),
+      error: vi.fn(),
+    }
+
+    const config: any = {}
+
+    const platform = new SwitchBotMatterPlatform(log, config, api)
+
+    // Provide discovered devices
+    ;(platform as any).discoveredDevices = [
+      { deviceId: 'dev1', deviceName: 'Lamp', deviceType: 'Plug' },
+      { deviceId: 'vac1', deviceName: 'Vac', deviceType: 'K10+' },
+    ] as any
+
+    // Stub accessory creation to avoid instantiating full device classes
+    ;(platform as any).createAccessoryFromDevice = async (dev: any) => ({ displayName: dev.deviceName, uuid: api.matter.uuid.generate(dev.deviceId) } as any)
+
+    await (platform as any).registerMatterAccessories()
+
+    // Ensure registerPlatformAccessories was called at least once
+    expect(mockRegister).toHaveBeenCalled()
+
+    // Sum total accessories registered across all calls
+    const totalRegistered = mockRegister.mock.calls.reduce((sum: number, call: any) => sum + ((call[2] && call[2].length) || 0), 0)
+    expect(totalRegistered).toBe(2)
+
+    // Verify PLUGIN_NAME and PLATFORM_NAME were used in the calls
+    for (const call of mockRegister.mock.calls) {
+      expect(call[0]).toBe(PLUGIN_NAME)
+      expect(call[1]).toBe(PLATFORM_NAME)
+    }
+  })
+
+  it('applies per-device config overrides when deviceId matches discovered device', async () => {
+    const mockRegister = vi.fn()
+
+    const api: any = {
+      matter: {
+        uuid: { generate: (s: string) => `uuid-${s}` },
+        registerPlatformAccessories: mockRegister,
+        clusterNames: { OnOff: 'OnOff', LevelControl: 'LevelControl', ColorControl: 'ColorControl' },
+        deviceTypes: { RoboticVacuumCleaner: 'rvc' },
+      },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: () => {},
+    }
+
+    const log: any = { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn() }
+
+    const config: any = {
+      options: {
+        devices: [{ deviceId: 'dev1', configDeviceName: 'Configured Lamp', logging: 'debug' }],
+      },
+    }
+
+    const platform = new SwitchBotMatterPlatform(log, config, api)
+
+    ;(platform as any).discoveredDevices = [{ deviceId: 'dev1', deviceName: 'Lamp', deviceType: 'Plug' }] as any
+
+    const seen: any[] = []
+    ;(platform as any).createAccessoryFromDevice = async (dev: any) => {
+      seen.push(dev)
+      return {
+        displayName: dev.deviceName ?? dev.configDeviceName,
+        uuid: api.matter.uuid.generate(dev.deviceId),
+      } as any
+    }
+
+    await (platform as any).registerMatterAccessories()
+
+    // createAccessoryFromDevice should have been called once with merged config
+    expect(seen.length).toBe(1)
+    expect(seen[0].deviceId).toBe('dev1')
+    // per-device config values should be present on the merged device
+    expect(seen[0].configDeviceName).toBe('Configured Lamp')
+    expect(seen[0].logging).toBe('debug')
+  })
+
+  it('ignores config-only devices by default but includes them when allowConfigOnlyDevices=true', async () => {
+    const mockRegister = vi.fn()
+
+    const api: any = {
+      matter: {
+        uuid: { generate: (s: string) => `uuid-${s}` },
+        registerPlatformAccessories: mockRegister,
+        clusterNames: { OnOff: 'OnOff', LevelControl: 'LevelControl', ColorControl: 'ColorControl' },
+        deviceTypes: { RoboticVacuumCleaner: 'rvc' },
+      },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: () => {},
+    }
+
+    const log: any = { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn() }
+
+    // config-only device (cfg1) and one discovered device (dev1)
+    const cfgOnly = { deviceId: 'cfg1', configDeviceName: 'OnlyInConfig', deviceType: 'Plug' }
+    const configDefault: any = { options: { devices: [cfgOnly] } }
+
+    const platformDefault = new SwitchBotMatterPlatform(log, configDefault, api)
+    ;(platformDefault as any).discoveredDevices = [{ deviceId: 'dev1', deviceName: 'Lamp', deviceType: 'Plug' }] as any
+    const seenDefault: any[] = []
+    ;(platformDefault as any).createAccessoryFromDevice = async (dev: any) => {
+      seenDefault.push(dev)
+      return {
+        displayName: dev.deviceName ?? dev.configDeviceName,
+        uuid: api.matter.uuid.generate(dev.deviceId),
+      } as any
+    }
+    await (platformDefault as any).registerMatterAccessories()
+    // Should only see discovered device (cfg1 ignored)
+    expect(seenDefault.find((d: any) => d.deviceId === 'cfg1')).toBeUndefined()
+
+    // Now opt-in to include config-only devices
+    const configOptIn: any = { options: { devices: [cfgOnly], allowConfigOnlyDevices: true } }
+    const platformOptIn = new SwitchBotMatterPlatform(log, configOptIn, api)
+    ;(platformOptIn as any).discoveredDevices = [{ deviceId: 'dev1', deviceName: 'Lamp', deviceType: 'Plug' }] as any
+    const seenOptIn: any[] = []
+    ;(platformOptIn as any).createAccessoryFromDevice = async (dev: any) => {
+      seenOptIn.push(dev)
+      return {
+        displayName: dev.deviceName ?? dev.configDeviceName,
+        uuid: api.matter.uuid.generate(dev.deviceId),
+      } as any
+    }
+    await (platformOptIn as any).registerMatterAccessories()
+    // Should include the config-only device now
+    expect(seenOptIn.find((d: any) => d.deviceId === 'cfg1')).toBeDefined()
+  })
+})