homebridge-roborock-vacuum2

A Homebridge plugin to integrate your Roborock vacuum cleaner with Apple HomeKit, allowing you to control it via the Home app and Siri.

Introduction

homebridge-roborock-vacuum2 brings your Roborock vacuum cleaner into Apple HomeKit. Using your Roborock app account credentials, this plugin automatically detects your vacuum, enabling you to control it directly from the Home app on your iPhone, iPad, or Mac, or with Siri voice commands.

This plugin is inspired by and adapted from the ioBroker.roborock project by copystring.

Features

• Automatic Device Detection: No need to manually find or enter your vacuum's device ID.
• Local Transport Diagnostics: The plugin UI shows resolved model data, local key availability, discovered local IP, TCP connection state, whether the plugin is using local or cloud transport, and a live local TCP probe.
• HomeKit Cleaning Controls: Start or stop cleaning from the main HomeKit accessory, pause cleaning with a dedicated momentary switch, and send the vacuum back to the dock with a separate Return to Dock switch.
• Experimental Matter Vacuum: On Homebridge 2 with Matter enabled, optionally expose each robot as a Matter robotic vacuum while keeping the existing HomeKit fan/switch accessory for compatibility. Matter Service Area room selection is included for clients that support area selection.

The supported robots are:

Roborock S4 Roborock S4 Max Roborock S5 Max Roborock S6 Roborock S6 Pure Roborock S6 MaxV Roborock S7 Roborock S7 MaxV (Ultra) Roborock Q7 Roborock Q7 Max Roborock S7 Pro Ultra Roborock S7 Max Ultra Roborock S8 Roborock S8 Pro Ultra Roborock Q Revo Roborock Q8 Max Roborock Q5 Pro Roborock Q Revo Pro Roborock Qrevo S Roborock Qrevo Curve Roborock Saros 10 Roborock (roborock.vacuum.a95) Roborock (roborock.vacuum.a159) Roborock (roborock.vacuum.ss07)

Requirements

Before installing, ensure you have:

• A Roborock vacuum cleaner compatible with the Roborock app.
• A Roborock app account (email and password).
• Homebridge installed on a server (e.g., Raspberry Pi).
• Node.js and npm installed on your Homebridge server.

Installation

Follow these steps to install the plugin:

1. Install Homebridge (if not already installed):

   • Refer to the official Homebridge installation guide.

2. Install the Plugin:

   • Open a terminal and run:

     npm install -g homebridge-roborock-vacuum2

Configuration

Use the Homebridge plugin settings UI to sign in, save account settings, and inspect diagnostics.

| Setting | Required | Description | | ------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | email | Yes | Roborock account email used for login and device discovery. | | password | Token fallback | Roborock account password. The UI uses it to create an encrypted token; the plugin can also use it as a fallback if no valid token is available. | | encryptedToken | Token fallback | Encrypted Roborock session data generated by the plugin UI after a successful password or 2FA login. This field is managed by the UI. | | baseURL | No | Roborock cloud region endpoint. Use https://usiot.roborock.com for US, https://euiot.roborock.com for EU, https://cniot.roborock.com for CN, or https://api.roborock.com for Asia. | | skipDevices | No | Comma-separated Roborock serial numbers or DUIDs to ignore during discovery. The Diagnostics panel shows these values. | | debugMode | No | Enables verbose API, discovery, and transport logging in the Homebridge log. | | transientWarningThrottleHours | No | Hours between repeated transient timeout warnings for each vacuum. Defaults to 6. Use 0 to hide recurring transient warnings unless debug logging is enabled. | | enableMatter | No | Experimental. Also exposes each vacuum as a Matter robotic vacuum with Service Area room selection when running Homebridge 2 with Matter enabled for the Roborock child bridge. Defaults to false. | | cloudOnlyMode | No | Disables local LAN discovery and local TCP commands for this plugin, routing commands and status polling through Roborock cloud when available. Defaults to false; restart after changing it. | | preferCloudForMatterCommands | No | Sends Matter vacuum commands through the Roborock cloud when cloud transport is connected. Useful for models whose local LAN command acknowledgements time out. Defaults to false. |

