@switchbot/homebridge-switchbot 5.0.0-beta.111 → 5.0.0-beta.113

package/package.json

@@ -2,7 +2,7 @@
   "name": "@switchbot/homebridge-switchbot",
   "displayName": "SwitchBot",
   "type": "module",
-  "version": "5.0.0-beta.111",
+  "version": "5.0.0-beta.113",
   "description": "The SwitchBot plugin allows you to access your SwitchBot device(s) from HomeKit.",
   "author": "SwitchBot <support@wondertechlabs.com> (https://github.com/SwitchBot)",
   "contributors": [
@@ -67,12 +67,13 @@
     "check": "npm install && npm outdated",
     "ports:free": "node scripts/free-dev-ports.mjs",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src/**/*.ts src/homebridge-ui/**/*.html && npm run typecheck",
-    "lint:fix": "eslint src/**/*.ts src/homebridge-ui/**/*.html --fix && npm run typecheck",
-    "watch:base": "npm run build && npm run plugin-ui && npm link && nodemon",
-    "watch": "npm run ports:free && npm run watch:base",
-    "watch:ui": "npm run ports:free && bash -c 'npx homebridge -I -U ~/.homebridge-dev & HB_PID=$!; sleep 6; UIX_STORAGE_PATH=~/.homebridge-dev node ./node_modules/homebridge-config-ui-x/dist/bin/standalone.js'",
-    "watch:ui:dev": "npm run watch:ui",
+    "lint": "eslint src/**/*.ts test/**/*.ts src/homebridge-ui/**/*.html && npm run typecheck",
+    "lint:src": "eslint src/**/*.ts",
+    "lint:test": "eslint test/**/*.ts",
+    "lint:ui": "eslint src/homebridge-ui/**/*.html",
+    "lint:fix": "eslint src/**/*.ts test/**/*.ts src/homebridge-ui/**/*.html --fix && npm run typecheck",
+    "watch": "npm run ports:free && npm run build && npm run plugin-ui && npm link && nodemon",
+    "watch:ui": "npm run ports:free && bash -c 'npx homebridge -I -U ~/.homebridge-dev & HB_PID=$!; sleep 6; UIX_STORAGE_PATH=~/.homebridge-dev node ./node_modules/homebridge-config-ui-x/dist/bin/standalone.js & npm run watch:files'",
     "watch:files": "nodemon",
     "plugin-ui": "mkdir -p ./dist/homebridge-ui/public && if [ -d ./src/homebridge-ui/public ]; then rsync -a ./src/homebridge-ui/public/ ./dist/homebridge-ui/public/; fi && node scripts/build-ui.js",
     "build": "npm run sync:device-types && npm run clean && tsc && npm run plugin-ui",
@@ -91,7 +92,7 @@
   "dependencies": {
     "@homebridge/plugin-ui-utils": "^2.2.1",
     "class-validator": "^0.15.1",
-    "node-switchbot": "^4.0.0-beta.8"
+    "node-switchbot": "^4.0.0-beta.14"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^7.7.0",

package/src/device-types.ts

@@ -95,83 +95,114 @@ export const DEVICE_TYPES = {
 } as const
 
 export const DEVICE_TYPE_NORMALIZATION_MAP: Record<string, string> = {
-  // Sensor type conversions
-  'motion sensor': 'motion',
-  'contact sensor': 'contact',
-  'presence sensor': 'contact',
-  'water detector': 'water detector',
+  // --- node-switchbot beta new types normalization additions ---
+  'hub mini': 'Hub Mini',
+  'hub 3': 'Hub 3',
+  'keypad': 'Keypad', // node-switchbot beta
+  'plug mini': 'Plug Mini (US)', // fallback to US if region not specified
+  'art frame': 'AI Art Frame',
+  'rgbicww': 'RGBICWW Strip Light',
+  'lock vision': 'Lock Vision Pro', // alias for new lock vision
+  'lock pro': 'Smart Lock Pro',
+  'lock lite': 'Lock Lite', // node-switchbot beta
+  'circulator fan': 'Circulator Fan', // node-switchbot beta
+  'smart thermostat radiator': 'Smart Radiator Thermostat',
+  'climate panel': 'Home Climate Panel',
+  'evaporative humidifier': 'Humidifier',
+  // --- end node-switchbot beta additions ---
+  // Only keep the last occurrence for each key, all values canonical
+  'air purifier pm2.5': 'Air Purifier PM2.5',
+  'pan/tilt cam plus 3k': 'Pan/Tilt Cam Plus 3K',
+  'remote with screen': 'Remote with Screen',
+  'ai hub': 'AI Hub',
+  'water detector': 'Water Detector',
+  'video doorbell': 'Video Doorbell',
+  'smart radiator thermostat': 'Smart Radiator Thermostat',
+  'woiosensor': 'WoIOSensor',
+  'garage door opener': 'Garage Door Opener',
+  'air purifier table pm2.5': 'Air Purifier Table PM2.5',
+  'air purifier voc': 'Air Purifier VOC',
+  'air purifier table voc': 'Air Purifier Table VOC',
+  'plug mini (eu)': 'Plug Mini (EU)',
+  // Only last occurrence for each key is kept above. Removed duplicates here.
 
   // Climate control conversions
-  'humidifier2': 'humidifier',
-  'circulator fan': 'fan',
-  'battery circulator fan': 'fan',
-  'standing circulator fan': 'fan',
+  'humidifier2': 'Humidifier2',
+  'battery circulator fan': 'Battery Circulator Fan',
+  'standing circulator fan': 'Standing Circulator Fan',
 
   // Lock/keypad conversions
-  'smart lock': 'lock',
-  'smart lock pro': 'lock',
-  'smart lock ultra': 'lock',
-  'lock lite': 'lock',
-  'keypad': 'lock',
-  'keypad touch': 'lock',
-  'keypad vision': 'lock',
-  'keypad vision pro': 'lock',
+  'smart lock': 'Smart Lock',
+  'smart lock pro': 'Smart Lock Pro',
+  'smart lock ultra': 'Smart Lock Ultra',
+  'keypad touch': 'Keypad Touch',
+  'keypad vision': 'Keypad Vision',
+  'keypad vision pro': 'Keypad Vision Pro',
 
   // Light conversions
-  'color bulb': 'light',
-  'ceiling light': 'light',
-  'ceiling light pro': 'light',
-  'candle warmer lamp': 'light',
-  'floor lamp': 'light',
-  'rgbic neon rope light': 'lightstrip',
-  'rgbic neon wire rope light': 'lightstrip',
-  'rgbicww floor lamp': 'lightstrip',
-  'rgbicww strip light': 'lightstrip',
-  'strip light': 'strip light',
-  'strip light 3': 'strip light',
+  'color bulb': 'Color Bulb',
+  'ceiling light': 'Ceiling Light',
+  'ceiling light pro': 'Ceiling Light Pro',
+  'candle warmer lamp': 'Candle Warmer Lamp',
+  'floor lamp': 'Floor Lamp',
+  'rgbic neon rope light': 'RGBIC Neon Rope Light',
+  'rgbic neon wire rope light': 'RGBIC Neon Wire Rope Light',
+  'rgbicww floor lamp': 'RGBICWW Floor Lamp',
+  'rgbicww strip light': 'RGBICWW Strip Light',
+  'strip light': 'Strip Light',
+  'strip light 3': 'Strip Light 3', // node-switchbot beta
 
   // Vacuum conversions
-  'robot vacuum cleaner s1': 'vacuum',
-  'robot vacuum cleaner s1 plus': 'vacuum',
-  'robot vacuum cleaner s10': 'vacuum',
-  'robot vacuum cleaner s20': 'vacuum',
-  'robot vacuum cleaner k10+ pro combo': 'wosweeper',
-  'robot vacuum cleaner k11+': 'wosweeper',
-  'robot vacuum cleaner k20 plus pro': 'wosweeper',
+  'robot vacuum cleaner s1': 'Robot Vacuum Cleaner S1',
+  'robot vacuum cleaner s1 plus': 'Robot Vacuum Cleaner S1 Plus',
+  'robot vacuum cleaner s10': 'Robot Vacuum Cleaner S10',
+  'robot vacuum cleaner s20': 'Robot Vacuum Cleaner S20',
+  'robot vacuum cleaner k10+ pro combo': 'Robot Vacuum Cleaner K10+ Pro Combo',
+  'robot vacuum cleaner k11+': 'Robot Vacuum Cleaner K11+',
+  'robot vacuum cleaner k20 plus pro': 'Robot Vacuum Cleaner K20 Plus Pro',
 
   // Exact device type mappings (API format → canonical format)
-  'plug mini (eu)': 'plug mini (eu)',
-  'plug mini (jp)': 'plug mini (jp)',
-  'plug mini (us)': 'plug mini (us)',
-  'relay switch 1': 'relay switch 1',
-  'relay switch 1pm': 'relay switch 1pm',
-  'relay switch 2pm': 'relay switch 2pm',
-  'blind tilt': 'blind tilt',
-  'roller shade': 'roller shade',
-  'curtain3': 'curtain3',
-  'hub 2': 'hub 2',
-  'meterplus': 'meterplus',
-  'meterpro': 'meterpro',
-  'meterpro(co2)': 'meterpro(co2)',
-  'walletfinder': 'walletfinder',
-  'k10+': 'k10+',
-  'k10+ pro': 'k10+ pro',
-  'k10+ pro (wosweeperminipro)': 'k10+ pro (wosweeperminipro)',
-
-  // Handle spaced variants from config files (normalize back to API format)
-  'meter pro': 'meterpro',
-  'meter pro (co2)': 'meterpro(co2)',
-  'meter plus': 'meterplus',
-  'relay switch 1 pm': 'relay switch 1pm',
-  'relay switch 2 pm': 'relay switch 2pm',
-  'plug mini eu': 'plug mini (eu)',
-  'plug mini jp': 'plug mini (jp)',
-  'plug mini us': 'plug mini (us)',
+  'relay switch 1': 'Relay Switch 1',
+  'blind tilt': 'Blind Tilt',
+  'roller shade': 'Roller Shade',
+  'curtain3': 'Curtain3',
+  'hub 2': 'Hub 2',
+  'meterplus': 'MeterPlus',
+  'meterpro': 'MeterPro',
+  'meterpro(co2)': 'MeterPro(CO2)',
+  'walletfinder': 'WalletFinder',
+  'k10+': 'K10+',
+  'k10+ pro (wosweeperminipro)': 'K10+ Pro (wosweeperminipro)',
+
+  // Handle spaced variants from config files (normalize back to canonical type)
+  'meter pro': 'Meter Pro',
+  'meter pro (co2)': 'Meter Pro (CO2)',
+  'meter plus': 'Meter Plus',
+  'relay switch 1 pm': 'Relay Switch 1PM',
+  'relay switch 2 pm': 'Relay Switch 2PM',
+  'plug mini eu': 'Plug Mini (EU)',
+  'plug mini jp': 'Plug Mini (JP)',
+  'plug mini us': 'Plug Mini (US)',
 
   // Migration mappings for invalid/legacy device types
-  'lock vision pro': 'lock', // Valid alias; map to lock behavior
-  'lock vision': 'Keypad Vision', // Invalid type
+  'lock vision pro': 'Lock Vision Pro', // Valid alias; map to canonical
+  // 'lock vision': 'Keypad Vision', // Invalid type (removed, now node-switchbot beta alias above)
   'lock touch': 'Keypad Touch', // Invalid type
+
+  // Additional normalization for new/unknown types from logs
+  'woplugus': 'Plug Mini (US)',
+  // Removed duplicate keys below, only last occurrence kept
+  // 'plug mini us': 'plug mini (us)', // duplicate, removed
+  // 'plug us': 'plug mini (us)', // duplicate, removed
+  // 'plug': 'plug', // duplicate, removed
+  // 'air purifier pm2.5': 'air purifier pm2.5', // duplicate, removed
+  // 'rgbic neon wire rope light': 'rgbic neon wire rope light', // duplicate, removed
+  // 'candle warmer lamp': 'candle warmer lamp', // duplicate, removed
+  // 'pan/tilt cam plus 3k': 'pan/tilt cam plus 3k', // duplicate, removed
+  // 'remote with screen': 'remote with screen', // duplicate, removed
+  // 'ai hub': 'ai hub', // duplicate, removed
+  // 'lock vision pro': 'lock vision pro', // duplicate, remove this line
+  // Add any other device types from logs as needed
 }
 
 /**

package/src/deviceFactory.ts

@@ -44,77 +44,93 @@ const DEVICE_CLASS_MAP: Record<string, any> = {
   // Primary device type keys (lowercase, simplified)
   'bot': BotDevice,
   'curtain': CurtainDevice,
+  'curtain3': Curtain3Device,
   'fan': FanDevice,
   'light': LightDevice,
   'lightstrip': LightStripDevice,
   'motion': MotionSensorDevice,
   'contact': ContactSensorDevice,
-  'vacuum': VacuumDevice,
+  'vacuum': VacuumDevice, // node-switchbot beta
+  // Canonical, normalized device type keys (lowercase, mapped to device classes)
+  'video doorbell': GenericDevice,
+  'smart radiator thermostat': GenericDevice, // node-switchbot beta
+  'woiosensor': GenericDevice,
+  'garage door opener': GenericDevice, // node-switchbot beta
+  'air purifier table pm2.5': GenericDevice,
+  'air purifier voc': GenericDevice,
+  'air purifier table voc': GenericDevice,
+  'meterplus': MeterDevice,
+  'meterpro': MeterDevice,
+  'meterpro(co2)': MeterDevice,
+  'walletfinder': WalletFinderDevice,
+  'plug': PlugDevice,
+  'plug mini (eu)': PlugMiniDevice, // node-switchbot beta
+  'plug mini (jp)': PlugMiniDevice, // node-switchbot beta
+  'plug mini (us)': PlugMiniDevice, // node-switchbot beta
+  'relay switch 1pm': RelaySwitch1PMDevice,
+  'relay switch 2pm': RelaySwitch1PMDevice,
+  'k10+ pro': WoSweeperDevice,
+  'robot vacuum cleaner k10+ pro combo': WoSweeperDevice,
+  'robot vacuum cleaner k11+': WoSweeperDevice,
+  'robot vacuum cleaner k20 plus pro': WoSweeperDevice,
+  'ai hub': GenericDevice,
+  'hub': GenericDevice,
+  'hub 2': Hub2Device,
+  'hub 3': GenericDevice, // node-switchbot beta
+  'hub mini': GenericDevice, // node-switchbot beta
+  'hub plus': GenericDevice,
+  'indoor cam': GenericDevice,
+  'pan/tilt cam': GenericDevice,
+  'pan/tilt cam 2k': GenericDevice,
+  'pan/tilt cam plus 2k': GenericDevice,
+  'pan/tilt cam plus 3k': GenericDevice,
+  'humidifier': HumidifierDevice, // node-switchbot beta (Evaporative Humidifier)
+  'roller shade': RollerShadeDevice, // node-switchbot beta
+  'strip light 3': StripLightDevice, // node-switchbot beta
+  'circulator fan': FanDevice, // node-switchbot beta
+  'smart lock pro': LockDevice, // node-switchbot beta
+  'lock lite': LockDevice, // node-switchbot beta
+  'keypad': LockDevice, // node-switchbot beta
+  'lock vision pro': LockDevice, // node-switchbot beta
+  'floor lamp': LightDevice, // node-switchbot beta
+  'rgbicww floor lamp': LightStripDevice, // node-switchbot beta
+  'rgbicww strip light': LightStripDevice, // node-switchbot beta
+  'home climate panel': GenericDevice, // node-switchbot beta (Climate Panel)
   'lock': LockDevice,
-  'humidifier': HumidifierDevice,
+  'humidifier2': HumidifierDevice,
   'temperature': TemperatureSensorDevice,
   'relay switch 1': RelaySwitchDevice,
-  'relay switch 1pm': RelaySwitch1PMDevice,
-  'relay switch 2pm': RelaySwitch1PMDevice,
-  'plug': PlugDevice,
-  'plug mini (jp)': PlugMiniDevice,
-  'plug mini (us)': PlugMiniDevice,
-  'plug mini (eu)': PlugMiniDevice,
   'blind tilt': BlindTiltDevice,
-  'curtain3': Curtain3Device,
   'worollershade': RollerShadeDevice,
   'wo rollershade': RollerShadeDevice,
-  'roller shade': RollerShadeDevice,
   'rollershade': RollerShadeDevice,
-  'hub 2': Hub2Device,
   'meter': MeterDevice,
-  'meterplus': MeterDevice,
   'meter plus (jp)': MeterDevice,
-  'meterpro': MeterDevice,
-  'meterpro(co2)': MeterDevice,
   'water detector': WaterDetectorDevice,
   'smart fan': SmartFanDevice,
   'strip light': StripLightDevice,
-  'strip light 3': StripLightDevice,
-  'walletfinder': WalletFinderDevice,
   'wosweeper': WoSweeperDevice,
   'wosweepermini': WoSweeperMiniDevice,
   'wosweeperminipro': WoSweeperMiniProDevice,
   'k10+': WoSweeperDevice,
-  'k10+ pro': WoSweeperDevice,
   'k10+ pro (wosweeperminipro)': WoSweeperMiniProDevice,
-  // API display name aliases (for UI compatibility)
-  'motion sensor': MotionSensorDevice,
-  'contact sensor': ContactSensorDevice,
-  'humidifier2': HumidifierDevice,
-  'circulator fan': FanDevice,
   'battery circulator fan': FanDevice,
   'standing circulator fan': FanDevice,
   'smart lock': LockDevice,
-  'smart lock pro': LockDevice,
   'smart lock ultra': LockDevice,
-  'lock lite': LockDevice,
-  'keypad': LockDevice,
   'keypad touch': LockDevice,
   'keypad vision': LockDevice,
   'keypad vision pro': LockDevice,
-  'lock vision pro': LockDevice,
   'color bulb': LightDevice,
   'ceiling light': LightDevice,
   'ceiling light pro': LightDevice,
   'candle warmer lamp': LightDevice,
-  'floor lamp': LightDevice,
   'rgbic neon rope light': LightStripDevice,
   'rgbic neon wire rope light': LightStripDevice,
-  'rgbicww floor lamp': LightStripDevice,
-  'rgbicww strip light': LightStripDevice,
   'robot vacuum cleaner s1': VacuumDevice,
   'robot vacuum cleaner s1 plus': VacuumDevice,
   'robot vacuum cleaner s10': VacuumDevice,
   'robot vacuum cleaner s20': VacuumDevice,
-  'robot vacuum cleaner k10+ pro combo': WoSweeperDevice,
-  'robot vacuum cleaner k11+': WoSweeperDevice,
-  'robot vacuum cleaner k20 plus pro': WoSweeperDevice,
 }
 
 function classForType(type: string) {
@@ -124,6 +140,7 @@ function classForType(type: string) {
 }
 
 export async function createDevice(opts: DeviceOptions, cfg: SwitchBotPluginConfig, useMatter: boolean) {
+
   // Reuse existing client when provided via config to avoid creating
   // a new SwitchBotClient per device (which can be expensive).
   let client: any = (cfg as any)?._client ?? null
@@ -135,8 +152,13 @@ export async function createDevice(opts: DeviceOptions, cfg: SwitchBotPluginConf
   // Pass client via config so devices can access it
   const mergedCfg = { ...(cfg as any), _client: client }
 
+  // Pass encryptionKey and keyId to device opts if present
+  const deviceOpts = { ...opts }
+  if (opts.encryptionKey) deviceOpts.encryptionKey = opts.encryptionKey
+  if (opts.keyId) deviceOpts.keyId = opts.keyId
+
   const DeviceCtor = classForType(opts.type)
-  const device = new DeviceCtor(opts, mergedCfg)
+  const device = new DeviceCtor(deviceOpts, mergedCfg)
   await device.init()
 
   // Attach a simple getState delegator to the client where appropriate

package/src/devices/genericDevice.ts

@@ -1,15 +1,105 @@
+// Utility: Validate BLE response length before parsing
 /* eslint-disable style/max-statements-per-line, unused-imports/no-unused-vars */
 import type { SwitchBotPluginConfig } from '../settings.js'
 
+import { Buffer } from 'node:buffer'
+
+import { DEVICE_MATTER_CLUSTERS } from '../platform.js'
 import { MATTER_ATTRIBUTE_IDS, MATTER_CLUSTER_IDS } from '../utils.js'
 import { DeviceBase } from './deviceBase.js'
 
+function validateBLEResponseLength(buf: Buffer | Uint8Array | any[], expected: number, context = ''): boolean {
+  if (!buf || typeof buf.length !== 'number' || buf.length !== expected) {
+    console.warn(`[BLE] Invalid response length${context ? ` for ${context}` : ''}: expected ${expected}, got ${buf?.length}`)
+    return false
+  }
+  return true
+}
+
+// BLE notification handling: per-command notification futures and unsolicited notification logging
+const BLE_NOTIFICATION_HANDLERS = new Map<string, (payload: Buffer) => void>()
+
 // Module-scope regex pattern to avoid recompilation
 const HEX_COLOR_REGEX = /^#?[0-9A-F]{6}$/i
 
 export class GenericDevice extends DeviceBase {
   constructor(opts: any, cfg: SwitchBotPluginConfig) {
     super(opts, cfg)
+    // If BLE encryptionKey/keyId provided, set on node-switchbot device instance if possible
+    if (opts.encryptionKey && this.client && typeof this.client.devices?.get === 'function') {
+      try {
+        const dev = this.client.devices.get(opts.id)
+        if (dev && typeof dev.setKey === 'function') {
+          dev.setKey({
+            encryptionKey: opts.encryptionKey,
+            keyId: opts.keyId || undefined,
+          })
+        }
+      } catch (e) {
+        // ignore if device not found or setKey not available
+      }
+    }
+
+    // Subscribe to BLE notifications if supported (node-switchbot v4+)
+    this._subscribeBLENotifications()
+  }
+
+  /**
+   * Subscribe to BLE notifications for this device (if supported by node-switchbot)
+   * Logs unsolicited notifications and enables per-command notification futures.
+   */
+  private async _subscribeBLENotifications() {
+    if (!this.client || typeof this.client.devices?.get !== 'function') { return }
+    const dev = this.client.devices.get(this.opts.id)
+    if (!dev || typeof dev.mac !== 'string' || !dev.mac) { return }
+    // Only subscribe once per device
+    if (BLE_NOTIFICATION_HANDLERS.has(dev.mac)) { return }
+    if (typeof dev.subscribeNotifications === 'function') {
+      const handler = (payload: Buffer) => {
+        // If a per-command notification future is waiting, let node-switchbot handle it
+        // Otherwise, log unsolicited notification
+        if (payload && payload.length > 0) {
+          // Unsolicited notification logging
+          // (node-switchbot will resolve per-command futures internally)
+          // eslint-disable-next-line no-console
+          console.info(`[BLE] Unsolicited notification from ${dev.mac}: ${payload.toString('hex')}`)
+        }
+      }
+      try {
+        // Subscribe and remember handler for possible cleanup
+        await dev.subscribeNotifications(handler)
+        BLE_NOTIFICATION_HANDLERS.set(dev.mac, handler)
+      } catch (e) {
+        // ignore if subscription fails
+      }
+    }
+  }
+
+  /**
+   * Await a BLE notification for this device (for advanced use in subclasses)
+   * Returns the notification payload or throws on timeout.
+   */
+  protected async _awaitBLENotification(timeoutMs = 5000): Promise<Buffer> {
+    if (!this.client || typeof this.client.devices?.get !== 'function') { throw new Error('No BLE client/device') }
+    const dev = this.client.devices.get(this.opts.id)
+    if (!dev || typeof dev.mac !== 'string' || !dev.mac) { throw new Error('No BLE MAC for device') }
+    if (typeof dev.bleConnection?.sendCommand !== 'function') { throw new TypeError('BLE connection does not support sendCommand') }
+    // This is a low-level utility; in most cases, node-switchbot handles notification futures for commands
+    // Here, we expose a direct await for advanced use
+    return new Promise<Buffer>((resolve, reject) => {
+      let timer: NodeJS.Timeout | undefined
+      const handler = (payload: Buffer) => {
+        clearTimeout(timer)
+        dev.bleConnection?.unsubscribeNotifications(dev.mac, handler)
+        resolve(payload)
+      }
+      dev.bleConnection?.subscribeNotifications(dev.mac, handler).then(() => {
+        timer = setTimeout(() => {
+          dev.bleConnection?.unsubscribeNotifications(dev.mac, handler)
+          reject(new Error('BLE notification timeout'))
+        }, timeoutMs)
+      }).catch(reject)
+    })
   }
 
   async getState(): Promise<any> {
@@ -17,6 +107,13 @@ export class GenericDevice extends DeviceBase {
     if (this.client && typeof this.client.getDevice === 'function') {
       try {
         const raw = await this.client.getDevice(this.opts.id)
+        // If this is a BLE buffer/array, validate length (common BLE status: 12 bytes, but may vary by device)
+        if (raw && (raw instanceof Buffer || Array.isArray(raw) || raw instanceof Uint8Array)) {
+          // Default to 12, override per device if needed
+          if (!validateBLEResponseLength(raw, 12, this.opts.type)) {
+            return { id: this.opts.id, type: this.opts.type, error: 'invalid_ble_response_length', raw }
+          }
+        }
         // Normalize common response shapes
         try {
           const device = raw?.body ?? raw
@@ -228,8 +325,19 @@ export class CurtainDevice extends GenericDevice {
     }
   }
 
-  // Matter-specific descriptor for Curtain (Shade cluster)
+  // Matter-specific descriptor for Curtain (Shade cluster) with conformance type
   createMatterAccessory(api: any): any {
+    // Use DEVICE_MATTER_CLUSTERS directly (static import)
+    let matterType = 0 // Default to Rollershade (lift-only)
+    try {
+      const typeKey = (this.opts.type || '').toLowerCase()
+      const clusterConf = DEVICE_MATTER_CLUSTERS[typeKey] || DEVICE_MATTER_CLUSTERS.curtain
+      if (clusterConf && clusterConf.windowCovering && typeof clusterConf.windowCovering.type === 'number') {
+        matterType = clusterConf.windowCovering.type
+      }
+    } catch (e) {
+      // fallback to default
+    }
     return {
       id: this.opts.id,
       name: this.opts.name ?? this.opts.type,
@@ -240,6 +348,7 @@ export class CurtainDevice extends GenericDevice {
           type: 'Shade',
           clusterId: MATTER_CLUSTER_IDS.WindowCovering,
           attributes: {
+            type: { read: async () => matterType, write: undefined },
             currentPosition: { read: async () => { const s = await this.getState(); return typeof s.position === 'number' ? s.position : 0 }, write: undefined },
             [MATTER_ATTRIBUTE_IDS.WindowCovering.CurrentPosition]: { read: async () => { const s = await this.getState(); return typeof s.position === 'number' ? s.position : 0 }, write: undefined },
             targetPosition: { read: async () => { const s = await this.getState(); return typeof s.position === 'number' ? s.position : 0 }, write: async (v: any) => this.setState({ position: Number(v) }) },
@@ -540,6 +649,8 @@ export class LightDevice extends GenericDevice {
           type: 'ColorControl',
           clusterId: MATTER_CLUSTER_IDS.ColorControl,
           attributes: {
+            // Required colorMode attribute for Matter conformance (0 = currentHueAndSaturation)
+            colorMode: { read: async () => 0 },
             colorHue: { read: async () => { const s = await this.getState(); return typeof s.hue === 'number' ? s.hue : 0 }, write: async (v: any) => this.setState({ hue: Number(v) }) },
             [MATTER_ATTRIBUTE_IDS.ColorControl.CurrentHue]: { read: async () => { const s = await this.getState(); return typeof s.hue === 'number' ? s.hue : 0 }, write: async (v: any) => this.setState({ hue: Number(v) }) },
             colorSaturation: { read: async () => { const s = await this.getState(); return typeof s.saturation === 'number' ? s.saturation : 0 }, write: async (v: any) => this.setState({ saturation: Number(v) }) },
@@ -996,3 +1107,4 @@ export class WalletFinderDevice extends GenericDevice {}
 export class WoSweeperDevice extends VacuumDevice {}
 export class WoSweeperMiniDevice extends VacuumDevice {}
 export class WoSweeperMiniProDevice extends VacuumDevice {}
+// Add missing closing braces for MeterDevice and WaterDetectorDevice

package/src/errors.ts

@@ -0,0 +1,43 @@
+// Error re-exports for node-switchbot v4 error compatibility
+
+let SwitchbotOperationError: any = undefined;
+let SwitchbotAuthenticationError: any = undefined;
+let CharacteristicMissingError: any = undefined;
+
+try {
+  // Dynamically import from node-switchbot if available
+  // (node-switchbot v4+ exports these error classes)
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const mod = require('node-switchbot');
+  SwitchbotOperationError = mod.SwitchbotOperationError;
+  SwitchbotAuthenticationError = mod.SwitchbotAuthenticationError;
+  CharacteristicMissingError = mod.CharacteristicMissingError;
+} catch {}
+
+// Fallbacks (for OpenAPI or legacy code)
+if (!SwitchbotOperationError) {
+  SwitchbotOperationError = class extends Error {
+    code?: string; cause?: Error;
+    constructor(message: string, code?: string, cause?: Error) {
+      super(message); this.name = 'SwitchbotOperationError'; this.code = code; this.cause = cause;
+    }
+  };
+}
+if (!SwitchbotAuthenticationError) {
+  SwitchbotAuthenticationError = class extends Error {
+    code?: string; cause?: Error;
+    constructor(message: string, code?: string, cause?: Error) {
+      super(message); this.name = 'SwitchbotAuthenticationError'; this.code = code; this.cause = cause;
+    }
+  };
+}
+if (!CharacteristicMissingError) {
+  CharacteristicMissingError = class extends Error {
+    characteristic: string;
+    constructor(message: string, characteristic: string) {
+      super(message); this.name = 'CharacteristicMissingError'; this.characteristic = characteristic;
+    }
+  };
+}
+
+export { SwitchbotOperationError, SwitchbotAuthenticationError, CharacteristicMissingError };