@switchbot/homebridge-switchbot 5.0.0-beta.9 → 5.0.0-beta.91

package/src/devices/genericDevice.ts

@@ -0,0 +1,965 @@
+/* eslint-disable style/max-statements-per-line, unused-imports/no-unused-vars */
+import type { SwitchBotPluginConfig } from '../settings.js'
+
+import { MATTER_ATTRIBUTE_IDS, MATTER_CLUSTER_IDS } from '../utils.js'
+import { DeviceBase } from './deviceBase.js'
+
+export class GenericDevice extends DeviceBase {
+  constructor(opts: any, cfg: SwitchBotPluginConfig) {
+    super(opts, cfg)
+  }
+
+  async getState(): Promise<any> {
+    // Default: return minimal info; implementations should override
+    if (this.client && typeof this.client.getDevice === 'function') {
+      try {
+        const raw = await this.client.getDevice(this.opts.id)
+        // Normalize common response shapes
+        try {
+          const device = raw?.body ?? raw
+          return device
+        } catch (e) {
+          return raw
+        }
+      } catch (e) {
+        // ignore and fallback
+      }
+    }
+    return { id: this.opts.id, type: this.opts.type }
+  }
+
+  async setState(change: any): Promise<any> {
+    // Apply change via SwitchBot API in real implementation
+    // Translate common high-level changes into SwitchBot OpenAPI commands
+    if (!this.client) {
+      return { success: false, reason: 'no client', change }
+    }
+
+    const cmdBody: any = {}
+
+    if (typeof change.on === 'boolean') {
+      cmdBody.command = change.on ? 'turnOn' : 'turnOff'
+      cmdBody.parameter = 'default'
+      cmdBody.commandType = 'command'
+    } else if (typeof change.brightness === 'number') {
+      const v = Math.max(0, Math.min(100, Number(change.brightness)))
+      cmdBody.command = 'setBrightness'
+      cmdBody.parameter = String(v)
+      cmdBody.commandType = 'command'
+    } else if (typeof change.speed === 'number') {
+      const v = Math.max(0, Math.min(100, Number(change.speed)))
+      cmdBody.command = 'setFanSpeed'
+      cmdBody.parameter = String(v)
+      cmdBody.commandType = 'command'
+    } else if (typeof change.position === 'number') {
+      const v = Math.max(0, Math.min(100, Number(change.position)))
+      cmdBody.command = 'setPosition'
+      cmdBody.parameter = String(v)
+      cmdBody.commandType = 'command'
+    } else if (typeof change.locked === 'boolean') {
+      cmdBody.command = change.locked ? 'lock' : 'unlock'
+      cmdBody.parameter = 'default'
+      cmdBody.commandType = 'command'
+    } else if (typeof change.start === 'boolean') {
+      cmdBody.command = change.start ? 'start' : 'stop'
+      cmdBody.parameter = 'default'
+      cmdBody.commandType = 'command'
+    } else {
+      // If caller supplied an explicit command body, pass through
+      if (change && typeof change.command === 'string') {
+        Object.assign(cmdBody, change)
+      } else {
+        // Fallback: send raw change to client setDeviceState
+        try {
+          if (typeof this.client.setDeviceState === 'function') {
+            return await this.client.setDeviceState(this.opts.id, change)
+          }
+          if (typeof this.client.sendCommand === 'function') {
+            return await this.client.sendCommand(this.opts.id, change)
+          }
+        } catch (err) {
+          const e = err as any
+          return { success: false, reason: e?.message ?? String(e) }
+        }
+        return { success: false, reason: 'unsupported change', change }
+      }
+    }
+
+    try {
+      return await this.client.setDeviceState(this.opts.id, cmdBody)
+    } catch (err) {
+      // try alternative client API if available
+      try {
+        if (typeof this.client.sendCommand === 'function') {
+          return await this.client.sendCommand(this.opts.id, cmdBody)
+        }
+      } catch (e2) {
+        // ignore
+      }
+      const e = err as any
+      return { success: false, reason: e?.message ?? String(e) }
+    }
+  }
+
+  createHAPAccessory(api: any): any {
+    // Default HAP descriptor: a Switch service with On characteristic
+    return {
+      services: [
+        {
+          type: 'Switch',
+          characteristics: {
+            On: {
+              get: async () => {
+                const s = await this.getState()
+                return !!(s && (s.on === true || s.state === 'on' || s.power === 'on'))
+              },
+              set: async (v: any) => {
+                await this.setState({ on: !!v })
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+
+  // Default Matter descriptor mirrors HAP descriptor structure so the
+  // platform can construct a Matter accessory representation when
+  // Homebridge Matter APIs are available. Device subclasses may override
+  // this to provide Matter-specific clusters/attributes if desired.
+  createMatterAccessory(api: any): any {
+    const hapDesc = this.createHAPAccessory(api)
+
+    const clusters: any[] = []
+    const mapCharacteristic = (charName: string) => {
+      switch (charName) {
+        case 'On':
+          return { attr: 'onOff', get: async () => { const s = await this.getState(); return !!(s && (s.on === true || s.state === 'on' || s.power === 'on')) }, set: async (v: any) => this.setState({ on: !!v }) }
+        case 'Brightness':
+          return { attr: 'brightness', get: async () => { const s = await this.getState(); return typeof s.brightness === 'number' ? s.brightness : 100 }, set: async (v: any) => this.setState({ brightness: Number(v) }) }
+        case 'Hue':
+          return { attr: 'colorHue', get: async () => { const s = await this.getState(); return typeof s.hue === 'number' ? s.hue : 0 }, set: async (v: any) => this.setState({ hue: Number(v) }) }
+        case 'Saturation':
+          return { attr: 'colorSaturation', get: async () => { const s = await this.getState(); return typeof s.saturation === 'number' ? s.saturation : 0 }, set: async (v: any) => this.setState({ saturation: Number(v) }) }
+        case 'ColorTemperature':
+          return { attr: 'colorTemperature', get: async () => {
+            const s = await this.getState(); if (typeof s.colorTemperature === 'number') { return s.colorTemperature } if (typeof s.kelvin === 'number') { return Math.round(1000000 / s.kelvin) } return 400
+          }, set: async (v: any) => this.setState({ colorTemperature: Number(v) }) }
+        case 'RotationSpeed':
+          return { attr: 'rotationSpeed', get: async () => { const s = await this.getState(); return typeof s.speed === 'number' ? s.speed : 0 }, set: async (v: any) => this.setState({ speed: Number(v) }) }
+        case 'TargetPosition':
+        case 'CurrentPosition':
+          return { attr: 'position', get: async () => { const s = await this.getState(); return typeof s.position === 'number' ? s.position : 0 }, set: async (v: any) => this.setState({ position: Number(v) }) }
+        case 'LockCurrentState':
+        case 'LockTargetState':
+          return { attr: 'locked', get: async () => { const s = await this.getState(); return !!(s && s.locked) }, set: async (v: any) => this.setState({ locked: !!v }) }
+        case 'MotionDetected':
+          return { attr: 'motionDetected', get: async () => { const s = await this.getState(); return !!(s && s.motion === true) }, set: undefined }
+        case 'ContactSensorState':
+          return { attr: 'contact', get: async () => { const s = await this.getState(); return s && s.open ? 1 : 0 }, set: undefined }
+        default:
+          return null
+      }
+    }
+
+    for (const s of (hapDesc.services || [])) {
+      const clusterType = (() => {
+        switch ((s.type || '').toLowerCase()) {
+          case 'lightbulb': return 'OnOff/LevelControl/ColorControl'
+          case 'fan': return 'FanControl'
+          case 'windowscovering': return 'Shade'
+          case 'motionsensor': return 'OccupancySensing'
+          case 'contactsensor': return 'DoorState'
+          case 'lockmechanism': return 'DoorLock'
+          case 'switch': return 'OnOff'
+          default: return s.type || 'Generic'
+        }
+      })()
+
+      const attributes: Record<string, any> = {}
+      for (const [charName] of Object.entries(s.characteristics || {})) {
+        const mapped = mapCharacteristic(charName)
+        if (mapped) { attributes[mapped.attr] = { read: typeof mapped.get === 'function' ? mapped.get : undefined, write: typeof mapped.set === 'function' ? mapped.set : undefined } }
+      }
+
+      clusters.push({ type: clusterType, attributes })
+    }
+
+    return {
+      id: this.opts.id,
+      name: this.opts.name ?? this.opts.type,
+      protocol: 'matter',
+      clusters,
+    }
+  }
+}
+
+// Specific device classes can extend GenericDevice for custom behavior.
+export class BotDevice extends GenericDevice {}
+
+export class CurtainDevice extends GenericDevice {
+  createHAPAccessory(api: any) {
+    return {
+      services: [
+        {
+          type: 'WindowCovering',
+          characteristics: {
+            CurrentPosition: {
+              get: async () => {
+                const s = await this.getState()
+                return typeof s.position === 'number' ? s.position : 0
+              },
+            },
+            TargetPosition: {
+              get: async () => {
+                const s = await this.getState()
+                return typeof s.position === 'number' ? s.position : 0
+              },
+              set: async (v: any) => {
+                await this.setState({ position: Number(v) })
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+
+  // Matter-specific descriptor for Curtain (Shade cluster)
+  createMatterAccessory(api: any): any {
+    return {
+      id: this.opts.id,
+      name: this.opts.name ?? this.opts.type,
+      protocol: 'matter',
+      clusters: [
+        {
+          // Shade cluster
+          type: 'Shade',
+          clusterId: MATTER_CLUSTER_IDS.WindowCovering,
+          attributes: {
+            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) }) },
+            [MATTER_ATTRIBUTE_IDS.WindowCovering.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) }) },
+          },
+        },
+      ],
+    }
+  }
+}
+
+export class FanDevice extends GenericDevice {
+  createHAPAccessory(api: any) {
+    return {
+      services: [
+        {
+          type: 'Fan',
+          characteristics: {
+            On: {
+              get: async () => {
+                const s = await this.getState()
+                return !!(s && (s.on === true || s.state === 'on'))
+              },
+              set: async (v: any) => {
+                await this.setState({ on: !!v })
+              },
+            },
+            RotationSpeed: {
+              get: async () => {
+                const s = await this.getState()
+                return typeof s.speed === 'number' ? s.speed : 0
+              },
+              set: async (v: any) => {
+                await this.setState({ speed: Number(v) })
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+
+  async setState(change: any): Promise<any> {
+    if (!this.client) { return { success: false, reason: 'no client' } }
+
+    // Oscillation support
+    if (typeof change.oscillate === 'boolean') {
+      const body = { command: 'setOscillation', parameter: change.oscillate ? 'on' : 'off', commandType: 'command' }
+      try {
+        return await this.client.setDeviceState(this.opts.id, body)
+      } catch (err) {
+        try {
+          if (typeof this.client.sendCommand === 'function') { return await this.client.sendCommand(this.opts.id, body) }
+        } catch (e) {}
+        const e = err as any
+        return { success: false, reason: e?.message ?? String(e) }
+      }
+    }
+
+    // Swing / sweep support (angle or mode)
+    if (change && (typeof change.swing === 'boolean' || typeof change.swingAngle === 'number' || typeof change.swingMode === 'string')) {
+      let param: string = 'default'
+      if (typeof change.swingMode === 'string') { param = change.swingMode } else if (typeof change.swingAngle === 'number') { param = String(Number(change.swingAngle)) } else {
+        param = change.swing ? 'on' : 'off'
+      }
+
+      const body = { command: 'setSwing', parameter: param, commandType: 'command' }
+      try {
+        return await this.client.setDeviceState(this.opts.id, body)
+      } catch (err) {
+        try {
+          if (typeof this.client.sendCommand === 'function') { return await this.client.sendCommand(this.opts.id, body) }
+        } catch (e) {}
+        const e = err as any
+        return { success: false, reason: e?.message ?? String(e) }
+      }
+    }
+
+    return super.setState(change)
+  }
+
+  // Matter-specific descriptor for Fan
+  createMatterAccessory(api: any): any {
+    return {
+      id: this.opts.id,
+      name: this.opts.name ?? this.opts.type,
+      protocol: 'matter',
+      clusters: [
+        {
+          // OnOff cluster
+          type: 'OnOff',
+          clusterId: MATTER_CLUSTER_IDS.OnOff,
+          attributes: {
+            onOff: { read: async () => { const s = await this.getState(); return !!(s && (s.on === true || s.state === 'on')) }, write: async (v: any) => this.setState({ on: !!v }) },
+            // numeric attribute id for onOff
+            [MATTER_ATTRIBUTE_IDS.OnOff.OnOff]: { read: async () => { const s = await this.getState(); return !!(s && (s.on === true || s.state === 'on')) }, write: async (v: any) => this.setState({ on: !!v }) },
+          },
+        },
+        {
+          // Fan Control cluster
+          type: 'FanControl',
+          clusterId: MATTER_CLUSTER_IDS.FanControl,
+          attributes: {
+            rotationSpeed: { read: async () => { const s = await this.getState(); return typeof s.speed === 'number' ? s.speed : 0 }, write: async (v: any) => this.setState({ speed: Number(v) }) },
+            [MATTER_ATTRIBUTE_IDS.FanControl.SpeedCurrent]: { read: async () => { const s = await this.getState(); return typeof s.speed === 'number' ? s.speed : 0 }, write: async (v: any) => this.setState({ speed: Number(v) }) },
+            oscillation: { read: async () => { const s = await this.getState(); return !!s?.oscillating }, write: async (v: any) => this.setState({ oscillate: !!v }) },
+            swingMode: { read: async () => { const s = await this.getState(); return s?.swingMode ?? null }, write: async (v: any) => this.setState({ swingMode: v }) },
+          },
+        },
+      ],
+    }
+  }
+}
+export class LightDevice extends GenericDevice {
+  createHAPAccessory(api: any) {
+    return {
+      services: [
+        {
+          type: 'Lightbulb',
+          characteristics: {
+            On: {
+              get: async () => {
+                const s = await this.getState()
+                return !!(s && (s.on === true || s.state === 'on' || s.power === 'on'))
+              },
+              set: async (v: any) => {
+                await this.setState({ on: !!v })
+              },
+            },
+            Brightness: {
+              props: { minValue: 0, maxValue: 100, minStep: 1 },
+              get: async () => {
+                const s = await this.getState()
+                return typeof s.brightness === 'number' ? s.brightness : 100
+              },
+              set: async (v: any) => {
+                await this.setState({ brightness: Number(v) })
+              },
+            },
+            Hue: {
+              props: { minValue: 0, maxValue: 360, minStep: 1 },
+              get: async () => {
+                const s = await this.getState()
+                // prefer explicit hue if provided
+                if (s && typeof s.hue === 'number') { return s.hue }
+                // try HSV from color hex
+                const hex = s?.color || s?.colorHex || s?.colour
+                if (typeof hex === 'string' && /^#?[0-9A-F]{6}$/i.test(hex)) {
+                  const h = (() => {
+                    const hsl = (h: number, s: number, l: number) => ({ h, s, l })
+                    // convert hex -> rgb -> hsv
+                    const cleaned = hex.replace('#', '')
+                    const r = Number.parseInt(cleaned.substr(0, 2), 16) / 255
+                    const g = Number.parseInt(cleaned.substr(2, 2), 16) / 255
+                    const b = Number.parseInt(cleaned.substr(4, 2), 16) / 255
+                    const mx = Math.max(r, g, b); const mn = Math.min(r, g, b)
+                    const d = mx - mn
+                    if (d === 0) { return 0 }
+                    let hue = 0
+                    switch (mx) {
+                      case r: hue = ((g - b) / d) % 6; break
+                      case g: hue = (b - r) / d + 2; break
+                      case b: hue = (r - g) / d + 4; break
+                    }
+                    hue = Math.round(hue * 60)
+                    if (hue < 0) { hue += 360 }
+                    return hue
+                  })()
+                  return h
+                }
+                return 0
+              },
+              set: async (v: any) => {
+                await this.setState({ hue: Number(v) })
+              },
+            },
+            Saturation: {
+              props: { minValue: 0, maxValue: 100, minStep: 1 },
+              get: async () => {
+                const s = await this.getState()
+                if (s && typeof s.saturation === 'number') { return s.saturation }
+                // if color hex is available, derive saturation from rgb
+                const hex = s?.color || s?.colorHex || s?.colour
+                if (typeof hex === 'string' && /^#?[0-9A-F]{6}$/i.test(hex)) {
+                  const cleaned = hex.replace('#', '')
+                  const r = Number.parseInt(cleaned.substr(0, 2), 16) / 255
+                  const g = Number.parseInt(cleaned.substr(2, 2), 16) / 255
+                  const b = Number.parseInt(cleaned.substr(4, 2), 16) / 255
+                  const mx = Math.max(r, g, b); const mn = Math.min(r, g, b)
+                  const d = mx - mn
+                  const sat = mx === 0 ? 0 : Math.round((d / mx) * 100)
+                  return sat
+                }
+                return 0
+              },
+              set: async (v: any) => {
+                await this.setState({ saturation: Number(v) })
+              },
+            },
+            ColorTemperature: {
+              props: { minValue: 153, maxValue: 500, minStep: 1 },
+              get: async () => {
+                const s = await this.getState()
+                // prefer mired if provided
+                if (s && typeof s.colorTemperature === 'number') { return s.colorTemperature }
+                if (s && typeof s.color_temp === 'number') { return s.color_temp }
+                // some devices provide kelvin
+                if (s && typeof s.kelvin === 'number' && s.kelvin > 0) {
+                  return Math.round(1000000 / s.kelvin)
+                }
+                return 400
+              },
+              set: async (v: any) => {
+                await this.setState({ colorTemperature: Number(v) })
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+
+  async setState(change: any): Promise<any> {
+    if (!this.client) { return { success: false, reason: 'no client' } }
+
+    // Color temperature (mired) or brightness/hue/sat
+    if (typeof change.colorTemperature === 'number' || typeof change.color_temp === 'number') {
+      const v = String(Number(change.colorTemperature ?? change.color_temp))
+      const body = { command: 'setColorTemperature', parameter: v, commandType: 'command' }
+      try {
+        return await this.client.setDeviceState(this.opts.id, body)
+      } catch (err) {
+        try {
+          if (typeof this.client.sendCommand === 'function') { return await this.client.sendCommand(this.opts.id, body) }
+        } catch (e) {}
+        const e = err as any
+        return { success: false, reason: e?.message ?? String(e) }
+      }
+    }
+
+    if (typeof change.hue === 'number' && typeof change.saturation === 'number') {
+      const body = { command: 'setColor', parameter: `${Number(change.hue)},${Number(change.saturation)}`, commandType: 'command' }
+      try {
+        return await this.client.setDeviceState(this.opts.id, body)
+      } catch (err) {
+        try {
+          if (typeof this.client.sendCommand === 'function') { return await this.client.sendCommand(this.opts.id, body) }
+        } catch (e) {}
+        const e = err as any
+        return { success: false, reason: e?.message ?? String(e) }
+      }
+    }
+
+    if (change && typeof change.color === 'string') {
+      const body = { command: 'setColor', parameter: change.color, commandType: 'command' }
+      try {
+        return await this.client.setDeviceState(this.opts.id, body)
+      } catch (err) {
+        try {
+          if (typeof this.client.sendCommand === 'function') { return await this.client.sendCommand(this.opts.id, body) }
+        } catch (e) {}
+        const e = err as any
+        return { success: false, reason: e?.message ?? String(e) }
+      }
+    }
+
+    // Fallback to generic handler (brightness/on)
+    return super.setState(change)
+  }
+
+  // Matter-specific descriptor for lights (OnOff + Level + Color)
+  createMatterAccessory(api: any): any {
+    return {
+      id: this.opts.id,
+      name: this.opts.name ?? this.opts.type,
+      protocol: 'matter',
+      clusters: [
+        {
+          // OnOff cluster
+          type: 'OnOff',
+          clusterId: MATTER_CLUSTER_IDS.OnOff,
+          attributes: {
+            onOff: { read: async () => { const s = await this.getState(); return !!(s && (s.on === true || s.state === 'on' || s.power === 'on')) }, write: async (v: any) => this.setState({ on: !!v }) },
+            [MATTER_ATTRIBUTE_IDS.OnOff.OnOff]: { read: async () => { const s = await this.getState(); return !!(s && (s.on === true || s.state === 'on' || s.power === 'on')) }, write: async (v: any) => this.setState({ on: !!v }) },
+          },
+        },
+        {
+          // Level Control cluster
+          type: 'LevelControl',
+          clusterId: MATTER_CLUSTER_IDS.LevelControl,
+          attributes: {
+            currentLevel: { read: async () => { const s = await this.getState(); return typeof s.brightness === 'number' ? s.brightness : 100 }, write: async (v: any) => this.setState({ brightness: Number(v) }) },
+            [MATTER_ATTRIBUTE_IDS.LevelControl.CurrentLevel]: { read: async () => { const s = await this.getState(); return typeof s.brightness === 'number' ? s.brightness : 100 }, write: async (v: any) => this.setState({ brightness: Number(v) }) },
+          },
+        },
+        {
+          // Color Control cluster
+          type: 'ColorControl',
+          clusterId: MATTER_CLUSTER_IDS.ColorControl,
+          attributes: {
+            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) }) },
+            [MATTER_ATTRIBUTE_IDS.ColorControl.CurrentSaturation]: { read: async () => { const s = await this.getState(); return typeof s.saturation === 'number' ? s.saturation : 0 }, write: async (v: any) => this.setState({ saturation: Number(v) }) },
+            colorTemperature: { read: async () => {
+              const s = await this.getState(); if (typeof s.colorTemperature === 'number') { return s.colorTemperature } if (typeof s.kelvin === 'number') { return Math.round(1000000 / s.kelvin) } return 400
+            }, write: async (v: any) => this.setState({ colorTemperature: Number(v) }) },
+            [MATTER_ATTRIBUTE_IDS.ColorControl.ColorTemperatureMireds]: { read: async () => {
+              const s = await this.getState(); if (typeof s.colorTemperature === 'number') { return s.colorTemperature } if (typeof s.kelvin === 'number') { return Math.round(1000000 / s.kelvin) } return 400
+            }, write: async (v: any) => this.setState({ colorTemperature: Number(v) }) },
+          },
+        },
+      ],
+    }
+  }
+}
+
+export class LightStripDevice extends LightDevice {}
+
+export class MotionSensorDevice extends GenericDevice {
+  createHAPAccessory(api: any) {
+    return {
+      services: [
+        {
+          type: 'MotionSensor',
+          characteristics: {
+            MotionDetected: {
+              get: async () => {
+                const s = await this.getState()
+                return !!(s && s.motion === true)
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+
+  async setState(change: any): Promise<any> {
+    if (!this.client) { return { success: false, reason: 'no client' } }
+
+    // Oscillation support
+    if (typeof change.oscillate === 'boolean') {
+      const body = { command: 'setOscillation', parameter: change.oscillate ? 'on' : 'off', commandType: 'command' }
+      try {
+        return await this.client.setDeviceState(this.opts.id, body)
+      } catch (err) {
+        try {
+          if (typeof this.client.sendCommand === 'function') { return await this.client.sendCommand(this.opts.id, body) }
+        } catch (e) {}
+        const e = err as any
+        return { success: false, reason: e?.message ?? String(e) }
+      }
+    }
+
+    // Swing / sweep support (angle or mode)
+    if (change && (typeof change.swing === 'boolean' || typeof change.swingAngle === 'number' || typeof change.swingMode === 'string')) {
+      let param: string = 'default'
+      if (typeof change.swingMode === 'string') { param = change.swingMode } else if (typeof change.swingAngle === 'number') { param = String(Number(change.swingAngle)) } else {
+        param = change.swing ? 'on' : 'off'
+      }
+
+      const body = { command: 'setSwing', parameter: param, commandType: 'command' }
+      try {
+        return await this.client.setDeviceState(this.opts.id, body)
+      } catch (err) {
+        try {
+          if (typeof this.client.sendCommand === 'function') { return await this.client.sendCommand(this.opts.id, body) }
+        } catch (e) {}
+        const e = err as any
+        return { success: false, reason: e?.message ?? String(e) }
+      }
+    }
+
+    return super.setState(change)
+  }
+}
+
+export class ContactSensorDevice extends GenericDevice {
+  createHAPAccessory(api: any) {
+    return {
+      services: [
+        {
+          type: 'ContactSensor',
+          characteristics: {
+            ContactSensorState: {
+              get: async () => {
+                const s = await this.getState()
+                return s && s.open ? 1 : 0
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+}
+
+export class VacuumDevice extends GenericDevice {
+  // Use DeviceBase defaults (Switch-style) — no override needed
+  createHAPAccessory(api: any) {
+    return super.createHAPAccessory(api)
+  }
+}
+
+export class LockDevice extends GenericDevice {
+  createHAPAccessory(api: any) {
+    return {
+      services: [
+        {
+          type: 'LockMechanism',
+          characteristics: {
+            LockCurrentState: {
+              get: async () => {
+                const s = await this.getState()
+                return s && s.locked ? 1 : 0
+              },
+            },
+            LockTargetState: {
+              get: async () => {
+                const s = await this.getState()
+                return s && s.locked ? 1 : 0
+              },
+              set: async (v: any) => {
+                await this.setState({ locked: !!v })
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+
+  async setState(change: any): Promise<any> {
+    if (!this.client) { return { success: false, reason: 'no client' } }
+
+    // User management actions: add/remove/list users, unlock with pin
+    if (change && typeof change.action === 'string') {
+      const action = change.action
+      try {
+        if (action === 'addUser' && (change.user || change.userId) && (change.pin || change.code)) {
+          const user = change.user ?? change.userId
+          const p = String(change.pin ?? change.code)
+          const body = { command: 'addUserCode', parameter: `${user}:${p}`, commandType: 'command' }
+          return await this.client.setDeviceState(this.opts.id, body)
+        }
+
+        if (action === 'removeUser' && (change.user || change.userId)) {
+          const user = change.user ?? change.userId
+          const body = { command: 'removeUserCode', parameter: String(user), commandType: 'command' }
+          return await this.client.setDeviceState(this.opts.id, body)
+        }
+
+        if (action === 'listUsers') {
+          const body = { command: 'listUsers', parameter: 'default', commandType: 'command' }
+          return await this.client.setDeviceState(this.opts.id, body)
+        }
+
+        if (action === 'unlockWithPin' && (change.pin || change.code)) {
+          const p = String(change.pin ?? change.code)
+          const body = { command: 'unlockWithPin', parameter: p, commandType: 'command' }
+          return await this.client.setDeviceState(this.opts.id, body)
+        }
+      } catch (err) {
+        try {
+          if (typeof this.client.sendCommand === 'function') { return await this.client.sendCommand(this.opts.id, { command: action, parameter: change.parameter ?? 'default', commandType: 'command' }) }
+        } catch (e) {}
+        const e = err as any
+        return { success: false, reason: e?.message ?? String(e) }
+      }
+    }
+
+    // Support setting lock PIN/passcode via `pin` or `passcode` (fallback)
+    const pin = change?.pin ?? change?.passcode ?? change?.code
+    if (typeof pin === 'string' || typeof pin === 'number') {
+      const body = { command: 'setLockPin', parameter: String(pin), commandType: 'command' }
+      try {
+        return await this.client.setDeviceState(this.opts.id, body)
+      } catch (err) {
+        try {
+          if (typeof this.client.sendCommand === 'function') { return await this.client.sendCommand(this.opts.id, body) }
+        } catch (e) {}
+        const e = err as any
+        return { success: false, reason: e?.message ?? String(e) }
+      }
+    }
+
+    return super.setState(change)
+  }
+
+  // Matter DoorLock descriptor including simple user-management actions
+  createMatterAccessory(api: any): any {
+    return {
+      id: this.opts.id,
+      name: this.opts.name ?? this.opts.type,
+      protocol: 'matter',
+      clusters: [
+        {
+          // DoorLock cluster
+          type: 'DoorLock',
+          clusterId: MATTER_CLUSTER_IDS.DoorLock,
+          attributes: {
+            lockState: { read: async () => { const s = await this.getState(); return !!(s && s.locked) }, write: async (v: any) => this.setState({ locked: !!v }) },
+            [MATTER_ATTRIBUTE_IDS.DoorLock.LockState]: { read: async () => { const s = await this.getState(); return !!(s && s.locked) }, write: async (v: any) => this.setState({ locked: !!v }) },
+          },
+        },
+        {
+          // DoorLock user mgmt cluster (conceptual)
+          type: 'DoorLockUserManagement',
+          clusterId: 0x0301,
+          attributes: {
+            addUser: { write: async (v: any) => this.setState({ action: 'addUser', user: v?.user, pin: v?.pin }) },
+            removeUser: { write: async (v: any) => this.setState({ action: 'removeUser', user: v?.user }) },
+            listUsers: { read: async () => { const r = await this.setState({ action: 'listUsers' }); return r }, write: undefined },
+            unlockWithPin: { write: async (v: any) => this.setState({ action: 'unlockWithPin', pin: v?.pin }) },
+          },
+        },
+      ],
+    }
+  }
+}
+
+export class HumidifierDevice extends GenericDevice {
+  createHAPAccessory(api: any) {
+    return {
+      services: [
+        {
+          type: 'HumiditySensor',
+          characteristics: {
+            CurrentRelativeHumidity: {
+              get: async () => {
+                const s = await this.getState()
+                return typeof s.humidity === 'number' ? s.humidity : 0
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+
+  async setState(change: any): Promise<any> {
+    if (!this.client) { return { success: false, reason: 'no client' } }
+
+    if (typeof change.humidity === 'number') {
+      const v = String(Number(change.humidity))
+      const body = { command: 'setHumidity', parameter: v, commandType: 'command' }
+      try {
+        return await this.client.setDeviceState(this.opts.id, body)
+      } catch (err) {
+        try {
+          if (typeof this.client.sendCommand === 'function') { return await this.client.sendCommand(this.opts.id, body) }
+        } catch (e) {}
+        const e = err as any
+        return { success: false, reason: e?.message ?? String(e) }
+      }
+    }
+
+    if (typeof change.dry === 'boolean') {
+      const body = { command: 'setDry', parameter: change.dry ? 'on' : 'off', commandType: 'command' }
+      try {
+        return await this.client.setDeviceState(this.opts.id, body)
+      } catch (err) {
+        try {
+          if (typeof this.client.sendCommand === 'function') { return await this.client.sendCommand(this.opts.id, body) }
+        } catch (e) {}
+        const e = err as any
+        return { success: false, reason: e?.message ?? String(e) }
+      }
+    }
+
+    return super.setState(change)
+  }
+}
+
+// Provide Matter descriptor for humidifier (humidity and on/off)
+export class HumidifierMatterDevice extends HumidifierDevice {
+  createMatterAccessory(api: any) {
+    return {
+      id: this.opts.id,
+      name: this.opts.name ?? this.opts.type,
+      protocol: 'matter',
+      clusters: [
+        {
+          // Relative Humidity Sensor cluster
+          type: 'RelativeHumiditySensor',
+          clusterId: MATTER_CLUSTER_IDS.RelativeHumidityMeasurement,
+          attributes: {
+            currentRelativeHumidity: { read: async () => { const s = await this.getState(); return typeof s.humidity === 'number' ? s.humidity : 0 }, write: undefined },
+            [MATTER_ATTRIBUTE_IDS.RelativeHumidityMeasurement.MeasuredValue]: { read: async () => { const s = await this.getState(); return typeof s.humidity === 'number' ? s.humidity : 0 }, write: undefined },
+          },
+        },
+        {
+          type: 'OnOff',
+          clusterId: MATTER_CLUSTER_IDS.OnOff,
+          attributes: {
+            onOff: { read: async () => { const s = await this.getState(); return !!s?.on }, write: async (v: any) => this.setState({ on: !!v }) },
+            [MATTER_ATTRIBUTE_IDS.OnOff.OnOff]: { read: async () => { const s = await this.getState(); return !!s?.on }, write: async (v: any) => this.setState({ on: !!v }) },
+          },
+        },
+      ],
+    }
+  }
+}
+
+export class TemperatureSensorDevice extends GenericDevice {
+  createHAPAccessory(api: any) {
+    return {
+      services: [
+        {
+          type: 'TemperatureSensor',
+          characteristics: {
+            CurrentTemperature: {
+              get: async () => {
+                const s = await this.getState()
+                return typeof s.temperature === 'number' ? s.temperature : 0
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+}
+
+// Additional device classes (aliases / specialized variants)
+export class RelaySwitchDevice extends GenericDevice {}
+export class RelaySwitch1PMDevice extends GenericDevice {}
+export class PlugDevice extends GenericDevice {
+  createHAPAccessory(api: any) {
+    return {
+      services: [
+        {
+          type: 'Outlet',
+          characteristics: {
+            On: {
+              get: async () => {
+                const s = await this.getState()
+                return !!(s && (s.on === true || s.state === 'on'))
+              },
+              set: async (v: any) => {
+                await this.setState({ on: !!v })
+              },
+            },
+            OutletInUse: {
+              get: async () => {
+                const s = await this.getState()
+                return s && s.inUse ? 1 : 0
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+}
+
+export class PlugMiniDevice extends PlugDevice {}
+
+export class BlindTiltDevice extends CurtainDevice {}
+export class Curtain3Device extends CurtainDevice {}
+export class RollerShadeDevice extends CurtainDevice {}
+
+export class Hub2Device extends GenericDevice {}
+
+export class MeterDevice extends GenericDevice {
+  createHAPAccessory(api: any) {
+    return {
+      services: [
+        {
+          type: 'TemperatureSensor',
+          characteristics: {
+            CurrentTemperature: {
+              get: async () => {
+                const s = await this.getState()
+                return typeof s.temperature === 'number' ? s.temperature : 0
+              },
+            },
+          },
+        },
+        {
+          type: 'HumiditySensor',
+          characteristics: {
+            CurrentRelativeHumidity: {
+              get: async () => {
+                const s = await this.getState()
+                return typeof s.humidity === 'number' ? s.humidity : 0
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+}
+
+export class WaterDetectorDevice extends GenericDevice {
+  createHAPAccessory(api: any) {
+    return {
+      services: [
+        {
+          type: 'LeakSensor',
+          characteristics: {
+            LeakDetected: {
+              get: async () => {
+                const s = await this.getState()
+                return s && s.leak ? 1 : 0
+              },
+            },
+          },
+        },
+      ],
+    }
+  }
+}
+
+export class SmartFanDevice extends FanDevice {}
+
+export class StripLightDevice extends LightStripDevice {}
+
+export class WalletFinderDevice extends GenericDevice {}
+
+// K10 / WoSweeper variants map to VacuumDevice
+export class WoSweeperDevice extends VacuumDevice {}
+export class WoSweeperMiniDevice extends VacuumDevice {}
+export class WoSweeperMiniProDevice extends VacuumDevice {}