@switchbot/homebridge-switchbot 5.0.0-beta.4 → 5.0.0-beta.40

package/src/settings.ts

@@ -32,10 +32,18 @@ interface credentials {
 
 export interface options {
   devices?: devicesConfig[]
-  deviceConfig?: { [deviceType: string]: devicesConfig }
   irdevices?: irDevicesConfig[]
-  irdeviceConfig?: { [remoteType: string]: irDevicesConfig }
   allowInvalidCharacters?: boolean
+  // When true, devices declared in config.options.devices that are not
+  // discovered via the SwitchBot OpenAPI will still be included (config-only
+  // devices). Default: false.
+  allowConfigOnlyDevices?: boolean
+  /**
+   * When true, previously-registered accessories for devices that are no
+   * longer discovered or configured will be kept on the bridge. Default: false.
+   * When false (default), stale accessories are removed automatically.
+   */
+  keepStaleAccessories?: boolean
   mqttURL?: string
   mqttOptions?: IClientOptions
   mqttPubOptions?: IClientOptions
@@ -51,6 +59,29 @@ export interface options {
   updateRate?: number
   pushRate?: number
   logging?: string
+  /**
+   * Maximum number of SwitchBot OpenAPI requests allowed per day.
+   * Defaults to 10,000 if not specified.
+   */
+  dailyApiLimit?: number
+  /**
+   * Number of daily API requests reserved for user-initiated commands.
+   * When remaining budget falls below this reserve, background polling and discovery
+   * are paused until the daily counter resets. Defaults to 1,000.
+   */
+  dailyApiReserveForCommands?: number
+  /**
+   * When true, the plugin will completely stop background polling/discovery
+   * once the remaining daily budget reaches the reserve (webhook-only mode).
+   * When false, polling continues until the hard daily limit is reached.
+   * Default: false.
+   */
+  webhookOnlyOnReserve?: boolean
+  // Matter platform batch refresh options
+  matterBatchRefreshRate?: number
+  matterBatchConcurrency?: number
+  matterBatchEnabled?: boolean
+  matterBatchJitter?: number
 };
 
 export type devicesConfig = botConfig | relaySwitch1Config | relaySwitch1PMConfig | meterConfig | meterProConfig | indoorOutdoorSensorConfig | humidifierConfig | curtainConfig | blindTiltConfig | contactConfig | motionConfig | waterDetectorConfig | plugConfig | colorBulbConfig | stripLightConfig | ceilingLightConfig | lockConfig | hubConfig
@@ -85,6 +116,12 @@ export interface BaseDeviceConfig extends device {
   mqttPubOptions?: IClientOptions
   history?: boolean
   webhook?: boolean
+  /**
+   * When true, applies this device's configuration to all other devices
+   * of the same deviceType/configDeviceType (e.g., all Humidifiers).
+   * Specific per-device settings will override these template settings.
+   */
+  applyToAllDevicesOfType?: boolean
 }
 
 export interface botConfig extends BaseDeviceConfig {
@@ -244,6 +281,12 @@ export interface irBaseDeviceConfig extends irdevice {
   logging?: string
   customOn?: string
   customOff?: string
+  /**
+   * When true, applies this IR device's configuration to all other IR devices
+   * of the same remoteType/configRemoteType (e.g., all IR Fans).
+   * Specific per-device settings will override these template settings.
+   */
+  applyToAllDevicesOfType?: boolean
   customize?: boolean
   commandType?: string
   disablePushOn?: boolean

package/src/test/hap/platform-hap.logging.test.ts

@@ -0,0 +1,36 @@
+/* eslint-disable import/first */
+import { describe, expect, it, vi } from 'vitest'
+// Mock modules used by the HAP platform constructor to avoid requiring a real Homebridge API
+vi.mock('fakegato-history', () => ({ default: () => ({}) }))
+vi.mock('homebridge-lib/EveHomeKitTypes', () => ({ EveHomeKitTypes: class { constructor() {} } }))
+
+import { SwitchBotHAPPlatform } from '../../platform-hap.js'
+import { makeLogStub } from '../helpers/platform-fixtures.js'
+
+/**
+ * Verifies that HAP platform debug logger includes the accessory displayName
+ * when loading an accessory from the cache.
+ */
+describe('platform-hap logging', () => {
+  it('prints accessory name when loading HAP cached accessory', async () => {
+    const api: any = { on: vi.fn() }
+    const log: any = makeLogStub()
+
+    const platform = new SwitchBotHAPPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+      devices: [],
+    } as any, api)
+
+    const accessory: any = { displayName: 'Test HAP Device' }
+    await (platform as any).configureAccessory(accessory)
+
+    // Allow async logger to flush
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    const calls = (log.info as any).mock.calls as Array<string[]>
+    const hasLine = calls.some(args => String(args[0]).includes('Loading accessory from cache: Test HAP Device'))
+    expect(hasLine).toBe(true)
+  })
+})

package/src/test/hap/platform-hap.test.ts

@@ -0,0 +1,70 @@
+/* eslint-disable import/first */
+import { describe, expect, it, vi } from 'vitest'
+// Mock modules used by the HAP platform constructor to avoid requiring a real Homebridge API
+vi.mock('fakegato-history', () => ({ default: () => ({}) }))
+vi.mock('homebridge-lib/EveHomeKitTypes', () => ({ EveHomeKitTypes: class { constructor() {} } }))
+
+import { SwitchBotHAPPlatform } from '../../platform-hap.js'
+import { makeLogStub } from '../helpers/platform-fixtures.js'
+
+/**
+ * High-level smoke tests for the HAP platform to ensure it initializes,
+ * subscribes to lifecycle events, and handles cached accessories.
+ */
+describe('platform-hap (smoke)', () => {
+  it('initializes and subscribes to didFinishLaunching', async () => {
+    const api: any = { on: vi.fn() }
+    const log: any = makeLogStub()
+
+    // Enable debug so debug* logs print via our shared logger
+    // Construct the platform (smoke)
+    new SwitchBotHAPPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+      devices: [],
+    } as any, api)
+
+    // Should register didFinishLaunching handler
+    expect(api.on).toHaveBeenCalled()
+    const calledWithDL = (api.on as any).mock.calls.some((args: any[]) => args[0] === 'didFinishLaunching' && typeof args[1] === 'function')
+    expect(calledWithDL).toBe(true)
+
+    // Should log effective platform logging at startup
+    const debugCalls = (log.debug as any).mock.calls as Array<string[]>
+    const hasStartupLine = debugCalls.some(args => String(args[0]).includes('[SwitchBot HAP] effective platformLogging='))
+    expect(hasStartupLine).toBe(true)
+
+    // Missing credentials results in a debug error log
+    // Allow async platform logger to flush
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const errorCalls = (log.error as any).mock.calls as Array<string[]>
+    const hasMissingCreds = errorCalls.some(args => String(args[0]).includes('Missing SwitchBot API credentials'))
+    expect(hasMissingCreds).toBe(true)
+  })
+
+  it('adds cached accessories via configureAccessory', async () => {
+    const api: any = { on: vi.fn() }
+    const log: any = makeLogStub()
+
+    const platform = new SwitchBotHAPPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+      devices: [],
+    } as any, api)
+
+    const accessory: any = { displayName: 'Cached Device' }
+    await (platform as any).configureAccessory(accessory)
+
+    // Should be stored in platform.accessories
+    expect(Array.isArray((platform as any).accessories)).toBe(true)
+    expect((platform as any).accessories.length).toBe(1)
+
+    // And should log the cache load message including device name
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const infoCalls = (log.info as any).mock.calls as Array<string[]>
+    const hasLine = infoCalls.some(args => String(args[0]).includes('Loading accessory from cache: Cached Device'))
+    expect(hasLine).toBe(true)
+  })
+})

