@switchbot/homebridge-switchbot 5.0.0-beta.20 → 5.0.0-beta.22

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.ts

@@ -978,6 +978,12 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
         if (c.includes(':')) {
           const parts = c.split(':').map(Number)
           ;[r, g, b] = parts
+        } else if (c.includes(',')) {
+          const parts = c.split(',').map(s => Number(s.trim()))
+          ;[r, g, b] = parts
+        } else if (c.includes(' ')) {
+          const parts = c.split(' ').map(s => Number(s.trim()))
+          ;[r, g, b] = parts
         } else if (c.startsWith('#')) {
           const hex = c.replace('#', '')
           r = Number.parseInt(hex.substring(0, 2), 16)
@@ -997,6 +1003,85 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
         result.battery = Number(battery)
       }
 
+      // VOC / TVOC (some air quality devices report total volatile organic compounds)
+      const voc = sd.voc ?? sd.tvoc
+      if (voc !== undefined) {
+        result.voc = Number(voc)
+      }
+
+      // PM10 (some devices report PM10 alongside PM2.5)
+      const pm10 = sd.pm10
+      if (pm10 !== undefined) {
+        result.pm10 = Number(pm10)
+      }
+
+      // PM2.5 (some BLE adverts use pm25 / pm_2_5)
+      const pm25 = sd.pm2_5 ?? sd.pm25 ?? sd.pm_2_5
+      if (pm25 !== undefined) {
+        result.pm25 = Number(pm25)
+      }
+
+      // CO2 (carbon dioxide ppm)
+      const co2 = sd.co2 ?? sd.co2ppm ?? sd.carbonDioxide
+      if (co2 !== undefined) {
+        result.co2 = Number(co2)
+      }
+
+      // Temperature (C) and Humidity (%) — support common shorthand keys
+      const temperature = sd.temperature ?? sd.temp ?? sd.t
+      if (temperature !== undefined) {
+        result.temperature = Number(temperature)
+      }
+
+      const humidity = sd.humidity ?? sd.h ?? sd.humid
+      if (humidity !== undefined) {
+        result.humidity = Number(humidity)
+      }
+
+      // Motion, Contact, Leak
+      const motion = sd.motion ?? sd.m
+      if (motion !== undefined) {
+        result.motion = Boolean(motion)
+      }
+
+      const contact = sd.contact ?? sd.open
+      if (contact !== undefined) {
+        result.contact = contact
+      }
+
+      const leak = sd.leak ?? sd.water
+      if (leak !== undefined) {
+        result.leak = Boolean(leak)
+      }
+
+      // Position / Cover / Curtain synonyms
+      const position = sd.position ?? sd.percent ?? sd.slidePosition ?? sd.curtainPosition
+      if (position !== undefined) {
+        result.position = Number(position)
+      }
+
+      // Fan speed/speed
+      const fanSpeed = sd.fanSpeed ?? sd.speed
+      if (fanSpeed !== undefined) {
+        result.fanSpeed = Number(fanSpeed)
+      }
+
+      // Lock state
+      const lock = sd.lock
+      if (lock !== undefined) {
+        result.lock = lock
+      }
+
+      // Robot vacuum fields
+      const rvcRunMode = sd.rvcRunMode
+      if (rvcRunMode !== undefined) {
+        result.rvcRunMode = rvcRunMode
+      }
+      const rvcOperationalState = sd.rvcOperationalState
+      if (rvcOperationalState !== undefined) {
+        result.rvcOperationalState = rvcOperationalState
+      }
+
       return result
     } catch (e: any) {
       this.debugLog(`parseAdvertisementForDevice failed for ${dev.deviceId}: ${e?.message ?? e}`)
@@ -1055,6 +1140,12 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
         if (color.includes(':')) {
           const parts = color.split(':').map(Number)
           ;[r, g, b] = parts
+        } else if (color.includes(',')) {
+          const parts = color.split(',').map(s => Number(s.trim()))
+          ;[r, g, b] = parts
+        } else if (color.includes(' ')) {
+          const parts = color.split(' ').map(s => Number(s.trim()))
+          ;[r, g, b] = parts
         } else if (color.startsWith('#')) {
           const hex = color.replace('#', '')
           r = Number.parseInt(hex.substring(0, 2), 16)
@@ -1065,10 +1156,10 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
         await safeUpdate(this.api.matter.clusterNames.ColorControl, { currentHue: Math.round((h / 360) * 254), currentSaturation: Math.round((s / 100) * 254) }, 'updateHueSaturation')
       }
 
-      // Battery/powerSource
-      if (status?.battery !== undefined || status?.batt !== undefined) {
+      // Battery/powerSource (support many possible field names)
+      if (status?.battery !== undefined || status?.batt !== undefined || status?.batteryLevel !== undefined || status?.batteryPercentage !== undefined || status?.battery_level !== undefined) {
         try {
-          const percentage = Number(status?.battery ?? status?.batt)
+          const percentage = Number(status?.battery ?? status?.batt ?? status?.batteryPercentage ?? status?.batteryLevel ?? status?.battery_level)
           const batPercentRemaining = Math.max(0, Math.min(200, Math.round(percentage * 2)))
           let batChargeLevel = 0
           if (percentage < 20) {
@@ -1076,7 +1167,8 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
           } else if (percentage < 40) {
             batChargeLevel = 1
           }
-          await safeUpdate('powerSource', { batPercentRemaining, batChargeLevel }, 'updateBatteryPercentage')
+          const powerCluster = (this.api.matter?.clusterNames && (this.api.matter.clusterNames as any).PowerSource) ? (this.api.matter.clusterNames as any).PowerSource : 'powerSource'
+          await safeUpdate(powerCluster, { batPercentRemaining, batChargeLevel }, 'updateBatteryPercentage')
         } catch (e: any) {
           this.debugLog(`Failed to apply battery status for ${dev.deviceId}: ${e?.message ?? e}`)
         }
@@ -1099,10 +1191,10 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
         }
       }
 
-      // Humidity
-      if (status?.humidity !== undefined || status?.h !== undefined) {
+      // Humidity (support different keys)
+      if (status?.humidity !== undefined || status?.h !== undefined || status?.humid !== undefined) {
         try {
-          const percent = Number(status?.humidity ?? status?.h)
+          const percent = Number(status?.humidity ?? status?.h ?? status?.humid)
           const measured = Math.round(percent * 100)
           await safeUpdate('relativeHumidityMeasurement', { measuredValue: measured }, 'updateHumidity')
         } catch (e: any) {
@@ -1186,6 +1278,44 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
           this.debugLog(`Failed to apply rvcRunMode for ${dev.deviceId}: ${e?.message ?? e}`)
         }
       }
+      // CO2 (carbon dioxide) - support common synonyms
+      if (status?.co2 !== undefined || status?.co2ppm !== undefined || status?.carbonDioxide !== undefined) {
+        try {
+          const val = Number(status?.co2 ?? status?.co2ppm ?? status?.carbonDioxide)
+          await safeUpdate('carbonDioxide', { carbonDioxideLevel: val }, 'updateCO2')
+        } catch (e: any) {
+          this.debugLog(`Failed to apply CO2 for ${dev.deviceId}: ${e?.message ?? e}`)
+        }
+      }
+
+      // PM2.5 / particulate matter
+      if (status?.pm2_5 !== undefined || status?.pm25 !== undefined || status?.pm_2_5 !== undefined) {
+        try {
+          const pm = Number(status?.pm2_5 ?? status?.pm25 ?? status?.pm_2_5)
+          await safeUpdate('pm2_5', { pm25: pm }, 'updatePM25')
+        } catch (e: any) {
+          this.debugLog(`Failed to apply PM2.5 for ${dev.deviceId}: ${e?.message ?? e}`)
+        }
+      }
+      // PM10 (some devices report pm10)
+      if (status?.pm10 !== undefined) {
+        try {
+          const pm10 = Number(status?.pm10)
+          await safeUpdate('pm10', { pm10 }, 'updatePM10')
+        } catch (e: any) {
+          this.debugLog(`Failed to apply PM10 for ${dev.deviceId}: ${e?.message ?? e}`)
+        }
+      }
+
+      // VOC / TVOC - volatile organic compounds
+      if (status?.voc !== undefined || status?.tvoc !== undefined) {
+        try {
+          const val = Number(status?.voc ?? status?.tvoc)
+          await safeUpdate('voc', { voc: val }, 'updateVOC')
+        } catch (e: any) {
+          this.debugLog(`Failed to apply VOC for ${dev.deviceId}: ${e?.message ?? e}`)
+        }
+      }
       if (status?.rvcOperationalState !== undefined) {
         try {
           await safeUpdate('rvcOperationalState', { operationalState: Number(status.rvcOperationalState) }, 'updateOperationalState')
@@ -1237,6 +1367,52 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
       // Merge device config (deviceConfig per deviceType and per-device overrides) to match HAP behavior
       const devicesToProcess = await this.mergeDiscoveredDevices(this.discoveredDevices)
 
+      // By default, automatically remove previously-registered Matter
+      // accessories whose deviceId is not present in the merged discovered
+      // list. If the user explicitly sets `options.keepStaleAccessories` to
+      // true, then we will keep previously-registered accessories (legacy
+      // behavior).
+      if ((this.config as any).options?.keepStaleAccessories) {
+        this.debugLog('Keeping previously-registered stale accessories because options.keepStaleAccessories=true')
+      } else {
+        try {
+          const desiredIds = new Set((devicesToProcess || []).map((d: any) => this.normalizeDeviceId(d.deviceId)))
+          const toUnregister: Array<MatterAccessory<Record<string, unknown>>> = []
+          for (const [uuid, acc] of Array.from(this.matterAccessories.entries())) {
+            try {
+              const deviceId = (acc as any)?.context?.deviceId
+              if (!deviceId) {
+                continue
+              }
+              const nid = this.normalizeDeviceId(deviceId)
+              if (!desiredIds.has(nid)) {
+                // Accessory exists but is no longer desired -> schedule for removal
+                this.infoLog(`Removing previously-registered accessory for deviceId=${deviceId} (no longer discovered or configured)`)
+                try {
+                  this.clearDeviceResources(deviceId)
+                } catch (e: any) {
+                  this.debugLog(`Failed to clear resources for ${deviceId} before unregister: ${e?.message ?? e}`)
+                }
+                toUnregister.push(acc as unknown as MatterAccessory<Record<string, unknown>>)
+                this.matterAccessories.delete(uuid)
+              }
+            } catch (e: any) {
+              this.debugLog(`Error while checking existing accessory ${uuid}: ${e?.message ?? e}`)
+            }
+          }
+
+          if (toUnregister.length > 0) {
+            try {
+              await this.api.matter.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, toUnregister)
+            } catch (e: any) {
+              this.debugLog(`Failed to unregister accessories: ${e?.message ?? e}`)
+            }
+          }
+        } catch (e: any) {
+          this.debugLog(`Failed to remove stale accessories: ${e?.message ?? e}`)
+        }
+      }
+
       // We'll separate discovered devices into two buckets:
       // - platformAccessories: accessories that will be hosted under the plugin's Matter bridge
       // - roboticAccessories: robot vacuum devices which require standalone commissioning behaviour

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

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from './platform-matter.js'
+import { formatDeviceIdAsMac } from './utils.js'
+
+describe('removeDisabledAccessories and unregister edge cases', () => {
+  it('clears resources and unregisters accessory even with invalid timer and non-MAC deviceId', async () => {
+    // Prepare API stub
+    const unregister = vi.fn()
+    const api: any = {
+      matter: {
+        uuid: { generate: (s: string) => `uuid-${s}` },
+        unregisterPlatformAccessories: unregister,
+      },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: () => {},
+    }
+
+    const log: any = { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn(), success: vi.fn() }
+    const platform = new SwitchBotMatterPlatform(log as any, { enableOnOffLight: false } as any, api)
+
+    // Build a fake serialized accessory matching the generated UUID for OnOff Light
+    const uuid = api.matter.uuid.generate('matter-onoff-light')
+    const accessory: any = { uuid, displayName: 'OnOff Light', context: { deviceId: 'NOT-A-MAC' } }
+
+    // Put invalid timer object into refreshTimers to ensure code handles it
+    const nid = (platform as any).normalizeDeviceId(accessory.context.deviceId)
+    ;(platform as any).refreshTimers.set(nid, null as any)
+    ;(platform as any).accessoryInstances.set(nid, { dummy: true })
+
+    // Insert accessory into matterAccessories so removeDisabledAccessories will see it
+    ;(platform as any).matterAccessories.set(uuid, accessory)
+
+    // Spy on clearDeviceResources
+    const spyClear = vi.spyOn(platform as any, 'clearDeviceResources')
+
+    // Call removeDisabledAccessories directly
+    await (platform as any).removeDisabledAccessories()
+
+    // Expect unregister was called and matterAccessories cleared
+    expect(unregister).toHaveBeenCalled()
+    expect((platform as any).matterAccessories.get(uuid)).toBeUndefined()
+
+    // clearDeviceResources should have been called with the accessory.deviceId
+    expect(spyClear).toHaveBeenCalledWith(accessory.context.deviceId)
+  })
+})

package/src/settings.ts

@@ -40,6 +40,12 @@ export interface options {
   // 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