01 — Overview

What is this?

eufy_vacuum is a Home Assistant custom integration paired with a Lovelace card called eufy-vacuum-command-center. Together they give you room-level control over your robot vacuum directly from your HA dashboard. It's a multi-brand integration — it supports Eufy, Roborock and Dreame vacuums today through an adapter system, and is built to extend to other brands.

The integration has been tested on the Eufy X10 Pro Omni, the Roborock S6 and the Dreame L10s Ultra Gen2. Other models of any of the three may work but aren't officially supported. Dreame works through the community dreame-vacuum integration, which you set up first — see Setup. Because capabilities differ by brand and model, some tabs and controls described in this guide appear, are hidden, or read differently depending on your vacuum — those differences are called out inline as you go.

Will my Eufy vacuum work?

Everything below — room-level control, the live map, room rollover, and the learning system — depends on the robot building a room map with per-room segments, which Eufy delivers only over its MQTT transport. If your robot doesn't map rooms, eufy_vacuum has nothing to add.

Not supported — basic navigation robots (no map, no rooms). These bump-and-go and gyroscopic-navigation models never build a room map, so per-room cleaning, the map view, and the learning system don't apply. They work fine in eufy-clean on their own for start/stop, suction, and status — use it directly:

• RoboVac C-series — 11C, 11S, 15C / 15C MAX, 25C, 30C / 30C MAX, 35C
• RoboVac G-series — G10 Hybrid, G20 / G20 Hybrid, G30 (incl. Verge / Hybrid / +SES), G32, G35 / G35+, G40 (incl. Hybrid / Hybrid+), G50

Transport-dependent — may not work. The mapping robots — the X-series (X8, X9 Pro, X10 Pro Omni), S1 / S1 Pro, L-series (L60, L70), LR-series (LR20 / LR30 / LR35), Omni C20, and AE C10 — build a map and should drive eufy_vacuum, but only when eufy-clean talks to them over MQTT. eufy-clean v1.12 added a legacy Tuya transport (cloud / local) for older robots; on that path the live map and the room list are never sent, so the map and per-room features go dark even on a robot that can map. Only the X10 Pro Omni is verified — if you run another, please open an issue with what worked, and the list will be updated.

What does it add beyond the stock Eufy integration?

A stock vacuum integration in Home Assistant lets you start and stop your vacuum as a single unit. eufy_vacuum goes further:

• Room-level control. You choose exactly which rooms to clean before each run, and in what order.
• Per-room cleaning settings. Each room can have its own cleaning mode (vacuum, mop, or both), suction level, water level, cleaning path, number of passes, and edge mopping toggle.
• Cleaning profiles. You can save a named set of room settings as a reusable profile and apply it to any room in one tap. Built-in profiles are read-only; you can create as many custom profiles as you like.
• Run profiles. You can save an entire room selection — which rooms are included, in what order, with what settings, and optionally an ordered sequence with mid-run charge or wait stops (vacuum, dock and top up, then mop — all one job) — as a named run profile and start it again with a single button.
• Queue management. The card shows you which rooms are queued, their estimated cleaning times, and your planned run order. You can reorder rooms by dragging or by using a move button.
• Zone cleaning. Draw a box on the map to clean just an area, save it as a named zone to re-clean by name, or drop a saved zone into a run as a sequenced, learnable step — so one job cleans rooms and a zone in order. See Zones.
• Learning system. After each run the integration records which rooms were cleaned and how long the vacuum spent in each — recovered from the vacuum's own live room signal, so it works for runs you start from the dashboard and runs you start from the vacuum's app. Over time it builds per-room timing estimates that get more accurate the more you use it. The card displays a confidence indicator (Reliable / Learning / Uncertain) for each room's estimate.
• Incomplete run recovery. If a run ends before all rooms are finished, the card shows a banner letting you queue only the missed rooms for a follow-up run.
• Trouble room indicators. The card tracks rooms the vacuum has repeatedly failed to clean and flags them so you can investigate.
• Stall capture. Optional, off until you arm it: when a run stalls, the integration draws the room the vacuum stopped in — outline, last stretch of travel, and a dot where it came to rest — notifies you, and fires an event carrying the image so an automation can send it to your phone. See Stall capture.
• Metrics and learning review. Dedicated panels let you browse historical run data and review what the system has learned.
• Theming. The card's colors, typography, and layout tokens are fully customizable from within the card itself — including a built-in Colorblind Safe theme that keeps status colors distinguishable for color-vision deficiency (see Accessibility).

Requirements

• Home Assistant with your Eufy vacuum already set up as a vacuum entity.
• The eufy_vacuum custom component installed in custom_components/eufy_vacuum.
• The eufy-vacuum-command-center Lovelace card installed and added to a dashboard with your vacuum_entity_id set in the card config.

At minimum your card config needs:

type: custom:eufy-vacuum-command-center
vacuum_entity_id: vacuum.your_vacuum

The card at a glance

The card has a header strip at the top showing your vacuum's name, two status pills, and the current battery level:

