# Xiaomi Vacuum Map Card for Home Assistant > Xiaomi Vacuum Map Card adds map-based controls and configurable actions to Home Assistant dashboards for several robot vacuum platforms. It is most suitable for users who need zone selection, room cleaning, saved destinations, or a map-oriented Lovelace card and who accept manual YAML configuration for advanced behavior. **PiotrMachowski/lovelace-xiaomi-vacuum-map-card** — This card provides a user-friendly way to fully control map-based vacuums in Home Assistant. Supported brands include Xiaomi (Roborock/Viomi/Dreame/Roidmi/Valetudo/Valetudo RE), Neato, Wyze, Roomba, Ecovacs (and probably more). - Repository: https://github.com/PiotrMachowski/lovelace-xiaomi-vacuum-map-card - Stars: 1,947 · Forks: 287 - Language: TypeScript - License: MIT - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/piotrmachowski-lovelace-xiaomi-vacuum-map-card ## The Home Assistant vacuum control gap addressed by Xiaomi Vacuum Map Card Xiaomi Vacuum Map Card is a Lovelace frontend card for controlling map-based robot vacuums from Home Assistant. Its target users are Home Assistant operators who already have a vacuum entity but want map-oriented commands in the dashboard rather than relying only on basic entity controls. The repository describes support for Xiaomi families including Roborock, Viomi, Dreame, Roidmi, Valetudo, and Valetudo RE. It also names Neato, Wyze, Roomba, and Ecovacs, while qualifying the overall list with "and probably more." That wording matters: the README presents broad platform coverage, but it does not provide a complete model-level compatibility matrix in the documented excerpt. The card addresses a specific interface problem. Home Assistant can represent a vacuum as an entity, while a floor plan lets the user select where the machine should work. According to the feature list, the card provides manual and saved zoned cleaning, manual and saved target selection, room cleaning, following a path, and custom services. It can also display icon controls and value tiles with conditional visibility, configurable content, and service calls. Multiple vacuums, multiple camera or image maps, and customizable styling are supported, which makes the card relevant to dashboards that expose more than one robot or map state. This is a presentation and control layer, not a new vacuum integration. The card belongs to a Home Assistant instance and sends commands through the services and entities available in that instance. It is therefore the wrong choice for someone who has no Home Assistant vacuum entity, no working map source, or a device whose integration does not expose the required commands. ## Map data, presets, calibration, and action flow inside Lovelace The documented configuration is organized around presets rather than a single vacuum unconditionally. Each preset requires `preset_name` and `entity`, while the visible preset table also requires `map_source`. At the top level, `additional_presets` accepts a list of extra presets, such as configurations associated with different maps or vacuums. This structure gives one card a controlled way to represent several combinations of vacuum and map without duplicating the entire card. Map handling is not treated as a raw image problem. The README contains dedicated sections for map source options, cropping options, calibration source options, and calibration points. Calibration determines how dashboard coordinates relate to the map, while cropping changes the displayed map area. Those controls imply that a usable configuration depends on matching the rendered map to the card's coordinate system. The card's actions operate on that calibrated space, so a visually correct map with incorrect calibration could still send commands to unintended coordinates. The excerpt does not state how automatic the calibration process is or how failures are reported, so that behavior should not be assumed. The action system extends beyond the built-in vacuum commands. Map modes include templates, selection types, a service-call schema, repeat types, predefined selections, icons, and labels. Icon-list and tile-list entries can invoke services and appear conditionally. In practical terms, the card combines an interactive map with Home Assistant service calls and state-based presentation. This is more flexible than a fixed set of buttons, but it also makes the YAML configuration more important because the visual editor is explicitly described as limited to a basic set of features. ## Installing Xiaomi Vacuum Map Card through HACS The documented HACS route starts inside Home Assistant. Open HACS, go to the `Frontend` section, use the button with the `+` icon, search for `Xiaomi Vacuum Map`, and install the repository. Home Assistant must then load the card as a Lovelace module resource. Add this resource entry through the documented Lovelace resources configuration: ```yaml url: /hacsfiles/lovelace-xiaomi-vacuum-map-card/xiaomi-vacuum-map-card.js type: module ``` After adding the resource, refresh the browser. The Lovelace card should then be available through Home Assistant's card interface. The README also points to a `docs/demo_config.yaml` example, which is the safest documented starting point when the required map and calibration values are not yet known. The card does not invent a vacuum configuration during installation. A usable configuration needs a preset name, a Home Assistant vacuum entity, and a map source. The README excerpt does not provide a complete minimal card example with confirmed values for those fields. It also says the visual configuration editor covers only basic features. For a first real use, begin with the demo configuration or add a basic preset in the editor, then compare the map and available controls against the vacuum's Home Assistant entity before saving zones or target positions. ## Manual release installation from the latest GitHub file HACS is not required. The manual route documented by the project is to download `xiaomi-vacuum-map-card.js` from the latest GitHub release and save it under the Home Assistant `www` directory. The README gives this example location: ```text /config/www/custom_lovelace/xiaomi-vacuum-map-card.js ``` Then register the file as a Lovelace module with this configuration: ```yaml url: /local/custom_lovelace/xiaomi-vacuum-map-card.js type: module ``` The `/local/` prefix in the resource URL corresponds to the README's example placement under the Home Assistant `www` directory. Restart Home Assistant if creating the `www` directory required that step, then refresh the browser. This method is useful for an operator who wants to manage the compiled frontend asset directly, but the README does not provide a source build procedure for end users. The package metadata identifies `xiaomi-vacuum-map-card.js` as the module and lists TypeScript, Rollup, Babel, ESLint, Prettier, and related development dependencies, but the installation section directs users to a release artifact rather than a local build command. Each manual upgrade therefore involves obtaining a newer release file, replacing the stored asset, refreshing Home Assistant, and checking the Lovelace view. The documentation does not specify an atomic rollback procedure or a compatibility matrix for card upgrades. ## Platform coverage and calibration limits in Xiaomi Vacuum Map Card The largest practical limitation is the boundary between a named vacuum brand and a confirmed working platform. The README includes Roomba and Ecovacs alongside Xiaomi and several related platforms, but it does not show a complete model-level compatibility matrix. It therefore cannot confirm whether a particular Roomba model, Ecovacs integration, Wyze model, or Valetudo version exposes every command used by the card. Map availability is another constraint. The feature list says multiple camera and image maps are supported, while the configuration model requires a map source and offers calibration and crop controls. The card cannot remove that dependency. If Home Assistant has a vacuum entity but no usable map image, map-based actions will not become usable merely because this Lovelace resource is installed. The README also does not describe a diagnostic report, automatic discovery process, or documented behavior for missing map data. The card is also not the best choice for users who need a complete vacuum dashboard and accept little configuration effort. The visual editor is deliberately limited, while advanced behavior depends on manual YAML adjustments. Conditional icons, tiles, templates, repeat types, service-call schemas, calibration points, and multiple presets can become difficult to maintain as a dashboard grows. This is a configurability trade-off rather than a defect: users gain control over commands and presentation, but they bear responsibility for a larger configuration surface. ## Xiaomi Vacuum Map Card compared with basic Home Assistant vacuum entities The practical alternative is a basic Home Assistant vacuum card or a manually designed Lovelace dashboard based only on the vacuum entity's states and standard services. That approach has a smaller configuration surface and does not require map calibration, saved destinations, or an interactive floor-plan resource. It is the better fit when starting, returning to base, battery status, and basic state display are sufficient. Xiaomi Vacuum Map Card takes a different approach. It treats the floor plan as the primary control surface and adds map selection modes, room and zone commands, saved targets, path following, custom services, conditional controls, and presets that can associate maps with vacuums. A conventional entity card centers on state and standard controls, whereas this card is intended to translate positions and areas into Home Assistant actions. Neither approach can create capabilities missing from the underlying vacuum integration. The map card needs compatible entities, map sources, and exposed services. A basic entity view may work when those richer capabilities are unavailable. The card is consequently more useful after the Home Assistant vacuum integration is functioning and its data model is understood. ## Release cadence, MIT licensing, and maintenance work for this card The repository is not archived. Its last push was on 2026-06-24, and the listed releases include `v2.4.1` on 2026-06-23, `v2.3.2` on 2026-02-04, and a `v2.3.2-beta` on 2026-02-03. The `v2.4.1` release is described as containing Roomba+, Neatsvor, and card editor fixes, while `v2.3.2` is described as adding Home Assistant 2026.2 compatibility. These release notes show changes in platform support and editor behavior, so users should treat the card as dashboard software that can require compatibility checks after Home Assistant updates. The project uses the `MIT` license. That identifies the repository's stated licensing model and allows source availability under its terms, but this review does not interpret the license or provide legal advice. A dashboard maintainer must also account for manual release-asset updates, browser refreshes, possible Home Assistant restarts, and revalidation of map calibration. The README does not document automated upgrade detection, rollback, migration automation for the current configuration, or a service-level compatibility commitment. For builders, the TypeScript source, Rollup configuration, linting rules, and package scripts represent additional maintenance beyond merely downloading a HACS update. For dashboard-only users, the practical upgrade cost is lower but still includes reviewing release notes and checking whether an existing map source or editor configuration changed. ## Conclusion Adopt this card if your Home Assistant setup exposes a supported map-based vacuum platform and you want map controls in Lovelace, especially when saved zones or destinations are part of your routine. Do not treat the stated brand list as proof of compatibility with every model, because the README does not document the full device qualification procedure or a per-model support matrix. Verify first that your vacuum integration supplies the expected entity and map data, then confirm the platform-specific map source and calibration settings before building a larger dashboard around the card. ## FAQ ### How do I install Xiaomi Vacuum Map Card in Home Assistant? Install the repository through HACS under `Frontend`, then add `/hacsfiles/lovelace-xiaomi-vacuum-map-card/xiaomi-vacuum-map-card.js` as a Lovelace module resource and refresh the browser. A manual installation can instead save the released JavaScript file under the Home Assistant `www` directory. ### Which vacuum brands does Xiaomi Vacuum Map Card support? The README names Xiaomi platforms including Roborock, Viomi, Dreame, Roidmi, Valetudo, and Valetudo RE, plus Neato, Wyze, Roomba, and Ecovacs. It does not provide a complete model-level support matrix in the documented excerpt. ### Can Xiaomi Vacuum Map Card create zoned cleaning controls in Lovelace? Yes. The documented features include manual and saved zoned cleaning, target selection, room cleaning, path following, and custom services. Advanced configuration uses manual YAML because the visual editor covers only a basic set of features. ## Sources - [Issues](https://github.com/PiotrMachowski/lovelace-xiaomi-vacuum-map-card/issues) - [License: MIT](https://github.com/PiotrMachowski/lovelace-xiaomi-vacuum-map-card/blob/master/LICENSE) - [PiotrMachowski/lovelace-xiaomi-vacuum-map-card on GitHub](https://github.com/PiotrMachowski/lovelace-xiaomi-vacuum-map-card) - [README](https://github.com/PiotrMachowski/lovelace-xiaomi-vacuum-map-card/blob/master/README.md) - [Releases](https://github.com/PiotrMachowski/lovelace-xiaomi-vacuum-map-card/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/piotrmachowski-lovelace-xiaomi-vacuum-map-card