homebridge-roborock-vacuum 1.7.2 → 2.0.0

package/CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
+## 2.0.0
+
+- **New Feature**: Matter protocol support (Beta)
+  - Per-device protocol selector in the settings UI: publish each vacuum over **HomeKit (HAP)** (default), **Matter (Beta)**, or skip it
+  - Vacuums publish as native Matter robotic vacuum cleaners: proper vacuum icon and controls in Apple Home (also works with Google Home, Alexa, SmartThings)
+  - **Room cleaning** through the Matter ServiceArea cluster (Apple Home needs iOS 18.4+): pick named rooms in the controller and clean only those; the room currently being cleaned is reported live
+  - **Vacuum / Mop / Vacuum & Mop** clean modes mapped to the Roborock suction and water-box settings; models without a water box only offer Vacuum
+  - Battery, charging state and operational errors (stuck, dust bin missing, dock problems, …) reported over Matter
+  - Roborock **scenes** as Matter on/off buttons on the plugin's own bridge, with a per-device "Bridge scene buttons over Matter" toggle
+  - Pairing QR codes, commissioning status and naming hints shown on the settings page (per device, plus the scene-button bridge)
+  - Requires **Homebridge 2.x with Matter enabled**; on Homebridge 1.x (or with Matter disabled) Matter selections safely fall back to HAP
+  - **Known limitations (Beta)**: Apple Home's Matter support for vacuums is still immature — expect the "Uncertified Accessory" warning, a generic "Matter Accessory" name during pairing (type the name shown in the settings page), and occasional instability. See the README's "Matter support (Beta)" section
+- **Improvement**: Settings page loads the device list instantly from a local cache (prefetched at login, refreshed in the background); "Load devices" forces a cloud refresh
+- **Fix**: Matter accessories now receive live state updates (state, battery, clean mode) instead of only the startup snapshot
+- **Fix**: Duplicate scene names across multiple Matter vacuums are suffixed with the vacuum name regardless of discovery order
+
 ## 1.2.2
+
 - **New Feature**: Dynamic Scene Switch Management
   - Automatically create HomeKit switch buttons for each device's available scenes
   - Scene switches named after scene names with momentary switch behavior
@@ -11,9 +28,11 @@
 - **Fix**: Resolved recursive call issue in scene methods
 
 ## 1.0.15
+
 - Fix Roborock Saros 10R Status issue
 
 ## 1.0.6
+
 - Support new model
 
 ## 1.0.0

package/README.md

@@ -69,9 +69,50 @@ Follow these steps to install the plugin:
 
 ## Configuration
 
-Use the Homebridge UI settings page to sign in and configure the plugin. To exclude vacuums from HomeKit, add their Roborock device IDs to **Skipped Device IDs**.
+Use the Homebridge UI settings page to sign in and configure the plugin. Click **Load devices** to list the vacuums on your account, then choose a protocol for each one:
 
