@switchbot/homebridge-switchbot 5.0.0-beta.7 → 5.0.0-beta.70

package/src/devices-matter/RoboticVacuumAccessory.ts

@@ -1,105 +1,167 @@
-/* global NodeJS */
+//
 
 /**
- * Robotic Vacuum Cleaner Accessory Class
+ * Robotic Vacuum Cleaner Accessory (SwitchBot-aligned)
  *
- * This is a comprehensive example demonstrating all available features
- * of the RoboticVacuumCleaner device type including:
- * - Multiple run modes (Idle, Cleaning, Mapping)
- * - Multiple clean modes (Vacuum, Mop, Vacuum & Mop, Deep Clean)
- * - Operational state management with realistic transitions
- * - Service area (room) support
+ * This implementation is intentionally limited to SwitchBot OpenAPI-supported
+ * behaviors for Robot Vacuum families. We expose only commands and modes that
+ * exist in the public API docs:
+ * https://github.com/OpenWonderLabs/SwitchBotAPI
  *
- * IMPORTANT: Platform Matter accessories
- * =======================================
- * This vacuum is registered as a platform accessory using
- * api.matter.registerPlatformAccessories(), which works the same as HAP.
- * Platform accessories are registered synchronously and are immediately ready for use.
+ * Capability matrix (derived from OpenAPI v1.1):
+ * - S1 / S1 Plus / K10+ / K10+ Pro
+ *   • Commands: start, stop, dock, PowLevel {0-3}
+ *   • No pause/resume, no mop, no area selection
+ * - K10+ Pro Combo
+ *   • Commands: startClean {action: sweep|mop, param: {fanLevel 1-4}}, pause, dock
+ *   • changeParam {fanLevel}, setVolume
+ * - S10 / S20 / K11+ / K20+ Pro
+ *   • Commands: startClean {action: sweep|sweep_mop|mop (model-dependent), param: {fanLevel 1-4, waterLevel 1-2?}},
+ *               pause, dock, changeParam, setVolume, (S10/S20) selfClean/addWaterForHumi
+ *   • Some models support waterLevel, some do not (e.g. K10+ Pro Combo)
  *
- * Demo behavior:
- * - Start/Resume: Sets run mode to "Cleaning", runs for 15/10 seconds, then returns to dock
- * - Return to dock: Immediately sets "Idle" mode, then Seeking (5s) → Charging (3s) → Docked
- * - Stop: Immediately stops and resets to "Idle" mode
- * - Pause: Cancels automatic completion timer, keeps "Cleaning" mode
+ * Matter clusters exposed:
+ * - rvcRunMode: Idle/Cleaning only (no Mapping mode via OpenAPI)
+ * - rvcCleanMode: Interpreted per model:
+ *   • Basic vac (S1/K10 family): suction levels → Quiet/Standard/Strong/MAX
+ *   • Mop-capable (K10+ Pro Combo/K11+/K20+ Pro): action → Vacuum or Mop
+ *   • Mop+Vac-capable (S10/S20): action → Vacuum or Vacuum & Mop
+ * - rvcOperationalState: start/stop/pause/goHome handlers are attached only when supported
+ * - serviceArea: NOT exposed (area/room selection isn’t in public OpenAPI)
  */
 
 import type { API, Logger, MatterRequests } from 'homebridge'
 
 import { BaseMatterAccessory } from './BaseMatterAccessory.js'
 
