Matterbridge Xiaomi Roborock Plugin

---

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

$3

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.

$3

- [ ] 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.

$3

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.

$3

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!