@switchbot/homebridge-switchbot 5.0.0-beta.52 → 5.0.0-beta.53

package/src/devices-matter/RoboticVacuumAccessory.ts

@@ -1,97 +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 ?? {
-      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',
@@ -101,224 +171,199 @@ 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: (() => {
+          if (capabilities.cleanAction === 'vacuum-only') {
+            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,
+            }
+          } else if (capabilities.cleanAction === 'vacuum-or-mop') {
+            return {
+              supportedModes: [
+                { label: 'Vacuum', mode: 0, modeTags: [{ value: 16385 }] },
+                { label: 'Mop', mode: 1, modeTags: [{ value: 16386 }] },
+              ],
+              currentMode: 0,
+            }
+          } else {
+            return {
+              supportedModes: [
+                { label: 'Vacuum', mode: 0, modeTags: [{ value: 16385 }] },
+                { label: 'Vacuum & Mop', mode: 1, modeTags: [{ value: 16385 }, { value: 16386 }] },
+              ],
+              currentMode: 0,
+            }
+          }
+        })(),
+        rvcOperationalState: {
+          operationalStateList: [
+            { operationalStateId: 0 }, // Stopped
+            { operationalStateId: 1 }, // Running
+            { operationalStateId: 2 }, // Paused
+            { operationalStateId: 64 }, // Seeking Charger
+            { operationalStateId: 65 }, // Charging
+            { operationalStateId: 66 }, // Docked
+          ],
+          operationalState: 66,
+        },
+      },
+      handlers: (() => {
+        const opHandlers: Record<string, any> = {
+          stop: async () => this.handleStop(),
+          start: async () => this.handleStart(),
+          goHome: async () => this.handleGoHome(),
+        }
+        if (capabilities.pause) {
+          opHandlers.pause = async () => this.handlePause()
+        }
+        if (capabilities.resume) {
+          opHandlers.resume = async () => this.handleResume()
+        }
+        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})`
+    const modeStr = ['Idle', 'Cleaning'][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)
+      await this.handleStart()
     } 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)
+      await this.handleGoHome()
     }
   }
 
   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)
+    if (this.capabilities.cleanAction === 'vacuum-only') {
+      const mapPow = ['Quiet', 'Standard', 'Strong', 'MAX'] as const
+      const label = mapPow[newMode] ?? `Unknown (${newMode})`
+      this.logInfo(`changing suction level to: ${label}`)
+      if (this.capabilities.suctionKind === 'powLevel-0-3') {
+        try {
+          await this.sendOpenAPICommand('PowLevel', String(newMode))
+        } catch (e: any) {
+          this.logWarn(`OpenAPI PowLevel failed: ${String(e?.message ?? e)}`)
+        }
+      } else if (this.capabilities.suctionKind === 'fanLevel-1-4') {
+        this.currentFanLevel = (Math.min(3, Math.max(0, Number(newMode))) + 1) as 1 | 2 | 3 | 4
+        try {
+          await this.sendOpenAPICommand('changeParam', JSON.stringify({ fanLevel: this.currentFanLevel }))
+        } catch (e: any) {
+          this.logWarn(`OpenAPI changeParam(fanLevel) failed: ${String(e?.message ?? e)}`)
+        }
+      }
+      this.updateCleanMode(newMode)
+      return
+    }
+
+    if (this.capabilities.cleanAction === 'vacuum-or-mop') {
+      const label = newMode === 0 ? 'Vacuum' : 'Mop'
+      this.currentCleanAction = newMode === 0 ? 'vacuum' : 'mop'
+      this.logInfo(`changing clean action to: ${label}`)
+      this.updateCleanMode(newMode)
+      return
+    }
+
+    const label = newMode === 0 ? 'Vacuum' : 'Vacuum & Mop'
+    this.currentCleanAction = newMode === 0 ? 'vacuum' : 'vacuum_mop'
+    this.logInfo(`changing clean action to: ${label}`)
+    this.updateCleanMode(newMode)
   }
 
   private async handlePause(): Promise<void> {
     this.logInfo('pausing.')
-    // TODO: await myVacuumAPI.pause()
-    this.clearTimers() // Clear cleaning completion timer
-    this.updateOperationalState(2) // Paused
+    try {
+      await this.sendOpenAPICommand('pause')
+    } 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') {
+        await this.sendOpenAPICommand('stop')
+      } else {
+        await this.sendOpenAPICommand('pause')
+      }
+    } 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') {
+        await this.sendOpenAPICommand('start')
+      } 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
+        }
+        await this.sendOpenAPICommand('startClean', 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.')
+    await this.handleStart()
   }
 
   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 {
+      await this.sendOpenAPICommand('dock')
+    } 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',
@@ -328,76 +373,32 @@ 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})`}`)
-  }
-
-  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'}`)
-  }
-
-  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}`)
+    let label = `Unknown (${mode})`
+    if (this.capabilities.cleanAction === 'vacuum-only') {
+      label = ['Quiet', 'Standard', 'Strong', 'MAX'][mode] || label
+    } else if (this.capabilities.cleanAction === 'vacuum-or-mop') {
+      label = ['Vacuum', 'Mop'][mode] || label
     } else {
-      this.logInfo('current area cleared')
+      label = ['Vacuum', 'Vacuum & Mop'][mode] || label
     }
-  }
-
-  public updateProgress(progress: Array<{ areaId: number, status: number }>): void {
-    this.updateState('serviceArea', { progress })
-    this.logInfo(`progress updated: ${progress.length} areas`)
+    this.logInfo(`clean mode updated to: ${label}`)
   }
 
   /**
-   * Update battery percentage
-   *
-   * Note: The Matter specification for RoboticVacuumCleaner does not include
-   * the PowerSource cluster. Battery information for robotic vacuums should be
-   * communicated through device-specific status reporting or via the RVC
-   * operational state cluster.
-   *
-   * This method is retained for API compatibility but does not update any
-   * Matter cluster state.
-   *
-   * @param percentageOrBatPercentRemaining - Battery percentage (0-100) or batPercentRemaining (0-200)
+   * Update battery percentage (no PowerSource cluster for this device type)
    */
   public async updateBatteryPercentage(percentageOrBatPercentRemaining: number): Promise<void> {
-    // Accept either 0–100 (percentage) or 0–200 (batPercentRemaining) to be robust
     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))))
 
-    // Determine charge level based on percentage
     let chargeLevel = 0 // Ok
     if (percentage < 20) {
       chargeLevel = 2 // Critical
@@ -405,10 +406,8 @@ export class RoboticVacuumAccessory extends BaseMatterAccessory {
       chargeLevel = 1 // Warning
     }
 
-    // Log battery status only - PowerSource cluster is not supported for RoboticVacuumCleaner
     this.logInfo(`battery status: ${percentage}% (${chargeLevel === 0 ? 'Ok' : chargeLevel === 1 ? 'Warning' : 'Critical'})`)
 
-    // Store battery info in context for reference
     if (this.context) {
       (this.context as any).batteryPercentage = percentage
       ;(this.context as any).batteryChargeLevel = chargeLevel