@homebridge-plugins/homebridge-ecovacs 7.2.2 → 7.2.4-beta.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to homebridge-ecovacs will be documented in this file.
 
+## v7.2.4 (Unreleased)
+
+### Changes
+
+- updated dependencies
+- option to expose as a vacuum robot in homekit
+
+## v7.2.3 (2025-07-24)
+
+### Other Changes
+
+- dependency updates
+
 ## v7.2.2 (2025-07-18)
 
 ### Other Changes

package/lib/platform.js

@@ -13,6 +13,7 @@ const require = createRequire(import.meta.url)
 const plugin = require('../package.json')
 
 const devicesInHB = new Map()
+const matterDevicesInHB = new Map()
 
 export default class {
   constructor(log, config, api) {
@@ -26,6 +27,9 @@ export default class {
       this.log = log
       this.isBeta = plugin.version.includes('beta')
 
+      // Check if Matter is available and enabled
+      this.matterEnabled = api.isMatterAvailable?.() && api.isMatterEnabled?.()
+
       // Configuration objects for accessories
       this.deviceConf = {}
       this.ignoredDevices = []
@@ -374,6 +378,13 @@ export default class {
       // Display version of the ecovacs-deebot library in the log
       this.log('%s v%s.', platformLang.ecovacsLibVersion, this.ecovacsAPI.getVersion())
 
+      // Log Matter availability
+      if (this.matterEnabled) {
+        this.log('Matter support is enabled - vacuums will be exposed via both HAP and Matter.')
+      } else {
+        this.log('Matter support is not available - vacuums will be exposed via HAP only.')
+      }
+
       // Attempt to log in to Ecovacs/Yeedi
       try {
         await this.ecovacsAPI.connect(this.config.username, EcoVacsAPI.md5(this.config.password))
@@ -440,6 +451,230 @@ export default class {
     }
   }
 
+  createMatterRVCAccessory(device, accessory) {
+    // Create a Matter RVC (Robotic Vacuum Cleaner) accessory config
+    const serialNumber = device.did
+    const displayName = device.nick || device.did
+
+    // Get device types we need
+    const RoboticVacuumCleanerType = this.api.matter.deviceTypes.RoboticVacuumCleaner
+
+    // Create bound handler functions that preserve the platform context
+    const boundHandlers = {
+      rvcRunMode: {
+        changeToMode: (request) => {
+          return this.handleMatterRunModeChange(accessory, request)
+        },
+      },
+      rvcOperationalState: {
+        pause: () => {
+          return this.handleMatterPause(accessory)
+        },
+        stop: () => {
+          return this.handleMatterStop(accessory)
+        },
+        start: () => {
+          return this.handleMatterStart(accessory)
+        },
+        resume: () => {
+          return this.handleMatterResume(accessory)
+        },
+        goHome: () => {
+          return this.handleMatterGoHome(accessory)
+        },
+      },
+    }
+
+    return {
+      uuid: this.api.matter.uuid.generate(serialNumber),
+      displayName,
+      deviceType: RoboticVacuumCleanerType,
+      serialNumber,
+      manufacturer: device.company || 'Ecovacs',
+      model: device.deviceModel || 'Deebot',
+      firmwareRevision: '1.0.0',
+      hardwareRevision: '1.0.0',
+
+      context: {
+        hapAccessoryUUID: accessory.UUID,
+        deviceId: device.did,
+      },
+
+      clusters: {
+        // Run Mode: Idle or Cleaning
+        rvcRunMode: {
+          supportedModes: [
+            { label: 'Idle', mode: 0, modeTags: [{ value: 16384 }] }, // RvcRunMode.ModeTag.Idle
+            { label: 'Cleaning', mode: 1, modeTags: [{ value: 16385 }] }, // RvcRunMode.ModeTag.Cleaning
+          ],
+          currentMode: 0, // Start as Idle
+        },
+        // Clean Mode: Just Vacuum mode
+        rvcCleanMode: {
+          supportedModes: [
+            { label: 'Vacuum', mode: 0, modeTags: [{ value: 16385 }] }, // RvcCleanMode.ModeTag.Vacuum
+          ],
+          currentMode: 0,
+        },
+        // Operational State
+        rvcOperationalState: {
+          operationalStateList: [
+            { operationalStateId: 0, operationalStateLabel: 'Stopped' },
+            { operationalStateId: 1, operationalStateLabel: 'Running' },
+            { operationalStateId: 2, operationalStateLabel: 'Paused' },
+            { operationalStateId: 3, operationalStateLabel: 'Error' },
+            { operationalStateId: 64, operationalStateLabel: 'Seeking Charger' },
+            { operationalStateId: 65, operationalStateLabel: 'Charging' },
+            { operationalStateId: 66, operationalStateLabel: 'Docked' },
+          ],
+          operationalState: 66, // Start docked
+        },
+      },
+
+      handlers: boundHandlers,
+    }
+  }
+
+  async handleMatterRunModeChange(accessory, request) {
+    try {
+      const { newMode } = request
+      accessory.logDebug(`Matter: ChangeToMode (run) request received: mode=${newMode}`)
+
+      if (newMode === 1) {
+        // Switching to Cleaning mode - start cleaning
+        await this.internalCleanUpdate(accessory, true)
+      } else if (newMode === 0) {
+        // Switching to Idle mode - stop or return to dock
+        await this.internalChargeUpdate(accessory, true)
+      }
+    } catch (err) {
+      accessory.logWarn(`Matter: Run mode change failed ${parseError(err)}`)
+    }
+  }
+
+  async handleMatterPause(accessory) {
+    try {
+      accessory.logDebug('Matter: Pause request received')
+      // Stop the vacuum
+      // TODO work out which devices have a pause and implement properly
+      await this.internalCleanUpdate(accessory, false)
+
+      // Update Matter states immediately
+      this.updateMatterRunMode(accessory, 0) // idle
+      this.updateMatterOperationalState(accessory, 0) // stopped
+    } catch (err) {
+      accessory.logWarn(`Matter: Pause failed ${parseError(err)}`)
+    }
+  }
+
+  async handleMatterStop(accessory) {
+    try {
+      accessory.logDebug('Matter: Stop request received')
+      await this.internalCleanUpdate(accessory, false)
+
+      // Update Matter states immediately
+      this.updateMatterRunMode(accessory, 0) // idle
+      this.updateMatterOperationalState(accessory, 0) // stopped
+    } catch (err) {
+      accessory.logWarn(`Matter: Stop failed ${parseError(err)}`)
+    }
+  }
+
+  async handleMatterStart(accessory) {
+    try {
+      accessory.logDebug('Matter: Start request received')
+      await this.internalCleanUpdate(accessory, true)
+    } catch (err) {
+      accessory.logWarn(`Matter: Start failed ${parseError(err)}`)
+    }
+  }
+
+  async handleMatterResume(accessory) {
+    try {
+      accessory.logDebug('Matter: Resume request received')
+      await this.internalCleanUpdate(accessory, true)
+    } catch (err) {
+      accessory.logWarn(`Matter: Resume failed ${parseError(err)}`)
+    }
+  }
+
+  async handleMatterGoHome(accessory) {
+    try {
+      accessory.logDebug('Matter: GoHome request received')
+      await this.internalChargeUpdate(accessory, true)
+    } catch (err) {
+      accessory.logWarn(`Matter: GoHome failed ${parseError(err)}`)
+    }
+  }
+
+  updateMatterOperationalState(accessory, state) {
+    // Update Matter operational state if Matter is enabled and accessory has Matter UUID
+    if (!this.matterEnabled || !accessory.matterUUID || !accessory.matterReady) {
+      return
+    }
+
+    try {
+      this.api.matter.updateAccessoryState(accessory.matterUUID, 'rvcOperationalState', {
+        operationalState: state,
+      })
+      accessory.logDebug(`Matter: Operational state updated to ${state}`)
+    } catch (err) {
+      accessory.logError(`Matter: Failed to update operational state: ${parseError(err)}`)
+    }
+  }
+
+  updateMatterRunMode(accessory, mode) {
+    // Update Matter run mode if Matter is enabled and accessory has Matter UUID
+    if (!this.matterEnabled || !accessory.matterUUID || !accessory.matterReady) {
+      return
+    }
+
+    try {
+      this.api.matter.updateAccessoryState(accessory.matterUUID, 'rvcRunMode', {
+        currentMode: mode,
+      })
+      accessory.logDebug(`Matter: Run mode updated to ${mode}`)
+    } catch (err) {
+      accessory.logError(`Matter: Failed to update run mode: ${parseError(err)}`)
+    }
+  }
+
+  updateMatterStateFromHAP(accessory) {
+    // Sync current HAP state to Matter when Matter becomes ready
+    if (!this.matterEnabled || !accessory.matterUUID || !accessory.matterReady) {
+      return
+    }
+
+    try {
+      // Sync cleaning state
+      const isActive = ['auto', 'clean', 'edge', 'spot', 'spotarea', 'customarea'].includes(
+        (accessory.context.cacheClean || '').toLowerCase().replace(/[^a-z]+/g, ''),
+      )
+      if (isActive) {
+        this.updateMatterRunMode(accessory, 1) // Cleaning
+        this.updateMatterOperationalState(accessory, 1) // Running
+      } else {
+        this.updateMatterRunMode(accessory, 0) // Idle
+      }
+
+      // Sync charging state
+      const chargeStateLower = (accessory.context.cacheCharge || '').toLowerCase()
+      if (chargeStateLower === 'charging') {
+        this.updateMatterOperationalState(accessory, 65) // charging
+      } else if (chargeStateLower === 'returning') {
+        this.updateMatterOperationalState(accessory, 64) // seeking charger
+      } else if (chargeStateLower === 'idle') {
+        this.updateMatterOperationalState(accessory, 66) // docked
+      } else if (!isActive) {
+        this.updateMatterOperationalState(accessory, 0) // stopped
+      }
+
+      accessory.logDebug('Matter: Initial state synchronized from HAP')
+    } catch (err) {
+      accessory.logError(`Matter: Failed to sync initial state: ${parseError(err)}`)
+    }
+  }
+
   initialiseDevice(device) {
     try {
       // Generate the Homebridge UUID from the device id
@@ -789,6 +1024,49 @@ export default class {
       this.api.updatePlatformAccessories([accessory])
       devicesInHB.set(accessory.UUID, accessory)
 
+      // Register Matter RVC accessory if Matter is enabled
+      if (this.matterEnabled) {
+        try {
+          const matterUUID = this.api.matter.uuid.generate(device.did)
+
+          // Check if this Matter accessory already exists
+          const existingMatterAccessory = matterDevicesInHB.get(matterUUID)
+
+          if (!existingMatterAccessory) {
+            // Create and publish new Matter RVC accessory
+            const matterAccessory = this.createMatterRVCAccessory(device, accessory)
+
+            // Mark Matter accessory as not ready yet
+            accessory.matterReady = false
+            accessory.matterUUID = matterUUID
+
+            // Publish the accessory and listen for the READY event
+            const published = this.api.matter.publishExternalAccessories(plugin.name, [matterAccessory])
+
+            // Listen for when the Matter accessory is ready
+            if (published && published[0] && published[0]._eventEmitter) {
+              published[0]._eventEmitter.on('ready', () => {
+                accessory.matterReady = true
+                accessory.log('Matter RVC accessory is ready.')
+
+                // Update initial state now that it's ready
+                this.updateMatterStateFromHAP(accessory)
+              })
+            }
+
+            matterDevicesInHB.set(matterUUID, matterAccessory)
+            this.log('[%s] Matter RVC accessory published.', accessory.displayName)
+          } else {
+            // Matter accessory already exists, just link it
+            accessory.matterUUID = matterUUID
+            accessory.matterReady = true // Assume existing accessories are ready
+            accessory.logDebug('Matter RVC accessory already registered.')
+          }
+        } catch (err) {
+          accessory.logWarn(`Failed to register Matter RVC accessory: ${parseError(err)}`)
+        }
+      }
+
       // Log configuration and device initialisation
       this.log(
         '[%s] %s: %s.',
@@ -912,31 +1190,38 @@ export default class {
   }
 
   configureAccessory(accessory) {
-    // Add the configured accessory to our global map
+    this.log.debug(`[${accessory.displayName}] loading cached hap accessory.`)
     devicesInHB.set(accessory.UUID, accessory)
-    accessory
-      .getService('Clean')
-      .getCharacteristic(this.api.hap.Characteristic.On)
-      .onSet(() => {
-        this.log.warn('[%s] %s.', accessory.displayName, platformLang.accNotReady)
-        throw new this.api.hap.HapStatusError(-70402)
-      })
-      .updateValue(new this.api.hap.HapStatusError(-70402))
-    accessory
-      .getService('Go Charge')
-      .getCharacteristic(this.api.hap.Characteristic.On)
-      .onSet(() => {
-        this.log.warn('[%s] %s.', accessory.displayName, platformLang.accNotReady)
-        throw new this.api.hap.HapStatusError(-70402)
-      })
-      .updateValue(new this.api.hap.HapStatusError(-70402))
+  }
+
+  configureMatterAccessory(accessory) {
+    this.log.debug(`[${accessory.displayName}] loading cached matter accessory.`)
+    matterDevicesInHB.set(accessory.uuid, accessory)
   }
 
   removeAccessory(accessory) {
     // Remove an accessory from Homebridge
     try {
+      // Remove HAP accessory
       this.api.unregisterPlatformAccessories(plugin.name, plugin.alias, [accessory])
       devicesInHB.delete(accessory.UUID)
+
+      // Remove corresponding Matter accessory if it exists
+      if (this.matterEnabled && accessory.context.ecoDeviceId) {
+        try {
+          const matterUUID = this.api.matter.uuid.generate(accessory.context.ecoDeviceId)
+          const matterAccessory = matterDevicesInHB.get(matterUUID)
+
+          if (matterAccessory) {
+            this.api.matter.unpublishExternalAccessories([matterAccessory])
+            matterDevicesInHB.delete(matterUUID)
+            this.log.debug('[%s] Matter RVC accessory removed.', accessory.displayName)
+          }
+        } catch (matterErr) {
+          this.log.warn('[%s] Failed to remove Matter accessory: %s', accessory.displayName, parseError(matterErr))
+        }
+      }
+
       this.log('[%s] %s.', accessory.displayName, platformLang.devRemove)
     } catch (err) {
       // Catch any errors during remove
@@ -964,7 +1249,7 @@ export default class {
       const order = value ? `Clean${accessory.context.commandSuffix}` : 'Stop'
 
       // Log the update
-      accessory.log(`${platformLang.curCleaning} [${value ? platformLang.cleaning : platformLang.stop}}]`)
+      accessory.log(`${platformLang.curCleaning} [${value ? platformLang.cleaning : platformLang.stop}]`)
 
       // Send the command
       accessory.logDebug(`${platformLang.sendCmd} [${order}]`)
@@ -1255,15 +1540,25 @@ export default class {
 
       // Check if the new cleaning state is different from the cached state
       if (accessory.context.cacheClean !== newVal) {
-        // State is different so update service
+        const isActive = ['auto', 'clean', 'edge', 'spot', 'spotarea', 'customarea'].includes(
+          newVal.toLowerCase().replace(/[^a-z]+/g, ''),
+        )
+
+        // State is different so update HAP service
         accessory
           .getService('Clean')
-          .updateCharacteristic(
-            this.hapChar.On,
-            ['auto', 'clean', 'edge', 'spot', 'spotarea', 'customarea'].includes(
-              newVal.toLowerCase().replace(/[^a-z]+/g, ''),
-            ),
-          )
+          .updateCharacteristic(this.hapChar.On, isActive)
+
+        // Update Matter states
+        if (isActive) {
+          // Vacuum is cleaning
+          this.updateMatterRunMode(accessory, 1) // Cleaning mode
+          this.updateMatterOperationalState(accessory, 1) // Running state
+        } else {
+          // Vacuum is not cleaning - could be idle or stopped
+          this.updateMatterRunMode(accessory, 0) // Idle mode
+          this.updateMatterOperationalState(accessory, 0) // Stopped state
+        }
 
         // Log the change
         accessory.log(`${platformLang.curCleaning} [${newVal}]`)
@@ -1356,7 +1651,7 @@ export default class {
 
       // Check if the new charging state is different from the cached state
       if (accessory.context.cacheCharge !== newVal) {
-        // State is different so update service
+        // State is different so update HAP service
         accessory
           .getService('Go Charge')
           .updateCharacteristic(this.hapChar.On, newVal === 'returning')
@@ -1365,6 +1660,19 @@ export default class {
           .getService(this.hapServ.Battery)
           .updateCharacteristic(this.hapChar.ChargingState, chargeState)
 
+        // Update Matter operational state based on charge state
+        const chargeStateLower = newVal.toLowerCase()
+        if (chargeStateLower === 'charging') {
+          this.updateMatterRunMode(accessory, 0) // Idle mode
+          this.updateMatterOperationalState(accessory, 65) // Charging
+        } else if (chargeStateLower === 'returning') {
+          this.updateMatterRunMode(accessory, 0) // Idle mode
+          this.updateMatterOperationalState(accessory, 64) // Seeking Charger
+        } else if (chargeStateLower === 'idle') {
+          this.updateMatterRunMode(accessory, 0) // Idle mode
+          this.updateMatterOperationalState(accessory, 66) // Docked
+        }
+
         // Log the change
         accessory.log(`${platformLang.curCharging} [${newVal}]`)
       }

package/package.json

@@ -3,7 +3,7 @@
   "displayName": "Homebridge Ecovacs",
   "alias": "Deebot",
   "type": "module",
-  "version": "7.2.2",
+  "version": "7.2.4-beta.0",
   "description": "Homebridge plugin to integrate Ecovacs Deebot devices into HomeKit.",
   "author": {
     "name": "bwp91",
@@ -63,15 +63,15 @@
   },
   "dependencies": {
     "@homebridge/plugin-ui-utils": "^2.1.0",
-    "ecovacs-deebot": "^0.9.6-beta.8",
-    "patch-package": "^8.0.0"
+    "ecovacs-deebot": "^0.9.6-beta.12",
+    "patch-package": "^8.0.1"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^4.17.0"
+    "@antfu/eslint-config": "^6.1.0"
   },
   "overrides": {
-    "ecovacs-deebot": {
-      "axios": "^1.10.0"
+    "request": {
+      "form-data": "^2.5.4"
     }
   }
 }

package/patches/{ecovacs-deebot+0.9.6-beta.8.patch → ecovacs-deebot+0.9.6-beta.12.patch}

@@ -1,5 +1,5 @@
 diff --git a/node_modules/ecovacs-deebot/library/tools.js b/node_modules/ecovacs-deebot/library/tools.js
-index d484ba1..1ad1f14 100644
+index d484ba1..eb8e866 100644
 --- a/node_modules/ecovacs-deebot/library/tools.js
 +++ b/node_modules/ecovacs-deebot/library/tools.js
 @@ -369,11 +369,13 @@ function envLogRaw(message) {