package/src/test/helpers/platform-fixtures.ts

@@ -0,0 +1,33 @@
+import { vi } from 'vitest'
+
+// Shared test helpers for platform-matter tests
+export function makeApiStub(matterProps: Record<string, any> = {}) {
+  const handlers: Record<string, (...args: any[]) => any> = {}
+
+  const api: any = {
+    matter: {
+      uuid: { generate: (s: string) => `uuid-${s}` },
+      registerPlatformAccessories: matterProps.registerPlatformAccessories ?? vi.fn(),
+      unregisterPlatformAccessories: matterProps.unregisterPlatformAccessories ?? vi.fn(),
+      updateAccessoryState: matterProps.updateAccessoryState ?? vi.fn(),
+      clusterNames: matterProps.clusterNames ?? {},
+      deviceTypes: matterProps.deviceTypes ?? {},
+    },
+    isMatterAvailable: matterProps.isMatterAvailable ?? (() => true),
+    isMatterEnabled: matterProps.isMatterEnabled ?? (() => true),
+    on: (ev: string, fn: (...args: any[]) => any) => { handlers[ev] = fn },
+    _handlers: handlers,
+  }
+
+  return api
+}
+
+export function makeLogStub() {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    debug: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+  }
+}

package/src/test/index.test.ts

@@ -0,0 +1,24 @@
+import type { API } from 'homebridge'
+
+import { describe, expect, it, vi } from 'vitest'
+
+import registerPlatform from '../index.js'
+import { PLATFORM_NAME, PLUGIN_NAME } from '../settings.js'
+
+describe('index.ts', () => {
+  it('should register the platform with homebridge', () => {
+    const api = {
+      registerPlatform: vi.fn(),
+    } as unknown as API
+
+    registerPlatform(api)
+
+    // The platform registration now uses a runtime proxy/delegate constructor so
+    // assert the call happened and the third argument is a constructor function.
+    expect(api.registerPlatform).toHaveBeenCalled()
+    const callArgs = (api.registerPlatform as any).mock.calls[0]
+    expect(callArgs[0]).toBe(PLUGIN_NAME)
+    expect(callArgs[1]).toBe(PLATFORM_NAME)
+    expect(typeof callArgs[2]).toBe('function')
+  })
+})