-When Homebridge restarts, matching devices will be skipped during discovery. If a skipped device already exists in HomeKit as a cached accessory, the plugin will remove it from Homebridge.
+- **HomeKit (HAP)** — the default. The vacuum is bridged to Apple Home as a fan-style accessory, as in previous versions.
+- **Matter (Beta)** — the vacuum is published over Matter as a robotic vacuum cleaner, so it gets the native vacuum icon and controls in Apple Home (and works with Google Home, Alexa and SmartThings). This is an experimental feature — read the [Matter support (Beta)](#matter-support-beta) section below before enabling it.
+- **Skip** — the vacuum is excluded entirely. You can also enter device IDs manually in the list below; manual entries are always skipped.
+
+When Homebridge restarts, each device is (re)published according to its selection. A device that was cached under a different protocol (or is now skipped) is removed from the old bridge first. **Changing a device's protocol re-creates the accessory**, so it loses its room and automation assignments in your home app and must be re-organized there.
+
+### Matter support (Beta)
+
+> ⚠️ **This is an experimental, lab-grade beta feature.** Matter support for robotic vacuums is still very new on the controller side. In particular, **Apple Home's compatibility is currently poor and not very stable**: the bridge is uncertified (Apple shows an "Uncertified Accessory" warning), the accessory appears as a generic **"Matter Accessory"** during pairing and must be named manually, room selection needs iOS 18.4 or later, and accessories can occasionally show "Not responding" or lose features after iOS updates. If you want the most reliable day-to-day experience, stay on **HomeKit (HAP)**. Choose Matter only if you want the native vacuum UI and room cleaning, and can live with rough edges.
+
+#### What you get over Matter
+
+- The **native robot-vacuum accessory** in Apple Home (proper icon, start/stop, Siri) instead of the fan-style HAP accessory.
+- **Room cleaning**: the vacuum's named rooms are exposed through the Matter ServiceArea cluster. Pick rooms in the controller and start cleaning — selecting none (or all) runs a full clean. While a room clean runs, the controller shows the room currently being cleaned.
+- **Vacuum / Mop / Vacuum & Mop** clean modes, mapped to the Roborock suction and water-box settings (models without a water box only offer Vacuum).
+- **Battery, charging state and error reporting** (stuck, dust bin missing, dock unreachable, … are surfaced as Matter operational errors).
+- Every Roborock **scene** that targets the device becomes an on/off button (see step 5 below). When the same scene name exists on more than one Matter vacuum, the vacuum's name is appended to keep the buttons distinguishable.
+- **Identify** ("play sound to locate" in Apple Home) plays the vacuum's find-me sound.
+
+Run-mode semantics follow the Matter spec: setting the run mode to **Idle stops** the vacuum where it is; use the **dock/Go Home** control to send it back to the charger.
+
+#### Requirements
+
+- **Homebridge 2.x** with Matter enabled on the bridge this plugin runs on (Homebridge 1.x, or Matter disabled, silently falls back to HAP with a log warning — nothing breaks).
+- For room cleaning in Apple Home: **iOS 18.4 or later**, and rooms must be **named in the Roborock app** (unnamed rooms are not published; the room list loads shortly after Homebridge starts).
+
+#### Setup steps
+
+1. **Enable Matter on the bridge.** If the plugin runs as a child bridge (the default when configured through the Homebridge UI), tick **"Enable Matter on this plugin's child bridge"** on the plugin settings page (writes `_bridge.matter` for you). If it runs on the main bridge, set `"matter": true` on the `bridge` block in `config.json`. Restart Homebridge to apply.
+2. **Select the protocol.** On the plugin settings page press **Load devices** and set the vacuum's dropdown to **Matter (Beta)**, then restart Homebridge. The per-device Matter option only appears when the relevant bridge has Matter enabled.
+3. **Pair the vacuum.** Reopen the settings page — a pairing panel with a QR code, the manual pairing code and the commissioning status appears under every Matter-selected device (each device is its own Matter node with its **own** pairing code). In Apple Home choose **Add Accessory** and scan the QR code. Expect the **"Uncertified Accessory"** warning (press _Add Anyway_) and a generic **"Matter Accessory"** name — when asked for a name, type the device name shown in the pairing panel.
+4. **Try it.** Start/stop from the accessory tile, pick rooms (iOS 18.4+) before starting for a room clean, and use the dock control to send it home.
+5. **Optional — scene buttons.** The scene buttons live on the plugin's **own Matter bridge**, which is a separate pairing from the vacuum. Scroll to the bottom of the device list on the settings page and scan the additional bridge QR code to add them. Scene list changes are picked up on the next Homebridge restart.
+
+Pairing is one-time per node — switching a device between HAP and Matter later does **not** require re-pairing, but note that **changing a device's protocol re-creates the accessory**, so room and automation assignments in your home app are lost and must be re-organized.
+
+#### Known limitations
+
+- **Apple Home compatibility is immature** — see the warning at the top of this section. Treat this as a beta and expect to occasionally re-pair or restart Homebridge after controller/iOS updates.
+- The device always pairs as a generic, uncertified **"Matter Accessory"**: controllers look the bridge's test vendor ID up in the certification database and ignore the name the device advertises, so the name must be entered manually (the pairing panel shows what to type).
+- Scene buttons require the **separate bridge pairing** (step 5) and appear as plain on/off switches in the controller.
+- Multi-floor maps are not exposed (rooms come from the currently active map), and zone cleaning, consumables and dock controls are not available over Matter yet.
 
 ## Current Room → MQTT (optional telemetry)
 

package/config.schema.json

@@ -30,6 +30,16 @@
         "type": "string",
         "description": "Roborock device IDs to exclude from HomeKit."
       },