The plugin needs either a valid encryptedToken or a password to start. A saved token is preferred because it avoids repeated password login attempts.

HomeKit Controls

HomeKit does not currently expose a dedicated vacuum service through Homebridge, so the vacuum appears as a fan-style accessory plus helper switches.

| HomeKit control | Behavior | | ------------------ | --------------------------------------------------------------------------- | | Main accessory on | Starts cleaning or resumes the current cleaning command. | | Main accessory off | Stops cleaning without automatically returning to the dock. | | Pause Cleaning | Sends Roborock's pause command, then resets the switch off. | | Return to Dock | Sends Roborock's dock command, then resets the switch off. | | Scene switches | Runs Roborock scenes discovered for the vacuum, then resets the switch off. |

Docking is intentionally separate from turning the main accessory off. This keeps "off" from unexpectedly ending a pause-only workflow and lets you choose whether the vacuum should remain stopped or return to the charger.

Matter Vacuum (Experimental)

Homebridge 2 can expose supported accessories over Matter. If you enable Enable experimental Matter vacuum in this plugin and Matter is enabled for your Homebridge bridge, the plugin registers a second, Matter-native robotic vacuum accessory for each supported Roborock.

This is opt-in because it can create an additional accessory in Apple Home. The original HomeKit fan-style accessory and helper switches remain available so existing automations and Homebridge 1.x installs keep working.

To set it up:

1. Run Homebridge 2 and enable Matter for the Roborock child bridge/daughter bridge in Homebridge. If this plugin runs in a child bridge, enabling Matter only on the main bridge is not enough.
2. Enable Enable experimental Matter vacuum in this plugin's settings.
3. Restart the Roborock child bridge.
4. Open the Homebridge logs and look for the Matter commissioning block for the Roborock vacuum. It includes lines such as Commissioning codes for Roborock S6 Pure, QR Code, and Manual Code.
5. Add the vacuum in Apple Home using the QR code or manual pairing code from the log.

Treat the Matter QR code and manual pairing code like temporary setup secrets; avoid posting logs that include them publicly.

Apple Home may show a generic Matter Accessory label during commissioning. The plugin sends the Roborock vacuum name to Homebridge, but the bridge name shown during pairing is controlled by Homebridge's Matter bridge/child-bridge configuration. If you want the pairing bridge to read like Matter Roborock Bridge, rename the Roborock child bridge/daughter bridge in Homebridge before pairing. Robotic vacuum cleaners are published by Homebridge as dedicated external Matter accessories for Apple Home compatibility, so Apple Home may ask you to add the vacuum after the bridge is commissioned; the plugin cannot force that second accessory confirmation to be skipped.

If you paired the experimental Matter vacuum before version 1.4.28 and Apple Home keeps showing the accessory as Updating, remove the Matter vacuum from Apple Home, restart the Roborock child bridge, and pair it again using the fresh code from the log.

The Matter vacuum controls map to the same Roborock commands used elsewhere in the plugin:

| Matter control | Behavior | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Run mode: Cleaning | Starts cleaning. If a Matter clean mode was selected, the plugin applies the matching Roborock suction/water settings first. | | Run mode: Idle | Stops cleaning without automatically returning to the dock. | | Clean mode: Vacuum | Uses Roborock vacuum/suction cleaning. On mop-capable models with controllable water flow, the plugin asks Roborock to turn water off. | | Clean mode: Mop | Shown only when the Roborock schema or feature list reports mop/water support. Uses mop cleaning and turns suction off where supported. | | Clean mode: Vacuum + Mop | Shown only when mop/water support is detected. Combines the standard Matter Vacuum and Mop clean-mode tags and enables both suction and mop/water settings where supported. | | Pause | Sends Roborock's pause command. | | Resume | Sends Roborock's start command and reapplies the selected clean mode if needed. | | Home / return to dock | Sends Roborock's dock command. | | Battery and run status | Mirrors the latest cached Roborock status where available. |