package/src/test/matter/devices-matter/baseMatterAccessory.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { BaseMatterAccessory } from '../../../devices-matter/BaseMatterAccessory.js'
+
+// Minimal concrete subclass for testing
+class TestAccessory extends BaseMatterAccessory {
+  constructor(api: any, log: any, opts?: any) {
+    super(api, log, {
+      uuid: opts?.uuid ?? api.matter.uuid.generate('test'),
+      displayName: opts?.displayName ?? 'Test',
+      deviceType: opts?.deviceType ?? ('OnOffLight' as any),
+      serialNumber: opts?.serialNumber ?? 'TEST-1',
+      manufacturer: opts?.manufacturer ?? 'TestCo',
+      model: opts?.model ?? 'T-1',
+      firmwareRevision: opts?.firmwareRevision ?? '1.0',
+      hardwareRevision: opts?.hardwareRevision ?? '1.0',
+      context: opts?.context ?? {},
+      clusters: opts?.clusters,
+      handlers: opts?.handlers,
+    })
+  }
+}
+
+describe('baseMatterAccessory helpers', () => {
+  it('sendOnCommand uses OpenAPI helper and updates state', async () => {
+    const update = vi.fn()
+    const sendOpenAPI = vi.fn(async () => ({ response: {}, statusCode: 200 }))
+    const api: any = { matter: { clusterNames: { OnOff: 'onOff', LevelControl: 'level', ColorControl: 'color' }, uuid: { generate: () => 'uuid-1' }, updateAccessoryState: update } }
+    const log: any = { info: vi.fn(), debug: vi.fn(), error: vi.fn(), warn: vi.fn() }
+
+    const ctx = { deviceId: 'DEV-1', sendOpenAPI, connectionType: 'OpenAPI' }
+    const acc = new TestAccessory(api, log, { context: ctx })
+
+    await acc.sendOnCommand()
+
+    expect(sendOpenAPI).toHaveBeenCalledWith('turnOn', 'default')
+    expect(update).toHaveBeenCalledWith(acc.uuid, 'onOff', { onOff: true })
+  })
+
+  it('sendOnCommand uses BLE helper when connectionType is BLE', async () => {
+    const update = vi.fn()
+    const sendBLE = vi.fn(async () => true)
+    const api: any = { matter: { clusterNames: { OnOff: 'onOff', LevelControl: 'level', ColorControl: 'color' }, uuid: { generate: () => 'uuid-2' }, updateAccessoryState: update } }
+    const log: any = { info: vi.fn(), debug: vi.fn(), error: vi.fn(), warn: vi.fn() }
+
+    const ctx = { deviceId: 'DEV-2', sendBLE, connectionType: 'BLE' }
+    const acc = new TestAccessory(api, log, { context: ctx })
+
+    await acc.sendOnCommand()
+
+    expect(sendBLE).toHaveBeenCalledWith('turnOn')
+    expect(update).toHaveBeenCalledWith(acc.uuid, 'onOff', { onOff: true })
+  })
+
+  it('sendSetBrightness sends percent and updates LevelControl', async () => {
+    const update = vi.fn()
+    const sendOpenAPI = vi.fn(async () => ({ response: {}, statusCode: 200 }))
+    const api: any = { matter: { clusterNames: { OnOff: 'onOff', LevelControl: 'level', ColorControl: 'color' }, uuid: { generate: () => 'uuid-3' }, updateAccessoryState: update } }
+    const log: any = { info: vi.fn(), debug: vi.fn(), error: vi.fn(), warn: vi.fn() }
+
+    const ctx = { deviceId: 'DEV-3', sendOpenAPI, connectionType: 'OpenAPI' }
+    const acc = new TestAccessory(api, log, { context: ctx })
+
+    await acc.sendSetBrightness(50)
+
+    expect(sendOpenAPI).toHaveBeenCalledWith('setBrightness', '50')
+    const expectedLevel = Math.round((50 / 100) * 254)
+    expect(update).toHaveBeenCalledWith(acc.uuid, 'level', { currentLevel: expectedLevel })
+  })
+
+  it('sendSetColor sends RGB and updates ColorControl', async () => {
+    const update = vi.fn()
+    const sendOpenAPI = vi.fn(async () => ({ response: {}, statusCode: 200 }))
+    const api: any = { matter: { clusterNames: { OnOff: 'onOff', LevelControl: 'level', ColorControl: 'color' }, uuid: { generate: () => 'uuid-4' }, updateAccessoryState: update } }
+    const log: any = { info: vi.fn(), debug: vi.fn(), error: vi.fn(), warn: vi.fn() }
+
+    const ctx = { deviceId: 'DEV-4', sendOpenAPI, connectionType: 'OpenAPI' }
+    const acc = new TestAccessory(api, log, { context: ctx })
+
+    await acc.sendSetColor(255, 128, 0)
+
+    expect(sendOpenAPI).toHaveBeenCalledWith('setColor', '255:128:0')
+    expect(update).toHaveBeenCalled()
+    // Ensure we updated ColorControl cluster with numeric attributes
+    const calledWith = (update.mock.calls[0] || update.mock.calls[1])
+    expect(calledWith[1] === 'color' || calledWith[1] === api.matter.clusterNames.ColorControl).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+describe('additional platform-matter mapping tests', () => {
+  it('parses OpenAPI color strings and triggers an update', async () => {
+    const updateAccessoryState = vi.fn()
+    const api: any = makeApiStub({ updateAccessoryState })
+    const log = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    // Some OpenAPI statuses provide color as comma/colon separated or hex
+    await (platform as any).applyStatusToAccessory('uuid-col', { deviceId: 'DEV-COL' } as any, { color: '255:128:64' })
+    await (platform as any).applyStatusToAccessory('uuid-col', { deviceId: 'DEV-COL' } as any, { color: '255,128,64' })
+    await (platform as any).applyStatusToAccessory('uuid-col', { deviceId: 'DEV-COL' } as any, { color: '#FF8040' })
+
+    expect(updateAccessoryState).toHaveBeenCalled()
+  })
+
+  it('maps MeterPro CO2 values to Matter updates', async () => {
+    const updateAccessoryState = vi.fn()
+    const api: any = makeApiStub({ updateAccessoryState })
+    const log = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    await (platform as any).applyStatusToAccessory('uuid-co2', { deviceId: 'DEV-METERPRO' } as any, { co2: 420 })
+
+    expect(updateAccessoryState).toHaveBeenCalled()
+  })
+
+  it('handles curtain position synonyms (position / slidePosition)', async () => {
+    const updateAccessoryState = vi.fn()
+    const api: any = makeApiStub({ updateAccessoryState })
+    const log = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    // Provide status with position and slidePosition synonyms
+    await (platform as any).applyStatusToAccessory('uuid-cur', { deviceId: 'DEV-CUR', deviceType: 'Curtain' } as any, { position: 30 })
+    await (platform as any).applyStatusToAccessory('uuid-cur', { deviceId: 'DEV-CUR', deviceType: 'Curtain' } as any, { slidePosition: 70 })
+
+    expect(updateAccessoryState).toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,47 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+describe('platform-matter BLE advertisement parser', () => {
+  it('parses extended serviceData fields correctly', () => {
+    const updateAccessoryState = vi.fn()
+    const api: any = makeApiStub({ updateAccessoryState })
+
+    const log: any = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    const dev: any = { deviceId: 'DEV-TEST' }
+    const sd = {
+      temp: 22.3,
+      humid: 45,
+      pm25: 12,
+      pm10: 34,
+      voc: 120,
+      co2: 420,
+      motion: 1,
+      open: 0,
+      leak: 0,
+      position: 30,
+      fanSpeed: 75,
+      battery: 88,
+      rgb: '255:128:64',
+    }
+
+    const parsed = (platform as any).parseAdvertisementForDevice(dev, sd)
+    expect(parsed).toBeTruthy()
+    expect(parsed.temperature).toBeCloseTo(22.3)
+    expect(parsed.humidity).toBe(45)
+    expect(parsed.pm25).toBe(12)
+    expect(parsed.pm10).toBe(34)
+    expect(parsed.voc).toBe(120)
+    expect(parsed.co2).toBe(420)
+    expect(parsed.motion).toBeTruthy()
+    expect(parsed.contact).toBeDefined()
+    expect(parsed.leak).toBeFalsy()
+    expect(parsed.position).toBe(30)
+    expect(parsed.fanSpeed).toBe(75)
+    expect(parsed.battery).toBe(88)
+    expect(parsed.color).toEqual({ r: 255, g: 128, b: 64 })
+  })
+})

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

@@ -0,0 +1,86 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { formatDeviceIdAsMac } from '../../utils.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.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 = makeApiStub({ registerPlatformAccessories: vi.fn(), unregisterPlatformAccessories: vi.fn(), clusterNames: { OnOff: 'OnOff' } })
+    api._handlers = handlers
+    // keep api.on as a single-statement arrow to satisfy lint
+    api.on = (ev: string, fn: (...args: any[]) => any) => (handlers[ev] = fn)
+
+    const log = makeLogStub()
+
+    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 = makeApiStub({ registerPlatformAccessories: vi.fn(), unregisterPlatformAccessories: vi.fn(), clusterNames: { OnOff: 'OnOff' } })
+    api._handlers = handlers
+    // keep api.on as a single-statement arrow to satisfy lint
+    api.on = (ev: string, fn: (...args: any[]) => any) => (handlers[ev] = fn)
+
+    const log = makeLogStub()
+
+    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/test/matter/platform-matter.keepstale.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+describe('keepStaleAccessories config flag behavior', () => {
+  it('keeps previously-registered accessories when options.keepStaleAccessories=true', async () => {
+    const unregister = vi.fn()
+    const register = vi.fn()
+    const api: any = makeApiStub({ unregisterPlatformAccessories: unregister, registerPlatformAccessories: register })
+
+    const log: any = makeLogStub()
+
+    // Create platform with keepStaleAccessories = true
+    const platform = new SwitchBotMatterPlatform(log as any, { options: { keepStaleAccessories: true } } as any, api)
+
+    // Seed discovered devices (one device)
+    ;(platform as any).discoveredDevices = [{ deviceId: 'DEV1', deviceType: 'Plug', deviceName: 'Device 1' }]
+
+    // Insert a stale accessory into matterAccessories
+    const staleUuid = api.matter.uuid.generate('stale-device')
+    const staleAcc: any = { uuid: staleUuid, displayName: 'Stale', context: { deviceId: 'STALE_DEVICE' } }
+    ;(platform as any).matterAccessories.set(staleUuid, staleAcc)
+
+    // Mock createAccessoryFromDevice to return a simple accessory for DEV1
+    vi.spyOn(platform as any, 'createAccessoryFromDevice').mockResolvedValue({ displayName: 'Device 1', uuid: 'uuid-DEV1', context: { deviceId: 'DEV1' } } as any)
+
+    // Run registration which includes stale-removal logic
+    await (platform as any).registerMatterAccessories()
+
+    // Expect unregister NOT called (we kept stale accessory)
+    expect(unregister).not.toHaveBeenCalled()
+
+    // Stale accessory should still be present in matterAccessories
+    expect((platform as any).matterAccessories.get(staleUuid)).toBeDefined()
+  })
+})

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

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+/**
+ * Verifies that debug logger formats arguments so that accessory displayName
+ * appears in the output for cached accessory load logs.
+ */
+describe('platform-matter logging', () => {
+  it('prints accessory name when loading cached Matter accessory', async () => {
+    const api: any = makeApiStub()
+    const log: any = makeLogStub()
+
+    const platform = new SwitchBotMatterPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+    } as any, api)
+
+    // Simulate Homebridge restoring a cached Matter accessory
+    const acc: any = { uuid: 'uuid-TEST', displayName: 'Test Device', context: { deviceId: 'DEV1' } }
+    ;(platform as any).configureMatterAccessory(acc)
+    // debugLog is async and gated; yield to allow the logger to run
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    // In 'debug' mode, debugLog uses log.info with a [DEBUG] prefix
+    // Ensure one of the info calls contains the message with the device name
+    const calls = (log.info as any).mock.calls as Array<string[]>
+    const hasLine = calls.some(args => String(args[0]).includes('Loading cached Matter accessory: Test Device'))
+    expect(hasLine).toBe(true)
+  })
+})

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

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.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 = makeApiStub({ updateAccessoryState, clusterNames: { OnOff: 'OnOff', LevelControl: 'LevelControl', ColorControl: 'ColorControl', PowerSource: 'powerSource' } })
+
+    const log: any = makeLogStub()
+    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 = makeApiStub({ updateAccessoryState })
+
+    const log: any = makeLogStub()
+    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()
+  })
+
+  it('applies VOC and PM10 mappings when present', async () => {
+    const updateAccessoryState = vi.fn()
+    const api: any = makeApiStub({ updateAccessoryState })
+
+    const log: any = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    const deviceId = 'DEV-AQ'
+    await (platform as any).applyStatusToAccessory('uuid-aq', { deviceId } as any, { voc: 123, pm10: 56 })
+
+    // Expect updateAccessoryState (or safeUpdate fallback) to have been called for voc and pm10
+    expect(updateAccessoryState).toHaveBeenCalled()
+  })
+})