@switchbot/homebridge-switchbot 5.0.0-beta.1 → 5.0.0-beta.10

package/src/platform-matter.ts

@@ -5,9 +5,12 @@ import type {
   MatterAccessory,
   SerializedMatterAccessory,
 } from 'homebridge'
+import type { bodyChange, device } from 'node-switchbot'
 
 import type { SwitchBotPlatformConfig } from './settings.js'
 
+import { SwitchBotBLE, SwitchBotOpenAPI } from 'node-switchbot'
+
 import {
   ColorLightAccessory,
   ColorTemperatureLightAccessory,
@@ -32,7 +35,7 @@ import {
   WindowBlindAccessory,
 } from './devices-matter/index.js'
 import { PLATFORM_NAME, PLUGIN_NAME } from './settings.js'
-import { cleanDeviceConfig } from './utils.js'
+import { cleanDeviceConfig, formatDeviceIdAsMac, hs2rgb, rgb2hs, sleep } from './utils.js'
 
 /**
  * MatterPlatform
@@ -47,6 +50,13 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
 
   // Track restored Matter cached accessories
   public readonly matterAccessories: Map<string, SerializedMatterAccessory> = new Map()
+  // node-switchbot clients
+  private switchBotAPI?: SwitchBotOpenAPI
+  private switchBotBLE?: SwitchBotBLE
+  // discovered devices cache
+  private discoveredDevices: device[] = []
+  // BLE event handlers keyed by device MAC (formatted)
+  private bleEventHandler: { [x: string]: (context: any) => void } = {}
 
   constructor(
     public readonly log: Logging,
@@ -87,10 +97,616 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     // Register Matter accessories when Homebridge has finished launching
     this.api.on('didFinishLaunching', () => {
       this.log.debug('Executed didFinishLaunching callback')
+      // Initialize SwitchBot API clients
+      try {
+        if (this.config.credentials?.token && this.config.credentials?.secret) {
+          this.switchBotAPI = new SwitchBotOpenAPI(this.config.credentials.token, this.config.credentials.secret, this.config.options?.hostname)
+          // forward basic logs
+          if (!this.config.options?.disableLogsforOpenAPI && this.switchBotAPI?.on) {
+            this.switchBotAPI.on('log', (l: any) => this.log.debug('[SwitchBot OpenAPI]', l.message))
+          }
+        } else {
+          this.log.debug('SwitchBot OpenAPI credentials not provided; cloud devices will be skipped')
+        }
+      } catch (e: any) {
+        this.log.error('Failed to initialize SwitchBot OpenAPI:', e?.message ?? e)
+      }
+
+      try {
+        this.switchBotBLE = new SwitchBotBLE()
+        if (!this.config.options?.disableLogsforBLE && this.switchBotBLE?.on) {
+          this.switchBotBLE.on('log', (l: any) => this.log.debug('[SwitchBot BLE]', l.message))
+        }
+      } catch (e: any) {
+        this.log.error('Failed to initialize SwitchBot BLE client:', e?.message ?? e)
+      }
+
+      // If BLE scanning is enabled, start scanning and route advertisements to registered handlers
+      if (this.config.options?.BLE && this.switchBotBLE) {
+        const ble = this.switchBotBLE
+        ;(async () => {
+          try {
+            await ble.startScan()
+          } catch (e: any) {
+            this.log.error(`Failed to start BLE scanning: ${e?.message ?? e}`)
+          }
+
+          // route advertisements to our handlers
+          ble.onadvertisement = async (ad: any) => {
+            try {
+              const mac = (ad.address || '').toLowerCase()
+              const handler = this.bleEventHandler[mac]
+              if (handler) {
+                await handler(ad.serviceData)
+              }
+            } catch (e: any) {
+              this.log.error(`Failed to handle BLE advertisement: ${e?.message ?? e}`)
+            }
+          }
+        })()
+      }
+
+      // perform device discovery from SwitchBot OpenAPI (if configured)
+      void this.discoverDevices()
+
       this.registerMatterAccessories()
     })
   }
 
+  /**
+   * Normalize a deviceId for matching (uppercase alphanumerics only)
+   */
+  private normalizeDeviceId(deviceId: string) {
+    return (deviceId ?? '').toUpperCase().replace(/[^A-Z0-9]+/g, '')
+  }
+
+  /**
+   * Merge two arrays by deviceId. For each item in a1 (user-provided devices list),
+   * find matching item in a2 (discovered devices) and merge them with user overrides last.
+   */
+  private mergeByDeviceId(a1: { deviceId: string }[], a2: any[]) {
+    return a1.map((itm) => {
+      const matchingItem = a2.find(item => this.normalizeDeviceId(item.deviceId) === this.normalizeDeviceId(itm.deviceId))
+      return Object.assign({}, matchingItem, itm)
+    })
+  }
+
+  /**
+   * Merge discovered devices with deviceConfig (per deviceType) and per-device overrides
+   * from `config.options.devices`, matching the behavior used in platform-hap.
+   */
+  private async mergeDiscoveredDevices(discovered: device[]): Promise<any[]> {
+    // If there's no device config or per-device config, return discovered as-is
+    if (!this.config.options?.devices && !this.config.options?.deviceConfig) {
+      return discovered
+    }
+
+    // Step 1: Assign missing deviceType from configDeviceType and merge deviceType-level configs
+    const devicesWithTypeConfig = await Promise.all(discovered.map(async (deviceObj) => {
+      if (!deviceObj.deviceType) {
+        deviceObj.deviceType = (deviceObj as any).configDeviceType !== undefined ? (deviceObj as any).configDeviceType : 'Unknown'
+        this.log.debug(`API missing deviceType for ${deviceObj.deviceId}, using configDeviceType: ${(deviceObj as any).configDeviceType}`)
+      }
+      const deviceTypeConfig = this.config.options?.deviceConfig?.[deviceObj.deviceType] || {}
+      return Object.assign({}, deviceObj, deviceTypeConfig)
+    }))
+
+    // Merge per-device overrides by matching deviceId
+    const merged = this.mergeByDeviceId(this.config.options?.devices ?? [], devicesWithTypeConfig ?? [])
+
+    // For any entries in merged (which are based on config.options.devices), ensure final per-device merges include deviceId-specific config
+    const final: any[] = []
+    for (const device of merged) {
+      const deviceIdConfig = this.config.options?.devices?.[device.deviceId] || {}
+      const deviceWithConfig = Object.assign({}, device, deviceIdConfig)
+      final.push(deviceWithConfig)
+    }
+
+    // Also include any discovered devices that weren't present in the user devices list
+    const userDeviceIds = new Set((this.config.options?.devices || []).map((d: any) => this.normalizeDeviceId(d.deviceId)))
+    for (const d of devicesWithTypeConfig) {
+      if (!userDeviceIds.has(this.normalizeDeviceId(d.deviceId))) {
+        final.push(d)
+      }
+    }
+
+    return final
+  }
+
+  /**
+   * Select effective connection type for a device: prefer explicit device.connectionType,
+   * otherwise prefer BLE when platform BLE is enabled and device provides a BLE model/id.
+   */
+  private chooseConnectionType(deviceObj: any): 'BLE' | 'OpenAPI' {
+    if (deviceObj?.connectionType) {
+      return deviceObj.connectionType === 'BLE' ? 'BLE' : 'OpenAPI'
+    }
+    // If platform BLE is enabled and we have a bleModel or deviceId that formats to a MAC, prefer BLE
+    if (this.config.options?.BLE && (deviceObj?.bleModel || formatDeviceIdAsMac(deviceObj?.deviceId))) {
+      return 'BLE'
+    }
+    return 'OpenAPI'
+  }
+
+  /**
+   * Map a SwitchBot device object to a MatterAccessory using the device-specific
+   * Matter accessory classes in `src/devices-matter`.
+   */
+  private async createAccessoryFromDevice(dev: device): Promise<MatterAccessory<Record<string, unknown>> | undefined> {
+    // Basic metadata
+    const displayName = dev.deviceName ?? dev.deviceId ?? 'SwitchBot Device'
+    const serial = dev.deviceId ?? 'unknown'
+    const manufacturer = 'SwitchBot'
+    const model = dev.deviceType ?? 'SwitchBot'
+    const firmware = (dev as any).firmware ?? (dev as any).version ?? '0.0.0'
+
+    // Helper to build a default opts object consumed by the matter device classes
+    const baseOpts = {
+      uuid: this.api.matter.uuid.generate(serial),
+      displayName,
+      serialNumber: serial,
+      manufacturer,
+      model,
+      firmwareRevision: String(firmware),
+      hardwareRevision: '1.0.0',
+      deviceId: dev.deviceId,
+      context: { deviceId: dev.deviceId },
+    }
+
+    // Small helper to wrap common OpenAPI on/off commands
+    // Helper to send an OpenAPI command
+    const sendOpenAPI = async (command: string, parameter = 'default') => {
+      const bodyChange: bodyChange = { command, parameter, commandType: 'command' }
+      return this.retryCommand(dev, bodyChange, this.config.options?.maxRetries ?? 1, this.config.options?.delayBetweenRetries ?? 1000)
+    }
+
+    // Helper to send a BLE action if Platform BLE is enabled and switchBotBLE exists
+    const sendBLE = async (methodName: string, ...args: any[]) => {
+      // Provide a small retry loop for flaky BLE operations
+      if (!this.switchBotBLE) {
+        throw new Error('Platform BLE not available')
+      }
+      const id = formatDeviceIdAsMac(dev.deviceId)
+      const maxRetries = (this.config.options as any)?.bleRetries ?? 2
+      const retryDelay = (this.config.options as any)?.bleRetryDelay ?? 500
+      let attempt = 0
+      while (attempt < maxRetries) {
+        try {
+          const list = await this.switchBotBLE.discover({ model: (dev as any).bleModel, id })
+          if (!Array.isArray(list) || list.length === 0) {
+            throw new Error('BLE device not found')
+          }
+          const deviceInst: any = list[0]
+          if (typeof deviceInst[methodName] !== 'function') {
+            throw new TypeError(`BLE method ${methodName} not available on device`)
+          }
+          return await deviceInst[methodName](...args)
+        } catch (e: any) {
+          attempt++
+          if (attempt >= maxRetries) {
+            throw e
+          }
+          this.log.debug(`BLE ${methodName} attempt ${attempt} failed for ${dev.deviceId}: ${e?.message ?? e}, retrying in ${retryDelay}ms`)
+          await sleep(retryDelay)
+        }
+      }
+      throw new Error('BLE operation failed')
+    }
+
+    const makeOnOffHandlers = (uuid: string, connectionType: 'BLE' | 'OpenAPI') => ({
+      onOff: {
+        on: async () => {
+          try {
+            if (connectionType === 'BLE' && this.switchBotBLE) {
+              await sendBLE('turnOn')
+            } else {
+              await sendOpenAPI('turnOn')
+            }
+            await this.api.matter.updateAccessoryState(uuid, this.api.matter.clusterNames.OnOff, { onOff: true })
+          } catch (e: any) {
+            this.log.error(`Failed to turn on device ${dev.deviceId}: ${e?.message ?? e}`)
+          }
+        },
+        off: async () => {
+          try {
+            if (connectionType === 'BLE' && this.switchBotBLE) {
+              await sendBLE('turnOff')
+            } else {
+              await sendOpenAPI('turnOff')
+            }
+            await this.api.matter.updateAccessoryState(uuid, this.api.matter.clusterNames.OnOff, { onOff: false })
+          } catch (e: any) {
+            this.log.error(`Failed to turn off device ${dev.deviceId}: ${e?.message ?? e}`)
+          }
+        },
+      },
+    })
+
+    // Mapping from SwitchBot deviceType -> constructor (expanded for parity with HAP)
+    const mapping: { [key: string]: any } = {
+      // Plugs / Outlets
+      'Plug': OnOffOutletAccessory,
+      'Plug Mini (US)': OnOffOutletAccessory,
+      'Plug Mini (JP)': OnOffOutletAccessory,
+      'Plug Mini': OnOffOutletAccessory,
+      'WoPlug': OnOffOutletAccessory,
+
+      // Lighting
+      'Color Bulb': ColorLightAccessory,
+      'Color Bulb Mini': ColorLightAccessory,
+      'Ceiling Light': ColorTemperatureLightAccessory,
+      'Ceiling Light Pro': ColorTemperatureLightAccessory,
+      'Strip Light': ExtendedColorLightAccessory,
+      'Light Strip': ExtendedColorLightAccessory,
+      'Light Strip Plus': ExtendedColorLightAccessory,
+      'Strip Light Pro': ExtendedColorLightAccessory,
+      'Dimmable Light': DimmableLightAccessory,
+
+      // Robot Vacuums
+      'K10+': RoboticVacuumAccessory,
+      'K10+ Pro': RoboticVacuumAccessory,
+      'WoSweeper': RoboticVacuumAccessory,
+      'WoSweeperMini': RoboticVacuumAccessory,
+      'Robot Vacuum Cleaner S1': RoboticVacuumAccessory,
+      'Robot Vacuum Cleaner S1 Plus': RoboticVacuumAccessory,
+      'Robot Vacuum Cleaner S10': RoboticVacuumAccessory,
+      'Robot Vacuum Cleaner S1 Pro': RoboticVacuumAccessory,
+      'Robot Vacuum Cleaner S1 Mini': RoboticVacuumAccessory,
+
+      // Locks
+      'Smart Lock': DoorLockAccessory,
+      'Smart Lock Pro': DoorLockAccessory,
+
+      // Sensors
+      'Motion Sensor': OccupancySensorAccessory,
+      'Contact Sensor': ContactSensorAccessory,
+      'Water Detector': LeakSensorAccessory,
+      'Meter': TemperatureSensorAccessory,
+      'MeterPlus': TemperatureSensorAccessory,
+      'MeterPro': TemperatureSensorAccessory,
+      'WoIOSensor': TemperatureSensorAccessory,
+      'Air Purifier PM2.5': HumiditySensorAccessory,
+      'Air Purifier Table PM2.5': HumiditySensorAccessory,
+      'Air Purifier': HumiditySensorAccessory,
+      'Air Purifier VOC': HumiditySensorAccessory,
+      'Air Purifier Table VOC': HumiditySensorAccessory,
+
+      // Fans
+      'Battery Circulator Fan': FanAccessory,
+
+      // Curtains / Blinds
+      'Blind Tilt': VenetianBlindAccessory,
+      'Curtain': WindowBlindAccessory,
+      'Curtain2': WindowBlindAccessory,
+      'Curtain3': WindowBlindAccessory,
+      'Curtain 2': WindowBlindAccessory,
+      'WoRollerShade': WindowBlindAccessory,
+      'Roller Shade': WindowBlindAccessory,
+      'Venetian Blind': VenetianBlindAccessory,
+
+      // Switches / Relays
+      'Relay Switch 1': OnOffSwitchAccessory,
+      'Relay Switch 1PM': OnOffSwitchAccessory,
+      'Relay Switch 2': OnOffSwitchAccessory,
+      'Relay Switch 3': OnOffSwitchAccessory,
+
+      // Misc / hubs / other
+      'Hub 2': undefined,
+      'Hub 3': undefined,
+      'Hub Mini': undefined,
+      'Bot': OnOffSwitchAccessory,
+      'Smart Bot': OnOffSwitchAccessory,
+      'Humidifier': HumiditySensorAccessory,
+      'Humidifier2': HumiditySensorAccessory,
+      'Thermostat': ThermostatAccessory,
+      'Water Heater': ThermostatAccessory,
+    }
+
+    const Ctor = mapping[dev.deviceType ?? '']
+    if (!Ctor) {
+      this.log.debug(`No Matter mapping for deviceType='${dev.deviceType}', deviceId=${dev.deviceId}`)
+      return undefined
+    }
+
+    // Build opts and handlers tailored for basic capabilities
+    const uuid = baseOpts.uuid
+    const handlers: Record<string, any> = {}
+
+    // Choose connection type for this device (BLE vs OpenAPI)
+    const connectionType = this.chooseConnectionType(dev)
+
+    // On/Off common
+    handlers.onOff = makeOnOffHandlers(uuid, connectionType).onOff
+
+    // If this is a light, add brightness and color handlers
+    if (['Color Bulb', 'Ceiling Light', 'Ceiling Light Pro', 'Strip Light', 'Dimmable Light'].includes(dev.deviceType ?? '')) {
+      // levelControl
+      handlers.levelControl = {
+        moveToLevelWithOnOff: async (request: any) => {
+          try {
+            const level = request.level as number
+            const percent = Math.round((level / 254) * 100)
+            if (connectionType === 'BLE' && this.switchBotBLE) {
+              await sendBLE('setBrightness', percent)
+            } else {
+              await sendOpenAPI('setBrightness', `${percent}`)
+            }
+            await this.api.matter.updateAccessoryState(uuid, this.api.matter.clusterNames.LevelControl, { currentLevel: level })
+          } catch (e: any) {
+            this.log.error(`Failed to set brightness for ${dev.deviceId}: ${e?.message ?? e}`)
+          }
+        },
+      }
+
+      // colorControl
+      handlers.colorControl = {
+        moveToHueAndSaturationLogic: async (request: any) => {
+          try {
+            const hue = request.hue as number
+            const saturation = request.saturation as number
+            const [r, g, b] = hs2rgb(Math.round((hue / 254) * 360), Math.round((saturation / 254) * 100))
+            if (connectionType === 'BLE' && this.switchBotBLE) {
+              await sendBLE('setRGB', Number(request.level ?? 100), r, g, b)
+            } else {
+              await sendOpenAPI('setColor', `${r}:${g}:${b}`)
+            }
+            await this.api.matter.updateAccessoryState(uuid, this.api.matter.clusterNames.ColorControl, { currentHue: hue, currentSaturation: saturation })
+          } catch (e: any) {
+            this.log.error(`Failed to set hue/sat for ${dev.deviceId}: ${e?.message ?? e}`)
+          }
+        },
+        moveToColorLogic: async (request: any) => {
+          try {
+            // MoveToColor gives colorX/colorY values; convert to approximate RGB by mapping to 0-255 scale
+            const colorX = request.colorX as number
+            const colorY = request.colorY as number
+            // Naive conversion: map X/Y into RGB via hue approximation (not colorimetrically accurate)
+            const hueApprox = Math.round((colorX / 65535) * 360)
+            const satApprox = Math.round((colorY / 65535) * 100)
+            const [r, g, b] = hs2rgb(hueApprox, satApprox)
+            if (connectionType === 'BLE' && this.switchBotBLE) {
+              await sendBLE('setRGB', Number(request.level ?? 100), r, g, b)
+            } else {
+              await sendOpenAPI('setColor', `${r}:${g}:${b}`)
+            }
+            await this.api.matter.updateAccessoryState(uuid, this.api.matter.clusterNames.ColorControl, { currentX: colorX, currentY: colorY })
+          } catch (e: any) {
+            this.log.error(`Failed to set XY color for ${dev.deviceId}: ${e?.message ?? e}`)
+          }
+        },
+      }
+
+      // color temperature — map to kelvin and send setColorTemperature
+      handlers.colorTemperature = {
+        moveToColorTemperature: async (request: any) => {
+          try {
+            const kelvin = Math.round(1000000 / Number(request.colorTemperature))
+            if (connectionType === 'BLE' && this.switchBotBLE) {
+              await sendBLE('setColorTemperature', kelvin)
+            } else {
+              await sendOpenAPI('setColorTemperature', `${kelvin}`)
+            }
+            await this.api.matter.updateAccessoryState(uuid, this.api.matter.clusterNames.ColorControl, { currentX: request.colorX ?? 0, currentY: request.colorY ?? 0 })
+          } catch (e: any) {
+            this.log.error(`Failed to set color temperature for ${dev.deviceId}: ${e?.message ?? e}`)
+          }
+        },
+      }
+    }
+
+    const opts = Object.assign({}, baseOpts, { handlers })
+
+    // Instantiate the device class and return its serialized accessory
+    const instance = new Ctor(this.api, this.log, opts)
+
+    // Register BLE->Matter push handler for this device's MAC (if BLE scanning is active)
+    try {
+      const mac = formatDeviceIdAsMac(dev.deviceId).toLowerCase()
+      // Handler receives advertisement/serviceData when BLE scan events arrive
+      this.bleEventHandler[mac] = async (serviceData?: any) => {
+        const uuidLocal = baseOpts.uuid
+
+        // First try model-specific / normalized parsing of BLE advertisement
+        try {
+          const parsed = this.parseAdvertisementForDevice(dev, serviceData)
+          if (parsed) {
+            // Power
+            if (parsed.power !== undefined) {
+              await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.OnOff, { onOff: Boolean(parsed.power) })
+            }
+
+            // Brightness
+            if (parsed.brightness !== undefined) {
+              const level = Math.round((Number(parsed.brightness) / 100) * 254)
+              await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.LevelControl, { currentLevel: level })
+            }
+
+            // Color
+            if (parsed.color !== undefined) {
+              const { r, g, b } = parsed.color
+              const [h, s] = rgb2hs(r, g, b)
+              await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.ColorControl, { currentHue: Math.round((h / 360) * 254), currentSaturation: Math.round((s / 100) * 254) })
+            }
+
+            // If we parsed something from serviceData prefer it and return early
+            if (serviceData) {
+              return
+            }
+          }
+        } catch (e: any) {
+          this.log.debug(`BLE advertisement parsing failed for ${dev.deviceId}: ${e?.message ?? e}`)
+        }
+
+        // Fallback to OpenAPI getDeviceStatus when serviceData is not present or parsing failed
+        if (!this.switchBotAPI) {
+          return
+        }
+        try {
+          const { response, statusCode } = await this.switchBotAPI.getDeviceStatus(dev.deviceId, this.config.credentials?.token, this.config.credentials?.secret)
+          if (!(statusCode === 100 || statusCode === 200)) {
+            return
+          }
+          const respAny: any = response
+          const body = respAny?.body ?? respAny
+          const status = body?.status ?? body
+
+          // On/Off
+          if (status?.power !== undefined) {
+            const on = (String(status.power).toLowerCase() === 'on' || Number(status.power) === 1)
+            await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.OnOff, { onOff: on })
+          }
+
+          // Brightness
+          if (status?.brightness !== undefined) {
+            const level = Math.round((Number(status.brightness) / 100) * 254)
+            await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.LevelControl, { currentLevel: level })
+          }
+
+          // Color
+          if (status?.color !== undefined) {
+            const color = String(status.color)
+            let r = 0
+            let g = 0
+            let b = 0
+            if (color.includes(':')) {
+              const parts = color.split(':').map(Number)
+              ;[r, g, b] = parts
+            } else if (color.startsWith('#')) {
+              const hex = color.replace('#', '')
+              r = Number.parseInt(hex.substring(0, 2), 16)
+              g = Number.parseInt(hex.substring(2, 4), 16)
+              b = Number.parseInt(hex.substring(4, 6), 16)
+            }
+            const [h, s] = rgb2hs(r, g, b)
+            await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.ColorControl, { currentHue: Math.round((h / 360) * 254), currentSaturation: Math.round((s / 100) * 254) })
+          }
+        } catch (e: any) {
+          this.log.debug(`BLE push handler failed for ${dev.deviceId}: ${e?.message ?? e}`)
+        }
+      }
+    } catch (e: any) {
+      this.log.debug(`Failed to register BLE handler for ${dev.deviceId}: ${e?.message ?? e}`)
+    }
+
+    return instance.toAccessory()
+  }
+
+  /**
+   * Discover devices via SwitchBot OpenAPI and cache them for later use
+   */
+  private async discoverDevices(): Promise<void> {
+    if (!this.switchBotAPI) {
+      this.log.debug('SwitchBot OpenAPI not configured; skipping discovery')
+      return
+    }
+
+    try {
+      const { response, statusCode } = await this.switchBotAPI.getDevices()
+      this.log.debug(`SwitchBot getDevices response status: ${statusCode}`)
+      if (statusCode === 100 || statusCode === 200) {
+        const deviceList = Array.isArray(response?.body?.deviceList) ? response.body.deviceList : []
+        this.discoveredDevices = deviceList
+        this.log.info(`Discovered ${deviceList.length} SwitchBot device(s) from OpenAPI`)
+        for (const d of deviceList) {
+          this.log.debug(`  - ${d.deviceName} (${d.deviceType}) id=${d.deviceId}`)
+        }
+      } else {
+        this.log.warn(`SwitchBot getDevices returned status ${statusCode}`)
+      }
+    } catch (e: any) {
+      this.log.error('Failed to discover SwitchBot devices:', e?.message ?? e)
+    }
+  }
+
+  /**
+   * Retry wrapper for control commands using SwitchBot OpenAPI
+   */
+  async retryCommand(deviceObj: device, bodyChange: bodyChange, maxRetries = 1, delayBetweenRetries = 1000): Promise<{ response: any, statusCode: number }> {
+    let retryCount = 0
+    while (retryCount < maxRetries) {
+      try {
+        if (!this.switchBotAPI) {
+          throw new Error('SwitchBot OpenAPI not initialized')
+        }
+        const { response, statusCode } = await this.switchBotAPI.controlDevice(
+          deviceObj.deviceId,
+          bodyChange.command,
+          bodyChange.parameter,
+          bodyChange.commandType as import('node-switchbot').commandType | undefined,
+          this.config.credentials?.token,
+          this.config.credentials?.secret,
+        )
+        return { response, statusCode }
+      } catch (e: any) {
+        this.log.debug(`retryCommand error: ${e?.message ?? e}`)
+      }
+      retryCount++
+
+      await sleep(delayBetweenRetries)
+    }
+    return { response: {}, statusCode: 500 }
+  }
+
+  /**
+   * Parse BLE advertisement/serviceData into normalized fields for a given device.
+   * Returns null when serviceData is falsy or parsing fails.
+   */
+  private parseAdvertisementForDevice(dev: device, serviceData?: any) {
+    if (!serviceData) {
+      return null
+    }
+    try {
+      const sd = serviceData
+      const result: any = {}
+
+      // Power/on state - supports multiple field names used by different models
+      const power = sd.power ?? sd.on ?? sd.p
+      if (power !== undefined) {
+        result.power = (String(power).toLowerCase() === 'on' || Number(power) === 1)
+      }
+
+      // Brightness (0-100)
+      const brightness = sd.brightness ?? sd.b
+      if (brightness !== undefined) {
+        result.brightness = Number(brightness)
+      }
+
+      // Color - could be 'r:g:b', '#rrggbb' or 'rrggbb'
+      const color = sd.color ?? sd.rgb ?? sd.c
+      if (color !== undefined) {
+        let r = 0
+        let g = 0
+        let b = 0
+        const c = String(color)
+        if (c.includes(':')) {
+          const parts = c.split(':').map(Number)
+          ;[r, g, b] = parts
+        } else if (c.startsWith('#')) {
+          const hex = c.replace('#', '')
+          r = Number.parseInt(hex.substring(0, 2), 16)
+          g = Number.parseInt(hex.substring(2, 4), 16)
+          b = Number.parseInt(hex.substring(4, 6), 16)
+        } else if (/^[0-9a-f]{6}$/i.test(c)) {
+          r = Number.parseInt(c.substring(0, 2), 16)
+          g = Number.parseInt(c.substring(2, 4), 16)
+          b = Number.parseInt(c.substring(4, 6), 16)
+        }
+        result.color = { r, g, b }
+      }
+
+      // Battery (some devices use battery or batt)
+      const battery = sd.battery ?? sd.batt
+      if (battery !== undefined) {
+        result.battery = Number(battery)
+      }
+
+      return result
+    } catch (e: any) {
+      this.log.debug(`parseAdvertisementForDevice failed for ${dev.deviceId}: ${e?.message ?? e}`)
+      return null
+    }
+  }
+
   /**
    * Required for DynamicPlatformPlugin
    * Called when homebridge restores cached accessories from disk at startup
@@ -123,7 +739,36 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     // Remove accessories that are disabled in config
     await this.removeDisabledAccessories()
 
-    // Register devices by Matter specification sections
+    // If we discovered real SwitchBot devices via OpenAPI, map and register them
+    if (this.discoveredDevices && this.discoveredDevices.length > 0) {
+      this.log.info(`Registering ${this.discoveredDevices.length} discovered SwitchBot device(s) as Matter accessories`)
+      const accessories: Array<MatterAccessory<Record<string, unknown>>> = []
+
+      // Merge device config (deviceConfig per deviceType and per-device overrides) to match HAP behavior
+      const devicesToProcess = await this.mergeDiscoveredDevices(this.discoveredDevices)
+
+      for (const dev of devicesToProcess) {
+        try {
+          const acc = await this.createAccessoryFromDevice(dev)
+          if (acc) {
+            accessories.push(acc)
+          }
+        } catch (e: any) {
+          this.log.error(`Failed to create Matter accessory for ${dev.deviceId}: ${e?.message ?? e}`)
+        }
+      }
+      if (accessories.length > 0) {
+        this.log.info(`✓ Registered ${accessories.length} discovered device(s)`)
+        for (const acc of accessories) {
+          this.log.info(`  - ${acc.displayName}`)
+        }
+        await this.api.matter.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, accessories)
+        return
+      }
+      this.log.info('No discovered devices were mapped to Matter accessories; falling back to example sections')
+    }
+
+    // Register example/demo devices by Matter specification sections
     await this.registerSection4Lighting()
     await this.registerSection5SmartPlugs()
     await this.registerSection6Switches()