Lovelace Vacuum Map card

This card provides a user-friendly way to fully control Xiaomi (Roborock/Viomi/Dreame/Roidmi) and Neato (+ possibly other) vacuums in Home Assistant.

full_demo.mp4

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 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 <ha config>/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.

⚠️⚠️⚠️

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

⚠️⚠️⚠️

Main options

Key	Type	Required	Default	Description
`title`	string	no	empty	Card's title
`language`	string	no	autodetected	Overrides autodetected language (supported languages)
`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	yes (if multiple presets are configured)	-	Name of the preset
`entity`	string	yes	-	Vacuum entity
`map_source`	string	yes	-	Preset's map source
`calibration_source`	object	yes	-	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 call after switching map preset
`conditions`	list	no	-	List of conditions that need to be (all of them) met for preset to be shown
`clean_selection_on_start`	boolean	no	`true`	Allows to disable cleaning selection on cleanup start

Map source options

Key	Type	Required	Default	Description
`camera`	string	no¹	-	Entity id of map camera
`image`	string	no¹	-	URL of map image
`crop`	object	no	no cropping	Images cropping options

¹ Exactly one of camera or image must be provided

Cropping options

Key	Type	Required	Description
`top`	number	no	Image cropping value from the top (in pixels)
`bottom`	number	no	Image cropping value from the bottom (in pixels)
`left`	number	no	Image cropping value from the left (in pixels)
`right`	number	no	Image cropping value from the right (in pixels)

Calibration source options

Key	Type	Required	Default	Description
`camera`	boolean	no¹	-	Enables retrieving calibration from camera defined in `map_source` (Xiaomi Cloud Map Extractor)
`entity`	string	no¹	-	Entity with calibration returned as a state
`attribute`	string	no	-	Enables usage of a configured attribute instead of state of given entity
`calibration_points`	list	no¹	-	List of 3 or 4 calibration points
`identity`	boolean	no¹	-	Enables using image coordinates on map (e.g. when map is used just for rooms)

¹ Exactly one of camera, entity, calibration_points or identity must be provided

Calibration points options

Each of calibration points must have a following structure:

vacuum: # coordinates of a point in a vacuum coordinate system
  x: 25500
  y: 25500
map: # coordinates of a point in a map coordinate system (can be read using e.g. Paint or Gimp)
  x: 466
  y: 1889

Manual calibration guide

Supported vacuum platforms

Following vacuum platforms are supported at this moment:

default: Built-in Xiaomi Miio integration
KrzysztofHajdamowicz/miio2: Custom miio2 integration by KrzysztofHajdamowicz
marotoweb/viomise: Custom Viomi SE integration by marotoweb
send_command: Uses vacuum.send_command service with commands: app_zoned_clean, app_goto_target, app_segment_clean
Neato: Built-in Neato integration

Adding a new platform

Icon list entry options

Key	Type	Required	Default	Description
`icon`	string	yes	-	An icon to be displayed (mdi)
`tap_action`	action	no	more-info	Action that will be triggered when an icon is tapped
`hold_action`	action	no	-	Action that will be triggered when an icon is held and released
`double_tap_action`	action	no	-	Action that will be triggered when an icon is double-tapped
`conditions`	list	no	-	List of conditions that need to be (all of them) met for an icon to be shown
`tooltip`	string	false	-	Tooltip to be displayed on hoover

Tile list entry options

Key	Type	Required	Default	Description
`label`	string	yes	-	Label of a tile
`entity`	string	yes	-	Entity which should be shown on a tile
`icon`	string	no	-	An icon to be displayed (mdi)
`attribute`	string	no	-	Attribute that should be shown on a tile
`multiplier`	number	no	-	Multiplier that should be used to calculate value shown on a tile
`precision`	number	no	-	Precision that should be used to present value on a tile
`unit`	string	no	-	Unit to be used
`tap_action`	action	no	more-info	Action that will be triggered when a tile is tapped
`hold_action`	action	no	-	Action that will be triggered when a tile is held and released
`double_tap_action`	action	no	-	Action that will be triggered when a tile is double-tapped
`conditions`	list	no	-	List of conditions that need to be (all of them) met for a tile to be shown
`tooltip`	string	false	-	Tooltip to be displayed on hoover
`translations`	map	false	-	Translations that should be applied to tile's value

Condition options

Key	Type	Required	Default	Description
`entity`	string	yes	-	Entity ID
`attribute`	string	no	-	Attribute to use instead of entity state
`value`	string	no¹	-	Entity state/attribute has to be equal to this value
`value_not`	string	no¹	-	Entity state/attribute has to be unequal to this value

¹ Exactly one of them has to be provided

Map modes options

Key	Type	Required	Default	Description
`template`	string	no¹	-	Map mode template to be used (supported templates)
`name`	string	yes²	-	Name of map mode
`icon`	string	yes²	-	Icon of map mode (mdi)
`selection_type`	string	yes²	-	Type of selection, one of supported ones
`service_call_schema`	object	yes²	-	Service call schema that should be used in this mode
`run_immediately`	boolean	no	`false`	Enables calling service immediately after choosing a selection
`coordinates_rounding`	boolean	no	`true`	Enables coordinates rounding
`max_selections`	integer	no	1	Maximal number of selections
`repeats_type`	string	no	`NONE`	Type of repeats inclusion, one of supported ones
`max_repeats`	integer	no	1	Maximal value of repeats
`predefined_selections`	list	no³	-

You can override any value from built-in template by providing it in your configuration

¹ Not required if all parameters with (²) are provided

² Required if template is not provided

³ Required if template is not provided and selection_type is one of: PREDEFINED_RECTANGLE, PREDEFINED_POINT, ROOM

Supported templates

List of supported templates depends on selected vacuum_platform:

default:
- vacuum_clean_zone: Cleaning free-drawn rectangular zones on the map
- vacuum_clean_zone_predefined: Cleaning rectangular zones that can be selected on the map from predefined_selections (getting coordinates)
- vacuum_goto: Going to point selected by clicking in an arbitrary place on the map
- vacuum_goto_predefined: Going to point selected on the map from predefined_selections (getting coordinates)
- vacuum_clean_segment: Room cleaning based on identifier - room number (getting outline, config generator)
- vacuum_follow_path: Following path selected by clicking on the map (using script)
KrzysztofHajdamowicz/miio2
- vacuum_clean_zone: Cleaning free-drawn rectangular zones on the map
- vacuum_clean_zone_predefined: Cleaning rectangular zones that can be selected on the map from predefined_selections (getting coordinates)
- vacuum_goto: Going to point selected by clicking in an arbitrary place on the map
- vacuum_goto_predefined: Going to point selected on the map from predefined_selections (getting coordinates)
- vacuum_clean_segment: Room cleaning based on identifier - room number (getting outline, config generator)
- vacuum_follow_path: Following path selected by clicking on the map (using script)
marotoweb/viomise
- vacuum_clean_zone: Cleaning free-drawn rectangular zones on the map
- vacuum_clean_zone_predefined: Cleaning rectangular zones that can be selected on the map from predefined_selections (getting coordinates)
- vacuum_clean_point: Cleaning around point selected by clicking in an arbitrary place on the map
- vacuum_clean_point_predefined: Cleaning around point selected on the map from predefined_selections (getting coordinates)
send_command
- vacuum_clean_zone: Cleaning free-drawn rectangular zones on the map
- vacuum_clean_zone_predefined: Cleaning rectangular zones that can be selected on the map from predefined_selections (getting coordinates)
- vacuum_goto: Going to point selected by clicking in an arbitrary place on the map
- vacuum_goto_predefined: Going to point selected on the map from predefined_selections (getting coordinates)
- vacuum_clean_segment: Room cleaning based on identifier - room number (getting outline, config generator)
- vacuum_follow_path: Following path selected by clicking on the map (using script)
Neato
- vacuum_clean_segment: Room cleaning based on identifier (getting outline)

See hints to check how to easily retrieve zone/point coordinates.

Supported selection types

Following selection types are supported at this moment:

MANUAL_RECTANGLE: Free-drawn rectangular zones on the map

Example video

MANUAL_RECTANGLE.mp4
PREDEFINED_RECTANGLE: Rectangular zones that can be selected on the map from predefined_selections

Example video

PREDEFINED_RECTANGLE.mp4
MANUAL_POINT: Point selected by clicking in an arbitrary place on the map

Example video

MANUAL_POINT.mp4
PREDEFINED_POINT: Point selected on the map from predefined_selections

Example video

PREDEFINED_POINT.mp4
ROOM: Identifier-based selection with free-drawn outline

Example video

ROOM.mp4
MANUAL_PATH: Path selected by clicking on the map

Example video

MANUAL_PATH.mp4

Service call schema options

Key	Type	Required	Default	Description
`service`	string	yes	-	Service that should be called in a given mode
`service_data`	object	no	-	Data that should be passed to service call

It is possible to use several placeholders in service_data section. They will be replaced by:

[[entity_id]]: entity_id defined in preset's config
[[selection]]: selection made on the map (zone, point or path)
[[selection_size]]: number of selections made on the map
[[selection_unwrapped]]: the same as [[selection]], but passed as string unwrapped from brackets
[[repeats]]: selected number of repeats
[[point_x]]: x coordinate of selected point (for MANUAL_POINT and PREDEFINED_POINT selection types)
[[point_y]]: y coordinate of selected point (for MANUAL_POINT and PREDEFINED_POINT selection types)

It is possible to use following modifiers in service_data section:

|[[jsonize]]: if value ends with this modifier it will be decoded as a JSON

Supported repeats types

Following repeats types are supported at this moment:

NONE: No repeats
INTERNAL: Repeats number included in coordinates array ([25500, 25000, 26500, 26500, 2])
EXTERNAL: Repeats number used as a separate attribute in service_call_schema
REPEAT: Repeats selection (repeats: 2, selection: [5,6] => [5,6,5,6])

Predefined selection options

Format of data depends on selected selection_type:

PREDEFINED_RECTANGLE

Key	Type	Required	Default	Description
`zones`	list	yes	-	List of lists containing zone's coordinates in `[x,y,width,height]` format (e.g. `[[25500, 25000, 26500, 26500]]`)
`icon`	object	no	-	Icon definition
`label`	object	no	-	Label definition

See hints to check how to easily retrieve zone coordinates.

PREDEFINED_POINT

Key Type Required Default Description

position list yes - Point's coordinates in [x,y] format (e.g. [25500, 25000])

icon object no - Icon definition

label object no - Label definition

See hints to check how to easily retrieve point coordinates.

ROOM

Key	Type	Required	Default	Description
`id`	string or number	yes	-	Room's identifier
`outline`	list	no	-	List of points forming an outline of a room (e.g. `[[25500,25500],[26500,25500],[25500,26500]]`
`icon`	object	no	-	Icon definition
`label`	object	no	-	Label definition

See hints to check how to easily create outline.

Icon options

Key	Type	Required	Default	Description
`name`	string	yes	-	An icon to be displayed (mdi)
`x`	number	yes	-	X coordinate of an icon (in vacuum's coordinate system)
`y`	number	yes	-	Y coordinate of an icon (in vacuum's coordinate system)

Label options

Key	Type	Required	Default	Description
`text`	string	yes	-	Text to be displayed
`x`	number	yes	-	X coordinate of a label (in vacuum's coordinate system)
`y`	number	yes	-	Y coordinate of a label (in vacuum's coordinate system)
`offset_x`	number	no	-	Offset that should be applied to label in X direction (in pixels)
`offset_y`	number	no	-	Offset that should be applied to label in Y direction (in pixels)

FAQ

Make sure to check out FAQ section in Discussions, it contains a lot of useful information
Does this card require rooted device?

No, it only utilizes features of Home Assistant.
How to create a map?

The easiest way is to use Xiaomi Cloud Map Extractor, but you can use any image (e.g. a screenshot from Mi Home/FloleVac).
Can I use image that has a perspective distortion?

Yes, you just have to provide 4 calibration points.

Migrating from v1.x.x

Configuration with map_image

Old config (v1.x.x) New config (v2.x.x)

type: custom:xiaomi-vacuum-map-card
entity: vacuum.xiaomi_vacuum
map_image: '/local/custom_lovelace/xiaomi_vacuum_map_card/map.png'
calibration_points:
  - vacuum:
      x: 25500
      y: 25500
    map:
      x: 466
      y: 1889
  - vacuum:
      x: 26500
      y: 26500
    map:
      x: 730
      y: 1625
  - vacuum:
      x: 25500
      y: 26500
    map:
      x: 466
      y: 1625
zones:
  - [[25500, 25500, 26500, 26500]]
  - [[24245, 25190, 27495, 27940], [27492, 26789, 28942, 27889]]

type: custom:xiaomi-vacuum-map-card
entity: vacuum.xiaomi_vacuum
map_source:
  image: '/local/custom_lovelace/xiaomi_vacuum_map_card/map.png'
calibration_source:
  calibration_points:
    - vacuum:
        x: 25500
        y: 25500
      map:
        x: 466
        y: 1889
    - vacuum:
        x: 26500
        y: 26500
      map:
        x: 730
        y: 1625
    - vacuum:
        x: 25500
        y: 26500
      map:
        x: 466
        y: 1625
map_modes:
  - template: vacuum_clean_zone
  - template: vacuum_goto
  - template: vacuum_clean_zone_predefined
    predefined_selections:
      - zones: [[25500, 25500, 26500, 26500]]
      - zones: [[24245, 25190, 27495, 27940], [27492, 26789, 28942, 27889]]

Configuration with map_camera

Old config (v1.x.x) New config (v2.x.x)

type: custom:xiaomi-vacuum-map-card
entity: vacuum.xiaomi_vacuum
map_camera: camera.xiaomi_cloud_map_extractor
camera_calibration: true
zones:
  - [[25500, 25500, 26500, 26500]]
  - [[24245, 25190, 27495, 27940], [27492, 26789, 28942, 27889]]

type: custom:xiaomi-vacuum-map-card
entity: vacuum.xiaomi_vacuum
map_source:
  camera: camera.xiaomi_cloud_map_extractor
calibration_source:
  camera: true
map_modes:
  - template: vacuum_clean_zone
  - template: vacuum_goto
  - template: vacuum_clean_zone_predefined
    predefined_selections:
      - zones: [[25500, 25500, 26500, 26500]]
      - zones: [[24245, 25190, 27495, 27940], [27492, 26789, 28942, 27889]]

Translations

Currently, this card contains translations for following languages:

cs - Czech (Čeština)
da - Danish (Dansk)
de - German (Deutsch)
el - Greek (Ελληνικά)
en - English
es - Spanish (Español)
fr - French (Français)
he - Hebrew (עברית)
hu - Hungarian (Magyar)
is - Icelandic (Íslenska)
it - Italian (Italiano)
nl - Dutch (Nederlands)
pl - Polish (Polski)
pt-BR - Brazilian Portuguese (Português Brasileiro)
ru - Russian (Русский)
sk - Slovak (Slovenčina)
sv - Swedish (Svenska)
uk - Ukrainian (Українська)
zh - Chinese (中文)
zh-Hant - Traditional Chinese (正體中文)

Adding a new language

Special thanks

I'd like to give special thanks to people who helped me with card's design and development:

Name		Name	Last commit message	Last commit date
Latest commit History 257 Commits
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
docs		docs
src		src
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.js		.prettierrc.js
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
hacs.json		hacs.json
package-lock.json		package-lock.json
package.json		package.json
rollup.config.dev.js		rollup.config.dev.js
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Lovelace Vacuum Map card

Table of contents

Features

Installation

HACS

Manual

Configuration

Main options

Preset options

Map source options

Cropping options

Calibration source options

Calibration points options

Supported vacuum platforms

Icon list entry options

Tile list entry options

Condition options

Map modes options

Supported templates

Supported selection types

Service call schema options

Supported repeats types

Predefined selection options

Icon options

Label options

FAQ

Migrating from v1.x.x

Translations

Special thanks

About

Releases

Packages

Languages

Key	Type	Required	Default	Description
`position`	list	yes	-	Point's coordinates in `[x,y]` format (e.g. `[25500, 25000]`)
`icon`	object	no	-	Icon definition
`label`	object	no	-	Label definition

License

Marlo461/lovelace-xiaomi-vacuum-map-card

Folders and files

Latest commit

History

Repository files navigation

Lovelace Vacuum Map card

Table of contents

Features

Installation

HACS

Manual

Configuration

Main options

Preset options

Map source options

Cropping options

Calibration source options

Calibration points options

Supported vacuum platforms

Icon list entry options

Tile list entry options

Condition options

Map modes options

Supported templates

Supported selection types

Service call schema options

Supported repeats types

Predefined selection options

Icon options

Label options

FAQ

Migrating from v1.x.x

Translations

Special thanks

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages