This is a custom component for Home Assistant to integrate the Viomi SE Vacuum Cleaner (viomi.vacuum.v19) - apparently EU version - with 4.0.9_0012 firmware and tested in 4.0.9_0017.
Building upon the major refactor initiated in v2025.10.19, the current version (v2026.4.4) has been fully updated and verified on Home Assistant 2026.2.3.
While optimized for the latest core, it remains compatible with Home Assistant 2024.12.0+ thanks to the use of modern practices like UI-based configuration (Config Flow), DataUpdateCoordinator, dedicated sensors for consumables, and configurable options.
- Table of Contents
- 🎉 What's New in v2? (The Modernization Update)
- ⬆️ Upgrading from v1
- ✨ Features
- 📋 Prerequisites
- 🚀 Installation
- ⚙️ Configuration
- 🔧 Options
- 📦 Entities & Attributes
- 🛠️ Custom Services
- 🖼️ Lovelace Integration
- ❓ Troubleshooting
- Acknowledgements
- 🤝 Contributions
- 📄 License
The current version (v2026.4.4), building on the massive refactor initiated in v2025.10.19, completely modernizes this integration.
If you are a new user, you can skip to the Installation section. If you are upgrading from version v1 (v2025.02.09beta or earlier), please read the Upgrading instructions below carefully.
- UI-Based Configuration: No more YAML! The integration is now set up entirely through the Home Assistant interface.
- Dedicated Sensors for Consumables: Individual sensors for the remaining life of the main brush, side brush, filter, and mop.
- Configurable Options: You can now click "Configure" on the integration to adjust:
- Command Cooldown: Time to wait between commands to prevent flooding the device.
- Update Interval: How often to fetch status updates.
- Improved Stability & Performance: The integration now uses
DataUpdateCoordinatorfor efficient data fetching and includes a command debounce mechanism to prevent errors. - Full Translation Support (EN/PT) and a
services.yamlfile for a better user experience in the Developer Tools.
If you were using the old version of this integration with a configuration.yaml setup, please follow these steps to upgrade:
- Important: Make a backup of your Home Assistant configuration.
- Remove the old
vacuum:entry forviomisefrom yourconfiguration.yamlfile. - Update the integration to the latest version via HACS (or by manually copying the new files).
- Restart Home Assistant.
- After restarting, go to Settings > Devices & Services and add the Viomi SE integration through the UI. You will be prompted for the IP Address and Token again.
Your old entity names should be preserved if you use the same name during the new configuration.
- UI Configuration: Set up and configure the vacuum entirely through the Home Assistant user interface.
- Standard Vacuum Controls:
start,pause,stop,return_to_base,locate. - Fan Speed Control: Adjust fan speeds (
Silent,Standard,Medium,Turbo). - Consumable & Battery Sensors: Dedicated sensors for the life percentage of all consumables and the battery.
- Configurable Timings: Adjust command cooldown and update intervals via the integration's options.
- Custom Services: Advanced cleaning commands for zones, segments (rooms), and specific points.
- Multi-language Support: UI is translated into English and Portuguese.
You need to obtain the IP Address and the 32-character Token of your Viomi SE vacuum.
The easiest way to get the token is by using the Xiaomi Miot Auto integration, which can automatically discover tokens for devices on your network. Alternatively, you can use the python-miio tool.
This integration is part of the default HACS repository!
- Go to your HACS page in Home Assistant.
- Click on "Integrations".
- Click the "Explore & Download Repositories" button in the bottom right corner.
- Search for "Viomi SE Vacuum".
- Click on the integration and then click "Download".
- Restart Home Assistant when prompted.
-
Download the latest release from the Releases page.
-
Unzip the downloaded file.
-
Copy the entire
viomisefolder into your Home Assistant'scustom_componentsdirectory.Important: Ensure the folder contains all these critical files for v2 to work:
__init__.py&const.py(Core logic and constants)coordinator.py(Data handling - Essential for v2)config_flow.py(UI Configuration setup)vacuum.py&sensor.py(Entity platforms)manifest.json&services.yamltranslations/folder (Required for UI text and translations)
-
The final path should look like:
<config_directory>/custom_components/viomise/ -
Restart Home Assistant.
Once the integration is installed and Home Assistant is restarted, you can add your vacuum via the UI.
- Go to Settings > Devices & Services.
- Click the + ADD INTEGRATION button in the bottom right corner.
- Search for "Viomi SE" and click on it.
- A configuration dialog will appear. Enter the following:
- Device Name: A friendly name for your vacuum (e.g., "Viomi SE").
- IP Address: The local IP address of your vacuum.
- Token: The 32-character token you obtained earlier.
- Click "Submit".
If the details are correct, the integration will be added, and a new device with its entities will appear.
After adding the integration, you can fine-tune its behavior.
- Go to Settings > Devices & Services.
- Find the Viomi SE integration and click on "Configure".
- You can adjust the following options:
- Command Cooldown (seconds): The minimum time to wait between sending commands to the vacuum. This prevents flooding the device with requests. (Default:
2.5) - Update Interval (seconds): How often to fetch status updates from the vacuum. (Default:
30)
- Command Cooldown (seconds): The minimum time to wait between sending commands to the vacuum. This prevents flooding the device with requests. (Default:
All properties fetched from the vacuum are available as State Attributes. This allows for advanced dashboard cards and automations without extra entities.
(Note: If you named your device "Living Room", the entity will be vacuum.living_room).
| Category | Attribute | Description |
|---|---|---|
| Mapping | current_map_id |
Unique ID of the active floor/map. |
remember_map |
Status of map saving (0: Off / 1: On). | |
has_map |
Indicates if a map is currently loaded. | |
has_newmap |
Indicates if a new map has been discovered. | |
| Cleaning Stats | s_area |
Area cleaned in the last/current session (m²). |
s_time |
Duration of the last/current cleaning (min). | |
| Modes & Config | run_state |
Numerical state of the vacuum (e.g., 4: Cleaning, 2: Charging). |
mode |
Operation mode (0: Vacuum, 1: Mixed, 2: Mop). | |
mop_route |
Mopping pattern (0: S-shape, 1: Y-shape). | |
suction_grade |
Suction power level (0-3). | |
water_grade |
Water flow level (11: Low, 12: Medium, 13: High). | |
repeat_state |
If the cleaning is set to repeat (0/1). | |
| Hardware | battary_life |
Real-time battery percentage (0-100). |
box_type |
Container detected (1: Dust, 2: Water, 3: 2-in-1). | |
mop_type |
Mop bracket status (0: Not installed, 1: Installed). | |
err_state |
Current error code (0 if no error). | |
| Maintenance | main_brush_left |
Hours remaining for the main brush. |
side_brush_left |
Hours remaining for the side brush. | |
filter_left |
Hours remaining for the filter. | |
mop_left |
Hours remaining for the mop. | |
*_percentage |
Percentage remaining for each consumable above. |
For easier history tracking and native Home Assistant features:
sensor.viomi_se_battery(Battery percentage)sensor.viomi_se_main_brush_life(%)sensor.viomi_se_side_brush_life(%)sensor.viomi_se_filter_life(%)sensor.viomi_se_mop_life(%)
Note: The exact entity ID may vary slightly based on the name you provide during setup. Naming the vacuum 'Robot' will result in the entity ID sensor.robot_battery
In addition to the standard vacuum services, this integration provides advanced services. You can find them in Developer Tools > Services.
| Service | Parameter | Example |
|---|---|---|
viomise.vacuum_clean_zone |
zone (coords), repeats |
Clean a specific area. |
viomise.vacuum_clean_segment |
segments (list) |
Clean specific rooms. |
viomise.vacuum_goto |
x_coord, y_coord |
Send robot to a spot. |
viomise.vacuum_set_map |
map_id, map_name or map_index |
Switch between floors. |
Example Service Call (in YAML):
service: viomise.vacuum_clean_segment
target:
entity_id: vacuum.viomi_se
data:
segments: [10, 11]Starting with version v2026.4.20, this integration supports both the new modern service names and legacy names to ensure your existing dashboards don't break.
| Service Name (New) | Legacy Alias (Backward Compatibility) | Description |
|---|---|---|
viomise.vacuum_clean_zone |
vacuum.xiaomi_clean_zone |
Required for xiaomi-vacuum-map-card default config. |
viomise.vacuum_clean_point |
vacuum.xiaomi_clean_point |
Required for "Go to point" default config. |
Note: While legacy aliases are supported to keep community Lovelace cards working out-of-the-box, we recommend migrating your custom scripts and automations to the viomise.* domain for better long-term support and visibility in Home Assistant Developer Tools.
For the best experience, we recommend using the Xiaomi Vacuum Map Card. This integration is compatible with its features.
Click to expand: Full Map Card YAML Example
type: grid
square: false
columns: 1
cards:
- type: heading
heading: Viomi SE
icon: mdi:robot-vacuum
heading_style: title
- type: custom:xiaomi-vacuum-map-card
entity: vacuum.viomi_se
vacuum_platform: marotoweb/viomise
map_source:
camera: image.viomi_se_live_map
calibration_source:
camera: true
# Dashboard Tiles: Displaying real-time stats and consumable status
tiles:
- tile_id: status
entity: vacuum.viomi_se # Uses the main entity state (Cleaning, Docked, etc.)
label: Status
- tile_id: battery
entity: sensor.viomi_se_battery
label: Battery
- tile_id: area
entity: vacuum.viomi_se
label: Area
attribute: s_area
unit: m²
icon: mdi:texture-box
- tile_id: time
entity: vacuum.viomi_se
label: Time
attribute: s_time
unit: min
icon: mdi:clock-time-five-outline
- tile_id: main_brush
entity: vacuum.viomi_se
label: Main Brush
attribute: main_brush_left
unit: h
icon: mdi:brush-variant
- tile_id: side_brush
entity: vacuum.viomi_se
label: Side Brush
attribute: side_brush_left
unit: h
icon: mdi:brush
- tile_id: filter
entity: vacuum.viomi_se
label: Filter
attribute: filter_left
unit: h
icon: mdi:air-filter
- tile_id: mop_life
entity: vacuum.viomi_se
label: Mop
attribute: mop_left
unit: h
icon: mdi:format-color-fill
append_icons: true
icons:
# --- MAP SELECTION ---
# Icons will highlight (glow) when the 'current_map_id' attribute matches the value
- icon_id: map_1
icon: mdi:layers-outline
label: First Floor
menu_id: map_selection
conditions:
- entity: vacuum.viomi_se
attribute: current_map_id
value: 1776530025
tap_action:
action: call-service
service: viomise.vacuum_set_map
service_data:
entity_id: vacuum.viomi_se
map_id: 1776530025
- icon_id: map_2
icon: mdi:layers-triple-outline
label: Ground Floor
menu_id: map_selection
conditions:
- entity: vacuum.viomi_se
attribute: current_map_id
value: 1776189566
tap_action:
action: call-service
service: viomise.vacuum_set_map
service_data:
entity_id: vacuum.viomi_se
map_id: 1776189566
# --- CLEANING MODES ---
- icon_id: mode_vacuum
icon: mdi:vacuum
label: Vacuum Only
menu_id: cleaning_mode
conditions:
- entity: vacuum.viomi_se
attribute: is_mop
value: "0"
tap_action:
action: call-service
service: vacuum.send_command
service_data:
entity_id: vacuum.viomi_se
command: set_mop
params: [0]
- icon_id: mode_mixed
icon: mdi:hydro-power
label: Vacuum & Mop
menu_id: cleaning_mode
conditions:
- entity: vacuum.viomi_se
attribute: is_mop
value: "1"
tap_action:
action: call-service
service: vacuum.send_command
service_data:
entity_id: vacuum.viomi_se
command: set_mop
params: [1]
- icon_id: mode_mop
icon: mdi:waves
label: Mop Only
menu_id: cleaning_mode
conditions:
- entity: vacuum.viomi_se
attribute: is_mop
value: "2"
tap_action:
action: call-service
service: vacuum.send_command
service_data:
entity_id: vacuum.viomi_se
command: set_mop
params: [2]
# --- WATER LEVELS ---
- icon_id: water_low
icon: mdi:water-minus-outline
label: Low
menu_id: water_level
conditions:
- entity: vacuum.viomi_se
attribute: water_grade
value: "0"
tap_action:
action: call-service
service: vacuum.send_command
service_data:
entity_id: vacuum.viomi_se
command: set_suction
params: [11]
- icon_id: water_medium
icon: mdi:water
label: Medium
menu_id: water_level
conditions:
- entity: vacuum.viomi_se
attribute: water_grade
value: "1"
tap_action:
action: call-service
service: vacuum.send_command
service_data:
entity_id: vacuum.viomi_se
command: set_suction
params: [12]
- icon_id: water_high
icon: mdi:water-plus
label: High
menu_id: water_level
conditions:
- entity: vacuum.viomi_se
attribute: water_grade
value: "2"
tap_action:
action: call-service
service: vacuum.send_command
service_data:
entity_id: vacuum.viomi_se
command: set_suction
params: [13]
# --- MOPPING PATTERNS ---
- icon_id: pattern_y
icon: mdi:alpha-y-circle
label: Y-shape
menu_id: mop_pattern
conditions:
- entity: vacuum.viomi_se
attribute: mop_route
value: "1"
tap_action:
action: call-service
service: vacuum.send_command
service_data:
entity_id: vacuum.viomi_se
command: set_moproute
params: [1]
- icon_id: pattern_s
icon: mdi:alpha-s-circle
label: S-shape
menu_id: mop_pattern
conditions:
- entity: vacuum.viomi_se
attribute: mop_route
value: "0"
tap_action:
action: call-service
service: vacuum.send_command
service_data:
entity_id: vacuum.viomi_se
command: set_moproute
params: [0]
- "Failed to connect" error: Double-check that the IP address is correct and that the vacuum is on the same network. The token might be incorrect or may have changed if you reset the vacuum's Wi-Fi.
- Device is "Unavailable": This usually means Home Assistant cannot reach the vacuum at its IP address. Check your network and ensure the vacuum is online in the Mi Home app.
- Logs: To get more information, you can enable debug logging for the integration by adding the following to your
configuration.yaml:logger: default: info logs: custom_components.viomise: debug miio: debug
This integration was originally forked from the home-assistant-vacuum-styj02ym project, which provided the initial structural foundation.
However, all the protocol research, including the discovery of how to use the specific siid and piid properties required to control the Viomi SE (v19) model, was done independently for this project. This reverse-engineering effort is the core of what makes this integration work for this specific vacuum model.
Contributions are welcome! If you find a bug or have a suggestion for a new feature, please open an issue or submit a pull request.
This project is licensed under the MIT License. See the LICENSE file for details.