Mop clean modes are capability-gated so vacuum-only models should continue to show only Vacuum. On models with a passive mop or limited water controls, Matter may still show mop modes when mop support is detected, but the plugin can only apply the Roborock settings the model exposes.

If Matter commands consistently wait on local LAN timeouts before succeeding through cloud fallback, enable Prefer Roborock cloud for Matter commands. This only changes commands sent by the experimental Matter vacuum; the existing HomeKit fan/switch accessories keep their normal transport behavior.

If local LAN requests appear connected but consistently time out across commands and status polling, enable Use Roborock cloud only and restart the Roborock child bridge. This disables local LAN discovery and local TCP control for the plugin and routes commands and status refreshes through Roborock cloud when the cloud connection is available.

Matter Service Area

Matter Service Area room selection is included with the native Matter vacuum accessory. The plugin exposes the current Roborock room map as Matter Service Area entries. If a Matter client selects one or more areas and then starts cleaning, the plugin sends Roborock's room-clean command for those selected room segments instead of starting a whole-home clean.

Known limits:

• Apple Home and other Matter controllers may not show Service Area controls yet, or may present them differently across app/OS versions.
• If you paired the Matter vacuum before Service Area support was available, or if Apple Home does not show newly added area controls, remove the Matter vacuum from Apple Home, restart the Roborock child bridge, and pair it again using the fresh code from the Homebridge log. Matter controllers can cache the cluster list from the first pairing.
• The plugin can expose saved Roborock maps, such as upper and lower floors, when Roborock reports multi-map metadata. Some Matter controllers do not show the separate map/floor picker yet, so when more than one map is available the plugin also prefixes room labels with the map name, such as Upper Floor - Kitchen.
• Room mappings are cached per map as each map is seen. A saved map only appears once Roborock reports named room segments for it; a map that returns no room segments (for example a floor that has not been divided into named rooms in the Roborock app) cannot be exposed yet. While the robot is idle the plugin briefly loads other saved maps to cache their rooms, restores the map the robot started on afterward (even if a slow model is late to acknowledge the switch), and retries still-empty maps periodically so newly segmented floors appear without a Homebridge restart. If a room is missing from a floor, divide and name that floor's rooms in the Roborock app, then check the Homebridge log for room mapping updates.
• Starting a selected room on a map that is not currently active will ask Roborock to load that map first, then send the room-clean command.
• This does not replace the existing HomeKit scene switches. Those remain the most reliable way to expose saved Roborock routines.

Diagnostics

The plugin UI includes a Diagnostics section that reads cached HomeData and transport state from the Homebridge storage directory. It shows each discovered device's name, DUID, serial number, resolved model, local IP, local TCP state, cloud fallback state, and the last command transport. Use this section to confirm whether the plugin is using local TCP, ready for local control, falling back to Roborock cloud transport, or seeing the vacuum as offline.

When Use Roborock cloud only is enabled, Diagnostics reports the vacuum as Cloud only and the copied diagnostic report includes cloudOnlyMode: enabled.

Use Test Local Connection to run a live LAN TCP probe from the Homebridge environment to each cached vacuum's local IP on the Roborock local port. This does not send a cleaning command; it only confirms whether the local socket can be reached and reports latency, cached transport state, and whether cloud fallback is likely.

Use Copy Diagnostic Report when opening GitHub Issues. The copied report redacts tokens, local keys, full DUIDs, serial numbers, and the final local IP address octet while preserving the connection state and latest local test result needed for troubleshooting.

The copied report also includes compact Roborock status diagnostics when available, including recent get_status values and recent live cloud/local status payloads. When debug logging is enabled, the plugin also captures compact get_server_timer and get_timer responses so schedule-related feature requests can be investigated without exposing credentials.

The Homebridge log also records transport transitions in plain language, including local TCP connect/disconnect, cloud fallback reasons, local recovery, offline state, remote/shared devices, missing local credentials, and missing local IP discovery.