Matterbridge Xiaomi Roborock Plugin is a dynamic platform plugin for Matterbridge that integrates with Roborock vacuum cleaners controlled via the Xiaomi Home app, enabling control via Apple Home and other Matter-compatible apps. If you use the Roborock app, refer to the Matterbridge Roborock Platform Plugin instead.

⭐️ If you like this project and find it useful, please consider giving it a star on GitHub at Matterbridge Xiaomi Roborock Plugin.

⚠️ Disclaimer

This project is in a very early stage of development. I'm initially building it to integrate with my Roborock S5, and will be extending the support once the basic features are implemented.

Other models might work at this stage, but I cannot guarantee that (mostly because I haven't been able to test them). Any help testing other models is welcome. If you find a model that works, please open an issue or a PR to add it to the list of supported models.

• Features
  • Room cleaning and discovery
  • TODO
• Supported models
• Known issues
• Installation
  • Prerequisites
  • Add the plugin to Matterbridge and your devices to Apple Home (or any other Matter-compatible app)

Features

• Basic RVC operations (start/stop/pause/resume/go back to dock)
• Fan speed control
• Water level control (only in supported models)
• Room cleaning and discovery (only in supported models)
• Battery information

Room cleaning and discovery

The plugin uses 2 methods to discover the rooms defined in the Xiaomi Home app, depending on the features supported by the model (and shown in the Xiaomi Home app):

1. For supported models where the app allows to add names in the rooms, it is capable of retrieving the names from the app.
   • In some cases, the names configured in the app are not returned by this API (instead, it shows a long numeric value). In this case, you can use the roomNames configuration option to manually define the names.
2. For other models, it needs a workaround:
   1. In the Xiaomi Home app, while in the vacuum view, open the options by clicking on the 3 dots in the top right corner.
   2. Then, in "Timer", define a cleaning timer for midnight (00:00) that repeats every day. Make sure to select all the rooms individually.
   3. Make sure to disable the timer (nobody wants to kick off a cleaning at midnight every day 🙈).
   4. Finally, set up the roomNames in this plugin's configuration. Make sure to follow the same order as you selected the rooms in the app.

‼️ If you need to rely on the 2nd approach, chances are that the vacuum does not support the command to run room cleaning (app_segment_clean). If you find the command that works for these models (testing via node-miio or python-miio), please open an issue or a PR to add this support.

TODO

• [ ] Improve state control
• [ ] Additional controls like initiate dust collection are missing
• [ ] Add information about the Maintenance counters (sensors, filter, brush)
• [ ] Add better error handling (expose the errors to the user if possible)

Supported models

| Model | Code name | Basic info (battery, serial, firmware) | Full cleaning | Room cleaning | Tested by | | ----------- | -------------------- | :------------------------------------: | :-----------: | :-----------: | :-------: | | Roborock S5 | roborock.vacuum.s5 | ✅ | ✅ | ✅ | @afharo |

Known issues

| Issue | Comment | Workaround | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------- | | The name of the device is not automatically placed in Apple Home. | AFAIK, this happens to all Matterbridge devices (all show as Matterbridge Accessory). | The device must be renamed in the Home App. |

Installation

This plugin leverages the Matterbridge ecosystem, so you can install it in the same way as any other Matterbridge plugin.

ℹ️ This is not a Homebridge plugin. You need to install Matterbridge instead.

Prerequisites

You need to have Matterbridge installed. Refer to their installation guide for more details.

Additionally, you need the IP and token of the RVC. I recommend using the Xiaomi Cloud Tokens Extractor, as I find it the easiest way to get the token.

⚠️ If the RVC's Wi-Fi connection is reconfigured, a new token is generated, and you will need to retrieve it again, and update this plugin's configuration.

The same happens if the RVC is paired/controlled via the Roborock app.

If you already use homebridge-xiaomi-roborock-vacuum, the same IP and token can be used.

Add the plugin to Matterbridge and your devices to Apple Home (or any other Matter-compatible app)

Once on the Matterbridge UI, install this plugin using the name matterbridge-xiaomi-roborock, and configure it. After restarting Matterbridge, a new device should appear in the list of Devices in the Matterbridge UI, scan the QR code with the Apple Home app (or any other Matter-compatible app), and you should be good to go!