+      "matterDevices": {
+        "title": "Matter Device IDs",
+        "type": "string",
+        "description": "Roborock device IDs to publish over Matter instead of HAP. Requires Homebridge 2.x with Matter enabled; ignored otherwise."
+      },
+      "matterSceneDevices": {
+        "title": "Matter Scene Button Device IDs",
+        "type": "string",
+        "description": "Matter device IDs whose Roborock scenes are bridged as Matter buttons. When omitted, scene buttons are enabled for every Matter device."
+      },
       "baseURL": {
         "type": "string",
         "default": "https://usiot.roborock.com",

package/dist/base_matter_accessory.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Base Matter Accessory Class
+ *
+ * Provides common functionality for all Matter devices.
+ * Based on @homebridge-plugins/homebridge-matter implementation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseMatterAccessory = void 0;
+/**
+ * Base class for all Matter accessories
+ * Implements the MatterAccessory interface and provides common methods
+ */
+class BaseMatterAccessory {
+    constructor(api, log, config) {
+        this.api = api;
+        this.log = log;
+        // Set all required properties
+        this.UUID = config.UUID;
+        this.displayName = config.displayName;
+        this.deviceType = config.deviceType;
+        this.serialNumber = config.serialNumber;
+        this.manufacturer = config.manufacturer;
+        this.model = config.model;
+        this.firmwareRevision = config.firmwareRevision;
+        this.hardwareRevision = config.hardwareRevision;
+        this.clusters = config.clusters;
+        this.handlers = config.handlers;
+        this.parts = config.parts;
+        // Set context with all metadata
+        this.context = {
+            serialNumber: this.serialNumber,
+            manufacturer: this.manufacturer,
+            model: this.model,
+            firmwareRevision: this.firmwareRevision,
+            hardwareRevision: this.hardwareRevision,
+            ...config.context,
+        };
+    }
+    /**
+     * Update the accessory state
+     * Helper method to update cluster attributes
+     */
+    async updateState(cluster, attributes, partId) {
+        const matter = this.api.matter;
+        if (!matter) {
+            return;
+        }
+        await matter.updateAccessoryState(this.UUID, cluster, attributes, partId);
+        this.log.debug(`[${this.displayName}] Updated ${cluster} state:`, attributes);
+    }
+    /**
+     * Log helper methods
+     */
+    logInfo(message, ...args) {
+        this.log.info(`[${this.displayName}] ${message}`, ...args);
+    }
+    logError(message, ...args) {
+        this.log.error(`[${this.displayName}] ${message}`, ...args);
+    }
+    logDebug(message, ...args) {
+        this.log.debug(`[${this.displayName}] ${message}`, ...args);
+    }
+    logWarn(message, ...args) {
+        this.log.warn(`[${this.displayName}] ${message}`, ...args);
+    }
+    /**
+     * Convert this class instance to a plain MatterAccessory object
+     * This is what gets registered with Homebridge
+     */
+    toAccessory() {
+        return {
+            UUID: this.UUID,
+            displayName: this.displayName,
+            deviceType: this.deviceType,
+            serialNumber: this.serialNumber,
+            manufacturer: this.manufacturer,
+            model: this.model,
+            firmwareRevision: this.firmwareRevision,
+            hardwareRevision: this.hardwareRevision,
+            context: this.context,
+            clusters: this.clusters,
+            handlers: this.handlers,
+            parts: this.parts,
+        };
+    }
+}
+exports.BaseMatterAccessory = BaseMatterAccessory;
+//# sourceMappingURL=base_matter_accessory.js.map

package/dist/base_matter_accessory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base_matter_accessory.js","sourceRoot":"","sources":["../src/base_matter_accessory.ts"],"names":[],"mappings":"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"}