-export class RoboticVacuumAccessory extends BaseMatterAccessory {
-  private activeTimers: NodeJS.Timeout[] = []
+type SwitchBotVacuumModel
+  = 'S1'
+    | 'S1 Plus'
+    | 'S1 Pro'
+    | 'S1 Mini'
+    | 'WoSweeper'
+    | 'WoSweeperMini'
+    | 'K10+'
+    | 'K10+ Pro'
+    | 'K10+ Pro Combo'
+    | 'S10'
+    | 'S20'
+    | 'K11+'
+    | 'K20+ Pro'
+
+interface VacuumCapabilities {
+  // Whether pause/resume is available
+  pause: boolean
+  resume: boolean
+  // Clean action type exposed via rvcCleanMode
+  cleanAction: 'vacuum-only' | 'vacuum-or-mop' | 'vacuum-or-vacmop'
+  // Suction mapping: basic uses PowLevel 0-3; advanced uses fanLevel 1-4
+  suctionKind: 'powLevel-0-3' | 'fanLevel-1-4' | 'none'
+  // Whether waterLevel parameter is supported on start/changeParam
+  waterLevel: boolean
+  // Advanced commands available (S10/S20 only)
+  advancedCommands?: {
+    setVolume?: boolean
+    selfClean?: boolean
+    addWaterForHumi?: boolean
+  }
+}
 
-  constructor(api: API, log: Logger, opts?: Partial<import('./BaseMatterAccessory').BaseMatterAccessoryConfig & { deviceId?: string }>) {
-    const serialNumber = opts?.serialNumber ?? 'VACUUM-001'
-    const clusters = opts?.clusters ?? {
-      powerSource: {
-        status: 0,
-        order: 0,
-        description: 'Battery',
-        batPercentRemaining: 100,
-        batChargeLevel: 2,
-        batReplaceability: 1,
-      },
-      rvcRunMode: {
-        supportedModes: [
-          { label: 'Idle', mode: 0, modeTags: [{ value: 16384 }] },
-          { label: 'Cleaning', mode: 1, modeTags: [{ value: 16385 }] },
-          { label: 'Mapping', mode: 2, modeTags: [{ value: 16386 }] },
-        ],
-        currentMode: 0,
-      },
-      rvcCleanMode: {
-        supportedModes: [
-          { label: 'Vacuum', mode: 0, modeTags: [{ value: 16385 }] },
-          { label: 'Mop', mode: 1, modeTags: [{ value: 16386 }] },
-          { label: 'Vacuum & Mop', mode: 2, modeTags: [{ value: 16385 }, { value: 16386 }] },
-          { label: 'Deep Clean', mode: 3, modeTags: [{ value: 16384 }] },
-          { label: 'Deep Vacuum', mode: 4, modeTags: [{ value: 16384 }, { value: 16385 }] },
-          { label: 'Deep Mop', mode: 5, modeTags: [{ value: 16384 }, { value: 16386 }] },
-          { label: 'Quick Clean', mode: 6, modeTags: [{ value: 1 }, { value: 16385 }] },
-          { label: 'Max Clean', mode: 7, modeTags: [{ value: 7 }, { value: 16385 }] },
-          { label: 'Min Clean', mode: 8, modeTags: [{ value: 6 }, { value: 16385 }] },
-          { label: 'Quiet Vacuum', mode: 9, modeTags: [{ value: 2 }, { value: 16385 }] },
-          { label: 'Quiet Mop', mode: 10, modeTags: [{ value: 2 }, { value: 16386 }] },
-          { label: 'Night Mode', mode: 11, modeTags: [{ value: 8 }, { value: 16385 }] },
-          { label: 'Eco Vacuum', mode: 12, modeTags: [{ value: 4 }, { value: 16385 }] },
-          { label: 'Eco Mop', mode: 13, modeTags: [{ value: 4 }, { value: 16386 }] },
-          { label: 'Auto', mode: 14, modeTags: [{ value: 0 }, { value: 16385 }] },
-        ],
-        currentMode: 0,
-      },
-      rvcOperationalState: {
-        operationalStateList: [
-          { operationalStateId: 0 },
-          { operationalStateId: 1 },
-          { operationalStateId: 2 },
-          { operationalStateId: 3 },
-          { operationalStateId: 64 },
-          { operationalStateId: 65 },
-          { operationalStateId: 66 },
-        ],
-        operationalState: 66,
-      },
-      serviceArea: {
-        supportedMaps: [],
-        supportedAreas: [
-          { areaId: 0, mapId: null, areaInfo: { locationInfo: { locationName: 'Living Room', floorNumber: 0, areaType: 7 }, landmarkInfo: null } },
-          { areaId: 1, mapId: null, areaInfo: { locationInfo: { locationName: 'Kitchen', floorNumber: 0, areaType: 10 }, landmarkInfo: null } },
-          { areaId: 2, mapId: null, areaInfo: { locationInfo: { locationName: 'Bedroom', floorNumber: 0, areaType: 2 }, landmarkInfo: null } },
-          { areaId: 3, mapId: null, areaInfo: { locationInfo: { locationName: 'Bathroom', floorNumber: 0, areaType: 6 }, landmarkInfo: null } },
-        ],
-        selectedAreas: [0, 1, 2, 3],
+function detectModelFromContext(ctx?: Record<string, unknown>): SwitchBotVacuumModel | undefined {
+  const t = (ctx?.deviceType as string | undefined)?.trim()
+  switch (t) {
+    case 'Robot Vacuum Cleaner S1':
+      return 'S1'
+    case 'Robot Vacuum Cleaner S1 Plus':
+      return 'S1 Plus'
+    case 'Robot Vacuum Cleaner S1 Pro':
+      return 'S1 Pro'
+    case 'Robot Vacuum Cleaner S1 Mini':
+      return 'S1 Mini'
+    case 'WoSweeper':
+      return 'WoSweeper'
+    case 'WoSweeperMini':
+      return 'WoSweeperMini'
+    case 'K10+':
+      return 'K10+'
+    case 'K10+ Pro':
+      return 'K10+ Pro'
+    case 'Robot Vacuum Cleaner K10+ Pro Combo':
+    case 'K10+ Pro Combo':
+      return 'K10+ Pro Combo'
+    case 'Robot Vacuum Cleaner S10':
+      return 'S10'
+    case 'Robot Vacuum Cleaner S20':
+    case 'S20':
+      return 'S20'
+    case 'Robot Vacuum Cleaner K11+':
+    case 'K11+':
+      return 'K11+'
+    case 'Robot Vacuum Cleaner K20 Plus Pro':
+    case 'K20+ Pro':
+      return 'K20+ Pro'
+    default:
+      return undefined
+  }
+}
+
+function capabilitiesFor(model?: SwitchBotVacuumModel): VacuumCapabilities {
+  // Defaults: conservative basic vac
+  if (!model) {
+    return { pause: false, resume: false, cleanAction: 'vacuum-only', suctionKind: 'powLevel-0-3', waterLevel: false }
+  }
+
+  // Basic vacuum models (S1 family, WoSweeper family, K10 family without Combo)
+  if (model === 'S1' || model === 'S1 Plus' || model === 'S1 Pro' || model === 'S1 Mini'
+    || model === 'WoSweeper' || model === 'WoSweeperMini'
+    || model === 'K10+' || model === 'K10+ Pro') {
+    return { pause: false, resume: false, cleanAction: 'vacuum-only', suctionKind: 'powLevel-0-3', waterLevel: false }
+  }
+
+  // K10+ Pro Combo: vacuum or mop, fanLevel, no waterLevel
+  if (model === 'K10+ Pro Combo') {
+    return { pause: true, resume: false, cleanAction: 'vacuum-or-mop', suctionKind: 'fanLevel-1-4', waterLevel: false }
+  }
+
+  // S10/S20: vacuum or vacuum+mop combo, fanLevel, waterLevel, plus advanced commands
+  if (model === 'S10' || model === 'S20') {
+    return {
+      pause: true,
+      resume: false,
+      cleanAction: 'vacuum-or-vacmop',
+      suctionKind: 'fanLevel-1-4',
+      waterLevel: true,
+      advancedCommands: {
+        setVolume: true,
+        selfClean: true,
+        addWaterForHumi: true,
       },
     }
+  }
 
-    const handlers = opts?.handlers ?? {
-      rvcRunMode: { changeToMode: async (request: MatterRequests.ChangeToMode) => this.handleChangeRunMode(request) },
-      rvcCleanMode: { changeToMode: async (request: MatterRequests.ChangeToMode) => this.handleChangeCleanMode(request) },
-      rvcOperationalState: { pause: async () => this.handlePause(), stop: async () => this.handleStop(), start: async () => this.handleStart(), resume: async () => this.handleResume(), goHome: async () => this.handleGoHome() },
-      serviceArea: { selectAreas: async (request: MatterRequests.SelectAreas) => this.handleSelectAreas(request), skipArea: async (request: MatterRequests.SkipArea) => this.handleSkipArea(request) },
-    }
+  // K11+/K20+ Pro: vacuum or mop, fanLevel, waterLevel, volume control
+  return {
+    pause: true,
+    resume: false,
+    cleanAction: 'vacuum-or-mop',
+    suctionKind: 'fanLevel-1-4',
+    waterLevel: true,
+    advancedCommands: {
+      setVolume: true,
+    },
+  }
+}
 
+export class RoboticVacuumAccessory extends BaseMatterAccessory {
+  // Track current high-level preferences that affect OpenAPI payloads
+  private currentCleanAction: 'vacuum' | 'mop' | 'vacuum_mop' = 'vacuum'
+  private currentFanLevel: 1 | 2 | 3 | 4 = 2
+  private capabilities: VacuumCapabilities
+
+  constructor(api: API, log: Logger, opts?: Partial<import('./BaseMatterAccessory').BaseMatterAccessoryConfig & { deviceId?: string }>) {
+    const serialNumber = opts?.serialNumber ?? 'VACUUM-001'
+    const model = detectModelFromContext(opts?.context)
+    const capabilities = capabilitiesFor(model)
     super(api, log, {
       uuid: opts?.uuid ?? api.matter.uuid.generate(serialNumber),
       displayName: opts?.displayName ?? 'Robot Vacuum',
@@ -109,224 +171,327 @@ export class RoboticVacuumAccessory extends BaseMatterAccessory {
       model: opts?.model ?? 'HB-MATTER-VACUUM-ROBOTIC',
       firmwareRevision: opts?.firmwareRevision ?? '2.0.0',
       hardwareRevision: opts?.hardwareRevision ?? '1.0.0',
-      clusters,
-      handlers,
-      context: { deviceId: opts?.deviceId, ...(opts?.context ?? {}) },
+      clusters: {
+        rvcRunMode: {
+          supportedModes: [
+            { label: 'Idle', mode: 0, modeTags: [{ value: 16384 }] },
+            { label: 'Cleaning', mode: 1, modeTags: [{ value: 16385 }] },
+          ],
+          currentMode: 0,
+        },
+        rvcCleanMode: (() => {
+          switch (model as string) {
+            case 'K10':
+              return {
+                supportedModes: [
+                  { label: 'Vacuum', mode: 0, modeTags: [{ value: 16385 }] },
+                ],
+                currentMode: 0,
+              }
+            case 'Robot Vacuum Cleaner S1':
+            case 'Robot Vacuum Cleaner S1 Plus':
+              return {
+                supportedModes: [
+                  { label: 'Quiet', mode: 0, modeTags: [{ value: 2 }] },
+                  { label: 'Standard', mode: 1, modeTags: [{ value: 16384 }] },
+                  { label: 'Strong', mode: 2, modeTags: [{ value: 7 }] },
+                  { label: 'MAX', mode: 3, modeTags: [{ value: 8 }] },
+                ],
+                currentMode: 1,
+              }
+            case 'Mini Robot Vacuum K10+':
+            case 'Mini Robot Vacuum K10+ Pro':
+            case 'K10+ Pro Combo':
+              return {
+                supportedModes: [
+                  { label: 'Vacuum', mode: 0, modeTags: [{ value: 16385 }] },
+                  { label: 'Mop', mode: 1, modeTags: [{ value: 16386 }] },
+                  { label: 'Sweep & Mop', mode: 2, modeTags: [{ value: 16385 }, { value: 16386 }] },
+                ],
+                currentMode: 0,
+              }
+            case 'Multitasking Household Robot K20+ Pro':
+              return {
+                supportedModes: [
+                  { label: 'Vacuum', mode: 0, modeTags: [{ value: 16385 }] },
+                  { label: 'Vacuum & Mop', mode: 1, modeTags: [{ value: 16385 }, { value: 16386 }] },
+                  { label: 'Deep Clean', mode: 2, modeTags: [{ value: 16384 }] },
+                ],
+                currentMode: 0,
+              }
+            case 'Floor Cleaning Robot S10':
+            case 'Floor Cleaning Robot S20':
+              return {
+                supportedModes: [
+                  { label: 'Vacuum', mode: 0, modeTags: [{ value: 16385 }] },
+                  { label: 'Mop', mode: 1, modeTags: [{ value: 16386 }] },
+                ],
+                currentMode: 0,
+              }
+            case 'Robot Vacuum K11+':
+              return {
+                supportedModes: [
+                  { label: 'Quiet', mode: 0, modeTags: [{ value: 2 }] },
+                  { label: 'Standard', mode: 1, modeTags: [{ value: 16384 }] },
+                  { label: 'Strong', mode: 2, modeTags: [{ value: 7 }] },
+                  { label: 'MAX', mode: 3, modeTags: [{ value: 8 }] },
+                  { label: 'Deep Clean', mode: 4, modeTags: [{ value: 16384 }, { value: 16385 }] },
+                ],
+                currentMode: 1,
+              }
+            default:
+              return {
+                supportedModes: [
+                  { label: 'Vacuum', mode: 0, modeTags: [{ value: 16385 }] },
+                  { label: 'Vacuum & Mop', mode: 1, modeTags: [{ value: 16385 }, { value: 16386 }] },
+                  { label: 'Deep Clean', mode: 2, modeTags: [{ value: 16384 }] },
+                ],
+                currentMode: 0,
+              }
+          }
+        })(),
+        rvcOperationalState: {
+          operationalStateList: [
+            { operationalStateId: 0 }, // Stopped
+            { operationalStateId: 1 }, // Running
+            { operationalStateId: 2 }, // Paused
+            { operationalStateId: 3 }, // Error
+            { operationalStateId: 64 }, // Seeking Charger
+            { operationalStateId: 65 }, // Charging
+            { operationalStateId: 66 }, // Docked
+            { operationalStateId: 67 }, // In Remote Control
+            { operationalStateId: 68 }, // In Dust Collecting
+          ],
+          operationalState: 66,
+        },
+      },
+      handlers: (() => {
+        const opHandlers: Record<string, any> = {
+          stop: async () => this.handleStop(),
+          start: async () => this.handleStart(),
+          goHome: async () => this.handleGoHome(),
+          // Always register resume handler, log warning if not supported
+          resume: async () => {
+            if (capabilities.resume) {
+              await this.handleResume()
+            } else {
+              this.logWarn(`Resume operation is not supported for model: ${this.model}`)
+            }
+          },
+        }
+        if (capabilities.pause) {
+          opHandlers.pause = async () => this.handlePause()
+        }
+        return {
+          rvcRunMode: { changeToMode: async (request: MatterRequests.ChangeToMode) => this.handleChangeRunMode(request) },
+          rvcCleanMode: { changeToMode: async (request: MatterRequests.ChangeToMode) => this.handleChangeCleanMode(request) },
+          rvcOperationalState: opHandlers as any,
+        }
+      })(),
+      context: { deviceId: opts?.deviceId, ...(opts?.context ?? {}), deviceType: (opts?.context as any)?.deviceType },
     })
 
+    this.capabilities = capabilities
     this.logInfo('initialized and ready.')
   }
 
   private async handleChangeRunMode(request: MatterRequests.ChangeToMode): Promise<void> {
     this.logInfo(`ChangeToMode (run) request received: ${JSON.stringify(request)}`)
     const { newMode } = request
-    const modeStr = ['Idle', 'Cleaning', 'Mapping'][newMode] || `Unknown (mode=${newMode})`
-    this.logInfo(`changing run mode to: ${modeStr}`)
-    // TODO: await myVacuumAPI.setRunMode(newMode)
-
-    // Clear any existing timers
-    this.clearTimers()
-
-    if (newMode === 1) {
-      // Switching to Cleaning mode - start the vacuum
-      this.updateOperationalState(1) // Running
-
-      // Simulate cleaning completion after 15 seconds
-      const completionTimer = setTimeout(() => {
-        this.logInfo('cleaning completed, returning to dock.')
-        this.updateRunMode(0) // Set to Idle - cleaning session ending
-        this.returnToDock()
-      }, 15000)
-
-      this.activeTimers.push(completionTimer)
-    } else if (newMode === 0) {
-      // Switching to Idle mode - return to dock
-      this.returnToDock()
-    } else if (newMode === 2) {
-      // Switching to Mapping mode - start mapping
-      this.updateOperationalState(1) // Running
-
-      // Simulate mapping completion after 20 seconds
-      const completionTimer = setTimeout(() => {
-        this.logInfo('mapping completed, returning to dock.')
-        this.returnToDock()
-      }, 20000)
-
-      this.activeTimers.push(completionTimer)
+    const modeStr = ['Idle', 'Cleaning', 'Returning to Dock'][newMode] || `Unknown (mode=${newMode})`
+    this.logInfo(`Changing run mode to: ${modeStr}`)
+
+    switch (this.model) {
+      case 'Robot Vacuum Cleaner S1':
+      case 'Robot Vacuum Cleaner S1 Plus': {
+        if (newMode === 1) {
+          await this.handleStart()
+        } else if (newMode === 0) {
+          await this.handleGoHome()
+        }
+        break
+      }
+      case 'Mini Robot Vacuum K10+':
+      case 'Mini Robot Vacuum K10+ Pro':
+      case 'K10+ Pro Combo': {
+        if (newMode === 1) {
+          await this.handleStart()
+        } else if (newMode === 2) {
+          await this.handleDock()
+        }
+        break
+      }
+      case 'Multitasking Household Robot K20+ Pro': {
+        if (newMode === 1) {
+          await this.handleStart()
+        } else if (newMode === 0) {
+          await this.handleGoHome()
+        } else if (newMode === 2) {
+          await this.handlePause()
+        }
+        break
+      }
+      case 'Floor Cleaning Robot S10':
+      case 'Floor Cleaning Robot S20': {
+        if (newMode === 1) {
+          await this.handleStart()
+        } else if (newMode === 0) {
+          await this.handleGoHome()
+        }
+        break
+      }
+      case 'Robot Vacuum K11+': {
+        if (newMode === 1) {
+          await this.handleStart()
+        } else if (newMode === 0) {
+          await this.handleGoHome()
+        } else if (newMode === 2) {
+          await this.handleDock()
+        }
+        break
+      }
+      default:
+        this.logWarn(`Run mode change not supported for model: ${this.model}`)
     }
   }
 
   private async handleChangeCleanMode(request: MatterRequests.ChangeToMode): Promise<void> {
     this.logInfo(`ChangeToMode (clean) request received: ${JSON.stringify(request)}`)
     const { newMode } = request
-    const modes = [
-      'Vacuum',
-      'Mop',
-      'Vacuum & Mop',
-      'Deep Clean',
-      'Deep Vacuum',
-      'Deep Mop',
-      'Quick Clean',
-      'Max Clean',
-      'Min Clean',
-      'Quiet Vacuum',
-      'Quiet Mop',
-      'Night Mode',
-      'Eco Vacuum',
-      'Eco Mop',
-      'Auto',
-    ]
-    const modeStr = modes[newMode] || `Unknown (mode=${newMode})`
-    this.logInfo(`changing clean mode to: ${modeStr}`)
-    // TODO: await myVacuumAPI.setCleanMode(newMode)
+
+    switch (this.model) {
+      case 'Robot Vacuum Cleaner S1':
+      case 'Robot Vacuum Cleaner S1 Plus': {
+        const mapPowS1 = ['Quiet', 'Standard', 'Strong', 'MAX'] as const
+        const labelS1 = mapPowS1[newMode] ?? `Unknown (${newMode})`
+        this.logInfo(`Changing suction level to: ${labelS1}`)
+        await this.sendOpenAPICommand('PowLevel', String(newMode))
+        break
+      }
+      case 'Mini Robot Vacuum K10+':
+      case 'Mini Robot Vacuum K10+ Pro':
+      case 'K10+ Pro Combo': {
+        const mapPowK10 = ['Vacuum', 'Mop', 'Sweep & Mop'] as const
+        const labelK10 = mapPowK10[newMode] ?? `Unknown (${newMode})`
+        this.logInfo(`Changing cleaning mode to: ${labelK10}`)
+        await this.sendOpenAPICommand('CleanMode', String(newMode))
+        break
+      }
+      case 'Multitasking Household Robot K20+ Pro': {
+        const mapPowK20 = ['Vacuum', 'Vacuum & Mop', 'Deep Clean'] as const
+        const labelK20 = mapPowK20[newMode] ?? `Unknown (${newMode})`
+        this.logInfo(`Changing cleaning mode to: ${labelK20}`)
+        await this.sendOpenAPICommand('CleanMode', String(newMode))
+        break
+      }
+      case 'Floor Cleaning Robot S10':
+      case 'Floor Cleaning Robot S20': {
+        const mapPowS10 = ['Vacuum', 'Mop'] as const
+        const labelS10 = mapPowS10[newMode] ?? `Unknown (${newMode})`
+        this.logInfo(`Changing cleaning mode to: ${labelS10}`)
+        await this.sendOpenAPICommand('CleanMode', String(newMode))
+        break
+      }
+      case 'Robot Vacuum K11+': {
+        const mapPowK11 = ['Quiet', 'Standard', 'Strong', 'MAX', 'Deep Clean'] as const
+        const labelK11 = mapPowK11[newMode] ?? `Unknown (${newMode})`
+        this.logInfo(`Changing suction level to: ${labelK11}`)
+        await this.sendOpenAPICommand('PowLevel', String(newMode))
+        break
+      }
+      default:
+        this.logWarn(`Clean mode change not supported for model: ${this.model}`)
+    }
   }
 
   private async handlePause(): Promise<void> {
     this.logInfo('pausing.')
-    // TODO: await myVacuumAPI.pause()
-    this.clearTimers() // Clear cleaning completion timer
-    this.updateOperationalState(2) // Paused
+    try {
+      this.logInfo(`[OpenAPI] Sending pause command`)
+      await this.sendOpenAPICommand('pause')
+      this.logInfo(`[OpenAPI] pause command sent`)
+    } catch (e: any) {
+      this.logWarn(`OpenAPI pause failed: ${String(e?.message ?? e)}`)
+    }
+    this.updateOperationalState(2)
   }
 
   private async handleStop(): Promise<void> {
     this.logInfo('stopping.')
-    // TODO: await myVacuumAPI.stop()
-    this.clearTimers()
-    this.updateRunMode(0) // Reset to Idle
-    this.updateOperationalState(0) // Stopped
+    try {
+      if (this.capabilities.cleanAction === 'vacuum-only' && this.capabilities.suctionKind === 'powLevel-0-3') {
+        this.logInfo(`[OpenAPI] Sending stop command`)
+        await this.sendOpenAPICommand('stop')
+        this.logInfo(`[OpenAPI] stop command sent`)
+      } else {
+        this.logInfo(`[OpenAPI] Sending pause command (for stop)`)
+        await this.sendOpenAPICommand('pause')
+        this.logInfo(`[OpenAPI] pause command sent (for stop)`)
+      }
+    } catch (e: any) {
+      this.logWarn(`OpenAPI stop/pause failed: ${String(e?.message ?? e)}`)
+    }
+    this.updateRunMode(0)
+    this.updateOperationalState(0)
   }
 
   private async handleStart(): Promise<void> {
-    this.logInfo('starting (via start command).')
-    // TODO: await myVacuumAPI.start()
-
-    // Clear any existing timers
-    this.clearTimers()
-
-    this.updateRunMode(1) // Set to Cleaning mode - this will trigger the run mode handler logic
-    this.updateOperationalState(1) // Running
-
-    // Simulate cleaning completion after 15 seconds
-    const completionTimer = setTimeout(() => {
-      this.logInfo('cleaning completed, returning to dock.')
-      this.updateRunMode(0) // Set to Idle - cleaning session ending
-      this.returnToDock()
-    }, 15000)
-
-    this.activeTimers.push(completionTimer)
+    this.logInfo('starting clean.')
+    try {
+      if (this.capabilities.cleanAction === 'vacuum-only' && this.capabilities.suctionKind === 'powLevel-0-3') {
+        this.logInfo(`[OpenAPI] Sending start command`)
+        await this.sendOpenAPICommand('start')
+        this.logInfo(`[OpenAPI] start command sent`)
+      } else {
+        const action = this.currentCleanAction === 'vacuum_mop' ? 'sweep_mop' : this.currentCleanAction
+        const param: any = { action, param: { fanLevel: this.currentFanLevel } }
+        if (this.capabilities.waterLevel) {
+          param.param.waterLevel = 1
+        }
+        this.logInfo(`[OpenAPI] Sending startClean: ${JSON.stringify(param)}`)
+        await this.sendOpenAPICommand('startClean', JSON.stringify(param))
+        this.logInfo(`[OpenAPI] startClean command sent: ${JSON.stringify(param)}`)
+      }
+    } catch (e: any) {
+      this.logWarn(`OpenAPI start/startClean failed: ${String(e?.message ?? e)}`)
+    }
+    this.updateRunMode(1)
+    this.updateOperationalState(1)
   }
 
   private async handleResume(): Promise<void> {
-    this.logInfo('resuming.')
-    // TODO: await myVacuumAPI.resume()
-
-    // Clear any existing timers
-    this.clearTimers()
-
-    this.updateRunMode(1) // Set to Cleaning mode
-    this.updateOperationalState(1) // Running
-
-    // Simulate cleaning completion after 10 seconds (shorter since resuming)
-    const completionTimer = setTimeout(() => {
-      this.logInfo('cleaning completed, returning to dock.')
-      this.updateRunMode(0) // Set to Idle - cleaning session ending
-      this.returnToDock()
-    }, 10000)
-
-    this.activeTimers.push(completionTimer)
+    this.logInfo('resume requested.')
+    try {
+      this.logInfo(`[OpenAPI] Sending resume command`)
+      await this.sendOpenAPICommand('resume')
+      this.logInfo(`[OpenAPI] resume command sent`)
+    } catch (e: any) {
+      this.logWarn(`OpenAPI resume failed: ${String(e?.message ?? e)}`)
+    }
+    this.updateRunMode(1)
+    this.updateOperationalState(1)
   }
 
   private async handleGoHome(): Promise<void> {
-    this.logInfo('goHome command received.')
-    // TODO: await myVacuumAPI.goHome()
-
-    // Clear any existing timers
-    this.clearTimers()
-
-    // Defer state updates to ensure handler completes first
-    setImmediate(() => {
-      // Set to Idle mode since we're ending the cleaning session
-      this.updateRunMode(0)
-
-      // Initiate return to dock sequence
-      this.returnToDock()
-    })
-  }
-
-  private async handleSelectAreas(request: MatterRequests.SelectAreas): Promise<void> {
-    this.logInfo(`SelectAreas request received: ${JSON.stringify(request)}`)
-    const { newAreas } = request
-    const areaNames = newAreas.map((id: number) =>
-      ['Living Room', 'Kitchen', 'Bedroom', 'Bathroom'][id] || `Area ${id}`,
-    )
-    this.logInfo(`selecting areas: ${areaNames.join(', ')}`)
-    // TODO: await myVacuumAPI.selectAreas(newAreas)
-  }
-
-  private async handleSkipArea(request: MatterRequests.SkipArea): Promise<void> {
-    this.logInfo(`SkipArea request received: ${JSON.stringify(request)}`)
-    const { skippedArea } = request
-    const areaName = ['Living Room', 'Kitchen', 'Bedroom', 'Bathroom'][skippedArea] || `Area ${skippedArea}`
-    this.logInfo(`skipping area: ${areaName}`)
-    // TODO: await myVacuumAPI.skipArea(skippedArea)
-  }
-
-  /**
-   * Helper method to clear all active timers
-   */
-  private clearTimers(): void {
-    this.activeTimers.forEach(timer => clearTimeout(timer))
-    this.activeTimers = []
-  }
-
-  /**
-   * Helper method to initiate return to dock sequence
-   * Can be called synchronously from other handlers
-   */
-  private returnToDock(): void {
-    this.logInfo('initiating return to dock sequence.')
-
-    // Defer ALL state updates to ensure handler completes first
-    setImmediate(() => {
-      // Start seeking charger directly (skip intermediate Stopped state)
-      this.updateOperationalState(64) // Seeking Charger
-
-      // After 5 seconds, start charging
-      const chargingTimer = setTimeout(() => {
-        this.logInfo('reached dock, now charging.')
-        this.updateOperationalState(65) // Charging
-
-        // After 3 more seconds, fully docked
-        const dockedTimer = setTimeout(() => {
-          this.logInfo('fully charged and docked.')
-          this.updateOperationalState(66) // Docked
-        }, 3000)
-
-        this.activeTimers.push(dockedTimer)
-      }, 5000)
-
-      this.activeTimers.push(chargingTimer)
-    })
+    this.logInfo('returning to dock.')
+    try {
+      this.logInfo(`[OpenAPI] Sending dock command`)
+      await this.sendOpenAPICommand('dock')
+      this.logInfo(`[OpenAPI] dock command sent`)
+    } catch (e: any) {
+      this.logWarn(`OpenAPI dock failed: ${String(e?.message ?? e)}`)
+    }
+    this.updateRunMode(0)
+    this.updateOperationalState(64)
   }
 
-  /**
-   * Update Methods - Use these to update the vacuum state from your API/device
-   *
-   * Since this is a platform accessory, state updates work immediately after registration.
-   */
-
   public updateOperationalState(state: number): void {
     this.updateState('rvcOperationalState', { operationalState: state })
     const states = [
       'Stopped',
       'Running',
       'Paused',
-      'Error',
-      null,
-      null,
-      null,
-      null,
-      ...Array.from({ length: 56 }).fill(null),
+      ...Array.from({ length: 61 }).fill(null),
       'Seeking Charger',
       'Charging',
       'Docked',
@@ -336,72 +501,121 @@ export class RoboticVacuumAccessory extends BaseMatterAccessory {
 
   public updateRunMode(mode: number): void {
     this.updateState('rvcRunMode', { currentMode: mode })
-    const modes = ['Idle', 'Cleaning', 'Mapping']
+    const modes = ['Idle', 'Cleaning']
     this.logInfo(`run mode updated to: ${modes[mode] || `Unknown (${mode})`}`)
   }
 
   public updateCleanMode(mode: number): void {
     this.updateState('rvcCleanMode', { currentMode: mode })
-    const modes = [
-      'Vacuum',
-      'Mop',
-      'Vacuum & Mop',
-      'Deep Clean',
-      'Deep Vacuum',
-      'Deep Mop',
-      'Quick Clean',
-      'Max Clean',
-      'Min Clean',
-      'Quiet Vacuum',
-      'Quiet Mop',
-      'Night Mode',
-      'Eco Vacuum',
-      'Eco Mop',
-      'Auto',
-    ]
-    this.logInfo(`clean mode updated to: ${modes[mode] || `Unknown (${mode})`}`)
+    const label = mode === 0 ? 'Vacuum' : mode === 1 ? 'Mop' : mode === 2 ? 'Vacuum & Mop' : 'Unknown'
+    this.logInfo(`clean mode updated to: ${label}`)
   }
 
-  public updateSelectedAreas(areaIds: number[]): void {
-    this.updateState('serviceArea', { selectedAreas: areaIds })
-    const areaNames = areaIds.map(id =>
-      ['Living Room', 'Kitchen', 'Bedroom', 'Bathroom'][id] || `Area ${id}`,
-    )
-    this.logInfo(`selected areas updated to: ${areaNames.join(', ') || 'All Areas'}`)
+  /**
+   * Update battery percentage (no PowerSource cluster for this device type)
+   */
+  public async updateBatteryPercentage(percentageOrBatPercentRemaining: number): Promise<void> {
+    const isBatPercent = Number(percentageOrBatPercentRemaining) > 100
+    const percentage = isBatPercent
+      ? Math.max(0, Math.min(100, Math.round(Number(percentageOrBatPercentRemaining) / 2)))
+      : Math.max(0, Math.min(100, Math.round(Number(percentageOrBatPercentRemaining))))
+
+    let chargeLevel = 0 // Ok
+    if (percentage < 20) {
+      chargeLevel = 2 // Critical
+    } else if (percentage < 40) {
+      chargeLevel = 1 // Warning
+    }
+
+    this.logInfo(`battery status: ${percentage}% (${chargeLevel === 0 ? 'Ok' : chargeLevel === 1 ? 'Warning' : 'Critical'})`)
+
+    if (this.context) {
+      (this.context as any).batteryPercentage = percentage
+      ;(this.context as any).batteryChargeLevel = chargeLevel
+    }
   }
 
-  public updateCurrentArea(areaId: number | null): void {
-    this.updateState('serviceArea', { currentArea: areaId })
-    if (areaId !== null) {
-      const areaName = ['Living Room', 'Kitchen', 'Bedroom', 'Bathroom'][areaId] || `Area ${areaId}`
-      this.logInfo(`current area updated to: ${areaName}`)
-    } else {
-      this.logInfo('current area cleared')
+  private async handleDock(): Promise<void> {
+    this.logInfo('Docking the vacuum.')
+    try {
+      this.logInfo('[OpenAPI] Sending dock command')
+      await this.sendOpenAPICommand('dock')
+      this.logInfo('[OpenAPI] Dock command sent successfully')
+      this.updateRunMode(0) // Set to Idle after docking
+      this.updateOperationalState(64) // Seeking Charger state
+    } catch (error: any) {
+      this.logWarn(`Docking failed: ${String(error?.message ?? error)}`)
     }
   }
 
-  public updateProgress(progress: Array<{ areaId: number, status: number }>): void {
-    this.updateState('serviceArea', { progress })
-    this.logInfo(`progress updated: ${progress.length} areas`)
+  private async handleServiceArea(): Promise<void> {
+    this.logWarn(`Service area functionality is not supported for model: ${this.model}`)
+    // Placeholder for potential future support.
   }
 
-  /**
-   * Update battery percentage
-   * @param percentage - Battery percentage (0-100)
-   */
-  public async updateBatteryPercentage(percentage: number): Promise<void> {
-    // Convert percentage to Matter format (0-200, where 200 = 100%)
-    const batPercentRemaining = Math.max(0, Math.min(200, Math.round(percentage * 2)))
+  private async simulateCleaningSequence(): Promise<void> {
+    this.logInfo('Starting cleaning sequence simulation.')
+    this.updateOperationalState(1) // Set to Running
+
+    setTimeout(async () => {
+      this.logInfo('Cleaning sequence timer expired. Requesting device status update.')
+      try {
+        const status = await this.requestDeviceStatus()
+        if (status && status.operationalState) {
+          this.logInfo(`Device status found: ${status.operationalState}`)
+          this.updateOperationalState(status.operationalState)
+        } else {
+          this.logWarn('Device status not found. Setting operational state to Stopped.')
+          this.updateOperationalState(0) // Default to Stopped
+        }
+      } catch (error: any) {
+        this.logWarn(`Failed to fetch device status: ${String(error?.message ?? error)}`)
+        this.updateOperationalState(0) // Default to Stopped
+      }
+    }, 5000) // Simulate a 5-second cleaning sequence
+  }
 
-    // Determine charge level based on percentage
-    let batChargeLevel = 0 // Ok
-    if (percentage < 20) {
-      batChargeLevel = 2 // Critical
-    } else if (percentage < 40) {
-      batChargeLevel = 1 // Warning
+  private async simulateDockingSequence(): Promise<void> {
+    this.logInfo('Starting docking sequence simulation.')
+    this.updateOperationalState(64) // Set to Seeking Charger
+
+    setTimeout(async () => {
+      this.logInfo('Docking sequence timer expired. Requesting device status update.')
+      try {
+        const status = await this.requestDeviceStatus()
+        if (status && status.operationalState) {
+          this.logInfo(`Device status found: ${status.operationalState}`)
+          this.updateOperationalState(status.operationalState)
+        } else {
+          this.logWarn('Device status not found. Setting operational state to Docked.')
+          this.updateOperationalState(66) // Default to Docked
+        }
+      } catch (error: any) {
+        this.logWarn(`Failed to fetch device status: ${String(error?.message ?? error)}`)
+        this.updateOperationalState(66) // Default to Docked
+      }
+    }, 5000) // Simulate a 5-second docking sequence
+  }
+
+  private async requestDeviceStatus(): Promise<{ operationalState?: number } | null> {
+    this.logInfo('Requesting device status from OpenAPI.')
+    try {
+      const response = await this.sendOpenAPICommand('getDeviceStatus')
+      this.logInfo(`Device status response: ${JSON.stringify(response)}`)
+      return response
+    } catch (error: any) {
+      this.logWarn(`Failed to request device status: ${String(error?.message ?? error)}`)
+      return null
     }
+  }
+
+  public async startCleaningSimulation(): Promise<void> {
+    this.logInfo('Initiating cleaning simulation.')
+    await this.simulateCleaningSequence()
+  }
 
-    await this.updateState('powerSource', { batPercentRemaining, batChargeLevel })
-    this.logInfo(`battery updated to: ${percentage}% (${batChargeLevel === 0 ? 'Ok' : batChargeLevel === 1 ? 'Warning' : 'Critical'})`)
+  public async startDockingSimulation(): Promise<void> {
+    this.logInfo('Initiating docking simulation.')
+    await this.simulateDockingSequence()
   }
 }