• Vacuum Status — what the vacuum entity itself reports (Docked, Cleaning, Returning, Paused, etc.).
• Dock Status — what the dock entity reports (Idle, Washing, Drying, Emptying, Charging, etc.). Only shown when your model exposes a dock status.

Both labels are formatted server-side, so any vocabulary the integration knows about is rendered consistently. A colored dot next to each one mirrors the state at a glance — green for active work, amber for transitional states, red for errors, muted grey for idle/offline.

Below the header is a navigation bar with tabs that switch between panels:

Tab	What it does
Rooms	Select rooms, adjust their settings, and start a cleaning run. This is the main day-to-day panel.
Maintenance	Track consumable lifespans (brushes, filter, etc.) and trigger upkeep actions.
Base Station	Control base station functions — wash mop, dry mop, empty dust bin.
Metrics	Browse historical run data with filters by room, profile, and status.
Learning Review	Review what the learning system has recorded about each room's cleaning history.
Room Rules	Set up automation rules that apply to rooms (for example, automatically adjusting settings based on time of day or other conditions).
Theme	Customize the card's visual appearance — colors, token values, and saved theme presets.
Setup	Add vacuums and import maps into the integration.

Tabs adapt to your vacuum

The navigation only shows tabs your vacuum supports. Base Station appears on models with a dock and is hidden on models without one — for example the dockless Roborock S6 doesn't show it.

Uploading a map image and linking the vacuum's map segments to your rooms happen on a separate Map Config screen rather than a top-nav tab. You reach it from the Configure button in the Rooms map view. See Making your own maps for the step-by-step walkthrough, or Map configuration for the technical reference.

The card opens on the Rooms tab the first time you load it. After that it remembers whichever tab you were on last per vacuum, so refreshing the browser doesn't lose your place.

On a narrow screen

The card switches to a mobile layout when it is narrow or short: the card itself under 600px wide, or the browser window under 500px tall.

Width is the card's own measured width, so a card sitting in a narrow dashboard column gets the mobile layout on a desktop too. Height is the browser window's, not the card's — a dashboard card's height is set by its own content, so measuring that would feed the layout its own output, while the window is what actually limits vertical room. The height test is there for phone landscape: rotating a 390×844 phone gives you roughly 844×390, which clears the 600px width test at the exact moment there is least height to lay anything out in.

You can force it either way from the card config:

mobile_shell: auto   # auto (default) | true (always mobile) | false (always desktop)

What changes:

• The navigation moves to a bottom tab bar with shortened labels — Rooms, Upkeep (Maintenance), Dock (Base Station), and Stats (Metrics) — plus a More overflow sheet holding Learning Review, Room Rules, Theme, Map Config, and Setup. Dock only appears on vacuums that have a base station, so a dockless model shows three tabs and More.
• The header compacts to a name line and a status line. The status line carries the vacuum's status with its coloured dot, and the battery — written out as "Battery 100%" rather than a bare percentage, and reading amber at 20% or below and red at 10% or below, the same bands as the desktop header. The dock's status gets a line of its own underneath when your model reports one.
• The Rooms toolbar wraps instead of running off the edge, and its buttons grow to a full-size tap target; see Rooms Panel → The Rooms toolbar.
• Theme editing works at every width. You can pick, activate, and share whole themes from a phone, and the Palette and Tokens editors work there too. What narrows on a small screen is mostly the Theme tab's own chrome; the token rows themselves drop a couple of duplicate inputs, and nothing becomes uneditable. See Sharing themes → On a phone.
• In landscape the chrome gets out of the way. When the window is short — a phone turned sideways — the compact header and the bottom tab bar start out hidden on any view long enough to scroll, and a deliberate flick back up, or scrolling to the very top, brings them back. A small nudge doesn't: reaching a control in landscape means scrolling constantly, and if every one of those restored the chrome it would take the room away again mid-edit. While a run is in flight the header stays put — that's exactly when its numbers are worth the space — and only the tab bar hides.

In the sidebar panel the card takes the full height of the panel at any width, so the header stays pinned and the bottom tab bar stays where your thumb expects it.

Small conveniences

A few interaction details that aren't tied to any one tab:

• Toast feedback. Save / reset / dock-action / delete operations surface a short status pill near the bottom of the card. Successful actions get a green stripe, failures a red one, informational events a blue one. Each one auto-dismisses after a few seconds; click the ✕ to drop it sooner.
• ESC closes modals. Any open modal (room editor, room access editor, run-estimate detail, maintenance item, order picker) closes on Escape.
• Two-tap destructive actions. Cancel Run, Clear Queue, and Delete on a map image variant all require two clicks. The first click flips the button to a pulsing "Confirm" state; the second click commits. The confirmation auto-clears after a few seconds, and switching tabs also drops it so a pending confirm never surprises you when you come back.
• Incomplete run banner. If a run ends with rooms unvisited, an alert banner appears at the top of the Rooms tab the moment the integration finalizes the job. A "Queue missed rooms" button kicks off a follow-up run with just the skipped rooms.