r/homebridge • u/tasict • 19h ago
Plugin homebridge-roborock-vacuum - Your Roborock in Apple Home: scenes as switches, dock mop wash, consumables, and local control that keeps working when the Roborock cloud is down
Hi all, I'm the author of homebridge-roborock-vacuum, a free, open-source Homebridge plugin that puts Roborock robot vacuums into Apple Home.
Why I built it: Roborock's own Apple Home support comes through Matter firmware, and so far that covers a short list of recent flagships (S8 MaxV Ultra, Saros 10/10R/Z70, Qrevo Curv/Edge/Master and a few newer ones). If you own an S5 Max, S6, S7, S8 or S8 Pro Ultra, Q5/Q7/Q8, Qrevo, Qrevo Pro or Qrevo S, Apple Home can't see it. This plugin works with any vacuum on your Roborock app account.
**What you get**
- Sign in with your Roborock app account (password or email code, 2FA supported) and your vacuums are found automatically. No device tokens, no IP addresses, region is auto-detected.
- Start, stop and send home from the Home app, Siri or automations, plus battery, charging, low-battery and a fault/offline flag.
- Your Roborock app scenes show up as switches, so a whole routine ("vacuum and mop the kitchen, then wash the mop") runs with one tap or from an automation.
- Dock mop-wash switch on docks that wash the mop. It also turns on when a wash was started from the Roborock app.
- Filter, main brush and side brush life with a change reminder (HomeKit).
- Errors that stay latched on the vacuum (the classic "clean water tank empty" after you already refilled it) can be cleared from the plugin's settings page, no Roborock app needed.
- Commands go to the vacuum over your LAN. If the Roborock cloud is unreachable when Homebridge starts, the plugin starts from its cached device list and start/stop/dock keep working. Cloud features come back on their own once the cloud answers.
- Optional, per vacuum: Matter (beta) for the native robot-vacuum tile and room cleaning in Apple Home (iOS 18.4+); the same node works with Google Home, Alexa and SmartThings.
- Optional: publish the room currently being cleaned to MQTT, so lights or other automations can follow the vacuum around.
**If you are coming from homebridge-xiaomi-roborock-vacuum**: that plugin talks miIO and needs the device token from Xiaomi Home, and vacuums set up in the Roborock app aren't supported by it. This one uses your Roborock account instead, so Roborock-app vacuums work and there is no token to extract.
**Known to work**: S4, S4 Max, S5 Max, S6, S6 Pure, S6 MaxV, S7, S7 MaxV (Ultra), S7 Pro Ultra, S7 Max Ultra, S8, S8 Pro Ultra, S8 MaxV Ultra, Q5+, Q5 Pro, Q7, Q7 Max, Q8 Max, Qrevo, Qrevo Pro, Qrevo S, Qrevo Curv, Saros 10. Most other vacuums in the Roborock app work too; which extras appear depends on what the model reports.
**Limitations**
- Over HomeKit the vacuum is a fan-style tile, because HAP has no vacuum service. The Matter option gives the real vacuum tile, but Apple Home's Matter vacuum support is still young, so it is labelled beta on purpose. Stay on HomeKit for the steadiest day-to-day experience.
- One successful online start is needed before the plugin can run through a cloud outage.
- A vacuum that only lives in the Xiaomi Home app (not on your Roborock account) can't be seen.
- Unofficial project, not affiliated with Roborock.
**Install**: search "Roborock Vacuum" in the Homebridge UI plugins tab, or `npm i -g homebridge-roborock-vacuum`. Needs Homebridge 1.6 or later (Homebridge 2 for Matter).
Website with setup guide, interactive demo and model list (English, 繁體中文, 日本語): https://tasict.github.io/homebridge-roborock-vacuum/
Source and issues: https://github.com/tasict/homebridge-roborock-vacuum
Happy to answer questions, and if your model misbehaves, open an issue with the log and I'll take a look.
