[opensourcedex]

lovelace-xiaomi-vacuum-map-card is a free, open source automation project written in TypeScript and released under MIT. It has 1,938 GitHub stars, 281 forks and 62 open issues, and was last pushed 3 months ago. On this registry it ranks #45 of 54 tracked projects in Automation, with 5 head-to-head comparisons available.

What is lovelace-xiaomi-vacuum-map-card?

What it is

lovelace-xiaomi-vacuum-map-card is an open-source Home Assistant Lovelace card written in TypeScript and released under the MIT license. It gives users a browser-based control surface for map-based robot vacuums, with named support for Xiaomi-family devices such as Roborock, Viomi, Dreame, Roidmi, Valetudo, and Valetudo RE, as well as Neato, Wyze, Roomba, and Ecovacs. The project lives inside the Home Assistant home-automation ecosystem and targets users who want vacuum control to appear as part of a Lovelace dashboard rather than only as a basic control.

The concrete problem it solves is the need for an interactive map interface for supported robot vacuums inside Home Assistant. The card provides a way to start zoned cleaning, send the robot to a target, clean selected rooms, follow a path, or trigger custom services from the same dashboard. It also provides icon controls and value tiles, so vacuum operation can be organized around the map image instead of around separate dashboard controls.

Key capabilities

  • The card supports map-based controls for zoned cleaning, both manual and saved, and for sending the vacuum to a target, also manual and saved.
  • It can trigger room cleaning, path following, and custom services from the map interface.
  • It provides icon controls whose visibility can be conditional and whose actions can call customizable services.
  • It provides value tiles with customizable content, conditional visibility, and customizable service calls.
  • It supports multiple vacuums and multiple map sources, including camera and image maps.

Who uses it and how

  • Home Assistant users add the card to a Lovelace dashboard to operate supported robot vacuums from a map or camera image.
  • Households with more than one vacuum can use the multiple-vacuum support to keep several robots under one dashboard control pattern.
  • Advanced users can combine icon controls, value tiles, conditional visibility, and custom service calls to build a dashboard-specific vacuum workflow.

Getting started

The README describes two installation methods: install the repository through HACS in the Frontend section, add the card to Lovelace resources using the URL /hacsfiles/lovelace-xiaomi-vacuum-map-card/xiaomi-vacuum-map-card.js and the type module setting, then refresh the browser, or download xiaomi-vacuum-map-card.js from the latest release for manual installation.

When to use it — and when not to

Use this card when you already run Home Assistant, have a supported map-based vacuum, and want dashboard-level controls such as zoned cleaning, target navigation, room cleaning, path following, and custom service calls. It is less suitable when you need a standalone vacuum controller outside Home Assistant, because the README presents it as a Lovelace card that must be added to Home Assistant resources. The provided registry data lists 62 open issues, and the README links to a community forum, so users should expect configuration questions and community troubleshooting.

project readme (upstream, from github) — read inline

HACS Default GitHub Latest Release GitHub All Releases Community Forum [![Ko-Fi][ko_fi_shield]][ko_fi] [![buycoffee.to][buycoffee_to_shield]][buycoffee_to] [![PayPal.Me][paypal_me_shield]][paypal_me] [![Revolut.Me][revolut_me_shield]][revolut_me]

Lovelace 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).

https://user-images.githubusercontent.com/6118709/140251738-7fb06e81-34b0-4bf8-b7b1-2221d0062331.mp4

Table of contents

Features

Features include:

  • Map-based controls:
    • Zoned cleaning (manual and saved)
    • Going to target (manual and saved)
    • Room cleaning
    • Following path
    • Custom services
  • Icon controls:
    • Conditional visibility
    • Customizable service calls
  • Value tiles:
    • Customizable content
    • Conditional visibility
    • Customizable service calls
  • General:
    • Multiple vacuums support
    • Multiple maps (camera/image) support
    • Fully customizable styling

Installation

HACS

Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

  • Open HACS
  • Go to "Frontend" section
  • Click button with "+" icon
  • Search for "Xiaomi Vacuum Map"
  • Install repository in HACS
  • Make sure you have added this card to Lovelace resources
    url: /hacsfiles/lovelace-xiaomi-vacuum-map-card/xiaomi-vacuum-map-card.js
type: module
  • Refresh your browser

Manual

  • Download xiaomi-vacuum-map-card.js file from the latest release
  • Save downloaded file somewhere in /www/ directory, e.g. /config/www/custom_lovelace/xiaomi-vacuum-map-card.js
  • Add saved file to Lovelace resources
    url: /local/custom_lovelace/xiaomi-vacuum-map-card.js
type: module
  • Restart HA if you had to create www directory
  • Refresh your browser

Configuration

This card contains UI configuration editor, but it is limited to only basic set of features. Its full potential can be achieved by manual yaml adjustments.

:warning::warning::warning:

You can use this configuration as an example: demo config (configuration used in full_demo.mp4).

:warning::warning::warning:

Main options

Key Type Required Default Description
title string no empty Card's title
language string no autodetected Overrides autodetected language (supported languages)
action_handler_id string no - Enables action handling
additional_presets list no empty A list of additional presets (e.g. with different map/vacuum)
All values from preset options section

Preset options

Key Type Required Default Description
preset_name string yes1 - Name of the preset
entity string yes - Vacuum entity
map_source string yes - Preset's map source
calibration_source object yes2 - Preset's calibration source
vacuum_platform string no default Preset's vacuum platform
map_locked boolean no false Default state of pan/zoom
two_finger_pan string no false Enables two finger map panning
icons list no autogenerated Preset's icons
append_icons boolean no false Enables appending configured icons to autogenerated ones instead of replacing them
tiles list no autogenerated Preset's tiles
append_tiles boolean no false Enables appending configured tiles to autogenerated ones instead of replacing them
map_modes list no autogenerated Preset's map modes
activate object no - Service call that should be executed after clicking preset name
activate_on_switch boolean no false Enables executing activate service cal

readme truncated — read the full docs on github

Frequently asked questions

Is lovelace-xiaomi-vacuum-map-card free to use?

lovelace-xiaomi-vacuum-map-card is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does lovelace-xiaomi-vacuum-map-card do?

This card provides a user-friendly way to fully control map-based vacuums in Home Assistant. Supported brands include Xiaomi (Roborock/Viomi/Dreame/Roidmi/Valet

What is lovelace-xiaomi-vacuum-map-card written in?

lovelace-xiaomi-vacuum-map-card is primarily written in TypeScript. Its source is publicly available at https://github.com/PiotrMachowski/lovelace-xiaomi-vacuum-map-card, and it has 1,938 GitHub stars.