jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-22 00:36:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update roborock documentation

Browse Source
This commit is contained in:
Allen Porter 2025-03-12 04:02:18 +00:00
parent 95bfb518f6
commit 459bcefc05
1 changed files with 220 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

298
source/_integrations/roborock.markdown
View File

@ -32,127 +32,246 @@ ha_platforms:
ha_integration_type: integration
---
The Roborock integration allows you to control your [Roborock](https://us.roborock.com/pages/robot-vacuum-cleaner) vacuum while using the Roborock app.
This integration requires a continuous cloud connection while using the device. However, excluding map data, communication between the integration and the device is conducted locally.
The Roborock {% term integration %} allows you to connect your [Roborock](https://us.roborock.com/pages/robot-vacuum-cleaner) robotic vacuums to your Home Assistant. Roborock vacuums are
intelligent home cleaning robots and depending on the specific device may have features
like mopping capabilities, laser navigation, and options for changing cleaning
performance or location in the home. This integration enables you to control and
monitor your Roborock vacuum directly from Home Assistant.
Once you log in with your Roborock account, the integration will automatically discover your Roborock devices and get the needed information to communicate locally with them. Please ensure your Home Assistant instance can communicate with the local IP of your device. We recommend setting a static IP for your Roborock Vacuum to help prevent future issues. The device communicates on port 58867. Depending on your firewall, you may need to allow communication from Home Assistant to your vacuum on that port.
The integration also allows for automation and integration with other smart home
devices. For example, you could send a notification when the vacuum is stuck, or
pause the vacuum when a media player starts playing music.
## Prerequisites
1. Download the Roborock App for iOS or Android.
1. Create an account and login
1. Add your Roborock device to the Roborock App (for example, by scanning a QR code)
{% include integrations/config_flow.md %}
{% configuration_basic %}
Email address:
description: "The email address used to sign in to the Roborock app. A verification code will be sent to this email address when adding the Roborock integration."
Verification code:
description: "The verification code that is sent to your email address when adding the Roborock integration."
{% endconfiguration_basic %}
## Robovac entities
{% include integrations/option_flow.md %}
The integration can be configured to specify which Roborock App features are drawn
on the map.
{% configuration_basic %}
Charger:
description: Show the charger on the map.
Cleaned area:
description: Show the area cleaned on the map.
Go-to path:
description: Show the go-to path on the map.
Ignored obstacles:
description: Show ignored obstacles on the map.
Ignored obstacles with photo:
description: Show ignored obstacles with photos on the map.
Mop path:
description: Show the mop path on the map.
No carpet zones:
description: Show the no carpet zones on the map.
No-go zones:
description: Show the no-go zones on the map
No mopping zones:
description: Show the no-mop zones on the map.
Obstacles:
description: Show obstacles on the map.
Obstacles with photo:
description: Show obstacles with photos on the map.
Path:
description: Show the path on the map.
Predicted path:
description: Show the predicted path on the map.
Vacuum position:
description: Show the vacuum position on the map.
Virtual walls:
description: Show virtual walls on the map.
Zones:
description: Show zones on the map.
{% endconfiguration_basic %}
## Data Updates
This integration uses both local and cloud {% term polling %}, and also receives
cloud push events using MQTT. Local communication is preferred when possible.
Map data is always fetched through the cloud, and Dyad and Zeo devices are cloud only.
The integration will automatically discover your Roborock devices using the cloud APIs and get
the needed information to communicate locally with them, if supported. Please ensure your Home Assistant
instance can communicate with the local IP of your device. We recommend setting a static IP
for your Roborock Vacuum to help prevent future issues. The device communicates on port 58867.
Depending on your firewall, you may need to allow communication from Home Assistant to your vacuum on that port.
## Supported functionality
Roborock devices have a variety of features that are supported on some devices but not on others. Only entities that your device supports will be added to your integration.
### Vacuum
### Robovac devices
#### Vacuum
The vacuum entity holds the ability to control most things the vacuum can do, such as start a clean, return to the dock, or set the fan speed.
### Select
#### Image
Mop mode - Describes how to mop the floor. On some firmware, it is called 'mop route'.
- **Map**
- **Description**: Displays a live map of your Roborock vacuum's cleaning area.
Mop intensity - How hard you would like your vacuum to mop.
#### Select
### Binary sensor
- **Mop mode**
- **Description**: Describes how to mop the floor. On some firmware, it is called 'mop route'.
Cleaning - States if the vacuum has a clean currently active. This is on when the robot is actively moving around or when the robot returns to the dock when the battery is low but a clean is still active and will resume later.
- **Mop intensity**
- **Description**: How hard you would like your vacuum to mop.
Mop attached - States if the mop is currently attached.
- **Selected map**
- **Description**: Choose the map that is loaded on the vacuum.
Mop drying status - Only available on docks with drying capabilites - States if the mop is currently being driven.
- **Empty mode**
- **Description**: You can set the "empty mode" setting including Max, Light, Balanced, and Smart.
- **Availability**: For vacuum equipped with an auto-empty dock
Water box attached - States if the water box is currently attached.
#### Binary sensor
Water shortage - States if the water box is low on water - 'Ok' if it has not detected a water shortage.
- **Charging**
- **Description**: States if the vacuum is currently charging or not.
- **Cleaning**
- **Description**: States if the vacuum is currently cleaning or not. This is on when the robot is actively moving around or when the robot returns to the dock when the battery is low but a clean is still active and will resume later.
- **Mop attached**
- **Description**: States if the mop is currently attached.
- **Mop drying status**
- **Description**: Only available on docks with drying capabilites - States if the mop is currently being driven.
- **Water box attached**
- **Description**: States if the water box is currently attached.
- **Water shortage**
- **Description**: States if the water box is low on water - 'Ok' if it has not detected a water shortage.
### Sensor
#### Sensor
Cleaning area - How much area the vacuum has cleaned in its current run. If the vacuum is not currently cleaning, how much area it has cleaned during its last run.
- **Cleaning area**
- **Description**: How much area the vacuum has cleaned in its current run. If the vacuum is not currently cleaning, how much area it has cleaned during its last run.
Cleaning time - How long the vacuum has been cleaning for. If the vacuum is not currently cleaning, how long it cleaned for in its last run.
- **Cleaning time**
- **Description**: How long the vacuum has been cleaning for. If the vacuum is not currently cleaning, how long it cleaned for in its last run.
Cleaning progress - Only available on some newer devices - what percent of the current cleaning is completed.
- **Cleaning progress**
- **Description**: Only available on some newer devices - what percent of the current cleaning is completed.
Dock error - Only available on the non-basic docks - The current error of the vacuum or 'Ok' if none exist
- **Dock error**
- **Description**: Only available on the non-basic docks - The current error of the vacuum or 'Ok' if none exist
Main brush time left - How much time is left before Roborock recommends you replace your main brush.
- **Main brush time left**
- **Description**: How much time is left before Roborock recommends you replace your main brush.
Mop drying remaining time - Only available on the non-basic docks - How much time is left until the mop is dry and ready to continue cleaning.
- **Mop drying remaining time**
- **Description**: Only available on the non-basic docks - How much time is left until the mop is dry and ready to continue cleaning.
Side brush time left - How much time is left before Roborock recommends you replace your side brush.
- **Side brush time left**
- **Description**: How much time is left before Roborock recommends you replace your side brush.
Filter time left - How much time is left before Roborock recommends you replace your vacuum's air filter.
- **Filter time left**
- **Description**: How much time is left before Roborock recommends you replace your vacuum's air filter.
Status - The current status of your vacuum. This typically describes the action that is currently being run. For example, 'spot_cleaning' or 'docking'.
- **Status**
- **Description**: The current status of your vacuum. This typically describes the action that is currently being run. For example, 'spot_cleaning' or 'docking'.
Last clean begin - the last time that your vacuum started cleaning.
- **Last clean begin**
- **Description**: the last time that your vacuum started cleaning.
Last clean end - The last time that your vacuum finished cleaning.
- **Last clean end**
- **Description**: The last time that your vacuum finished cleaning.
Total cleaning time - The lifetime cleaning duration of your vacuum.
- **Total cleaning time**
- **Description**: The lifetime cleaning duration of your vacuum.
Total cleaning area - The lifetime cleaning area of your vacuum.
- **Total cleaning area**
- **Description**: The lifetime cleaning area of your vacuum.
Total cleaning count - The lifetime cleaning count of your vacuum.
- **Total cleaning count**
- **Description**: The lifetime cleaning count of your vacuum.
Vacuum error - The current error with your vacuum, if there is one.
- **Vacuum error**
- **Description**: The current error with your vacuum, if there is one.
### Time
#### Time
Do not disturb begin - When _Do not disturb_ is enabled, the vacuum does not run or speak after this point.
- **Do not disturb begin**
- **Description**: When _Do not disturb_ is enabled, the vacuum does not run or speak after this point.
Do not disturb end - When _Do not disturb_ is enabled, the vacuum does not run or speak before this point.
- **Do not disturb end**
- **Description**: When _Do not disturb_ is enabled, the vacuum does not run or speak before this point.
### Switch
#### Switch
Child lock - This disables the buttons on the vacuum. Nothing happens when the buttons are pushed.
- **Child lock**
- **Description**: This disables the buttons on the vacuum. Nothing happens when the buttons are pushed.
Status indicator light - This is the LED on the top of your vacuum. The color changes depending on the status of your vacuum.
- **Status indicator light**
- **Description**: This is the LED on the top of your vacuum. The color changes depending on the status of your vacuum.
Do not disturb - This enables _Do not disturb_ during the time frame you have set in the app or on the time entity. When _Do not disturb_ is enabled, the vacuum does not run or speak.
- **Do not disturb**
- **Description**: This enables _Do not disturb_ during the time frame you have set in the app or on the time entity. When _Do not disturb_ is enabled, the vacuum does not run or speak.
### Number
#### Number
Volume - This allows you to control the volume of the robot's voice. For example, when it states "Starting cleaning". This allows you to set the volume to 0%, while the app limits it to 20%.
- **Volume**
- **Description**: This allows you to control the volume of the robot's voice. For example, when it states "Starting cleaning". This allows you to set the volume to 0%, while the app limits it to 20%.
### Button
#### Button
There are currently four buttons that allow you to reset the various maintenance items on your vacuum. Pressing the button cannot be undone. For this reason, the buttons are disabled by default to make sure they are not pressed unintentionally.
Reset sensor consumable - The sensors on your vacuum are expected to be cleaned after 30 hours of use.
- **Reset sensor consumable**
- **Description**: The sensors on your vacuum are expected to be cleaned after 30 hours of use.
Reset side brush consumable - The side brush is expected to be replaced every 200 hours.
- **Reset side brush consumable**
- **Description**: The side brush is expected to be replaced every 200 hours.
Reset main brush consumable - The main brush/ roller is expected to be replaced every 300 hours.
- **Reset main brush consumable**
- **Description**: The main brush/ roller is expected to be replaced every 300 hours.
Reset air filter - The air filter is expected to be replaced every 150 hours.
- **Reset air filter**
- **Description**: The air filter is expected to be replaced every 150 hours.
### Actions
#### Actions
#### Action `roborock.set_vacuum_goto_position`
##### Action Set Vacuum Goto Position
Go the specified coordinates.
The `roborock.set_vacuum_goto_position` action will set the vacuum to go to
the specified coordinates.
- **Data attribute**: `entity_id`
- **Description**: Only act on a specific robot.
- **Optional**: No.
- **Data attribute**: `x_coord`
- **Description**: X-coordinate, integer value. The dock is located at x-coordinate 25500.
- **Optional**: No.
- **Data attribute**: `y_coord`
- **Description**: Y-coordinate, integer value. The dock is located at y-coordinate 25500.
- **Optional**: No.
#### Action `roborock.get_vacuum_current_position`
| Data attribute | Optional | Description |
|------------------|----------|------------------------------------------------------|
| `entity_id` | No | Only act on a specific robot. |
| `x_coord` | No | X-coordinate, integer value. The dock is located at x-coordinate 25500. |
| `y_coord` | No | Y-coordinate, integer value. The dock is located at y-coordinate 25500. |
Get the current position of the vacuum. This is a cloud call and should only be used for diagnostics. This is not meant to be used for automations. Frequent requests can lead to rate limiting.
##### Action Get Vacuum Current Position
- **Data attribute**: `entity_id`
- **Description**: Only act on a specific robot.
- **Optional**: No.
The `roborock.get_vacuum_current_position` action will get the current position of the vacuum. This
is a cloud call and should only be used for diagnostics. This is not meant to be used for
automations. Frequent requests can lead to rate limiting.
| Data attribute | Optional | Description |
|------------------|----------|------------------------------------------------------|
| `entity_id` | No | Only act on a specific robot. |
Example:
@ -171,43 +290,66 @@ data: {}
y: 25168
```
### Image
##### Action Get Maps
You can see all the maps within your Roborock account. Keep in mind that they are device-specific. The maps require the cloud API to communicate as the maps are seemingly stored on the cloud. If someone can figure out a way around this - contributions are always welcome.
The `roborock.get_maps` action will return the maps available on the device and
details about any named rooms.
| Data attribute | Optional | Description |
|------------------|----------|------------------------------------------------------|
| `entity_id` | No | Get maps for a specific device. |
## Dyad entities
This will return the name of the map, and the room names and id numbers. See [How can I clean a specific room? ](#how-can-i-clean-a-specific-room) for more details on how to use the maps response.
### Dyad devices
Roborock wet/dry vacuums currently expose some entities through an MQTT connection - it is currently cloud dependent.
### Sensor
#### Sensor
Status - The current status of your vacuum. This typically describes the action that is currently being run. For example, 'drying' or 'charging'.
- **Status**
- **Description**: The current status of your vacuum. This typically describes the action that is currently being run. For example, 'drying' or 'charging'.
Battery - The current charge of your device.
- **Battery**
- **Description**: The current charge of your device.
Filter time left - how long until Roborock recommends cleaning/replacing your filter.
- **Filter time left**
- **Description**: how long until Roborock recommends cleaning/replacing your filter.
Brush time left - how long until Roborock recommends cleaning/replacing your brush.
- **Brush time left**
- **Description**: how long until Roborock recommends cleaning/replacing your brush.
Error - the current error of the device - if one exists - "None" otherwise.
- **Error**
- **Description**: the current error of the device - if one exists - "None" otherwise.
Total cleaning time - how long you have cleaned with your wet/dry vacuum.
- **Total cleaning time**
- **Description**: how long you have cleaned with your wet/dry vacuum.
## Zeo Entities
### Zeo Entities
Roborock Zeo One currently exposes some entities through an MQTT connection - it is currently cloud dependent.
### Sensor
#### Sensor
State - The current state of your washing machine. For example, 'washing' or 'rinsing'.
- **State**
- **Description**: The current state of your washing machine. For example, 'washing' or 'rinsing'.
Countdown - Countdown for how long until the machine starts.
- **Countdown**
- **Description**: Countdown for how long until the machine starts.
Washing left - The amount of time until your machine is done washing.
- **Washing left**
- **Description**: The amount of time until your machine is done washing.
- **Error**
- **Description**: The current error of the Zeo, if one exists.
## Removing the integration
This integration follows standard integration removal. No extra steps are required.
{% include integrations/remove_device_service.md %}
Error - The current error of the Zeo, if one exists.
## FAQ
@ -215,7 +357,7 @@ Error - The current error of the Zeo, if one exists.
No. This integration requires information from your Roborock app to set up and uses Roborock's protocols to communicate with your device. You must have your vacuum synced to the Roborock app.
### Can I block internet access for this device?
As of right now - no. When the vacuum is disconnected from the internet, it will attempt to disconnect itself from Wi-Fi and reconnect itself until it can reach the Roborock servers. We are looking for the best way to handle this and see what can be blocked while still allowing the vacuum to function.
As of right now - no. When the vacuum is disconnected from the internet, it will attempt to disconnect itself from Wi-Fi and reconnect itself until it can reach the Roborock servers.
### What devices are supported?
If you can add your device to the Roborock app - it is supported. However, some older vacuums like the Roborock S5 must be connected using the Mi Home app and can be set up in Home Assistant through the [Xiaomi Miio](/integrations/xiaomi_miio/) integration.