Lovelace Xiaomi Vacuum Map card

This card provides a user-friendly way to fully control Xiaomi (and 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
`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
`tiles`	list	no	autogenerated	Preset's tiles
`map_modes`	list	no	autogenerated	Preset's map modes

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	Description
`camera`	string	no¹	Camera with calibration (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

¹ Exactly one of camera, entity or calibration_points 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 Home Assistant integration
KrzysztofHajdamowicz/miio2: Custom miio2 integration by Krzysztof Hajdamowicz

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

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

Condition options

Key	Type	Required	Default	Description
`entity`	string	no	-	Entity id of map camera
`attribute`	string	no*	-	URL of map image
`value`	string	no*	-	URL of map image
`value_not`	string	no*	-	URL of map image

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: Free-drawn rectangular zones on the map
- vacuum_clean_zone_predefined: Rectangular zones that can be selected on the map from predefined_selections
- vacuum_goto: Point selected by clicking in an arbitrary place on the map
- vacuum_goto_predefined: Point selected on the map from predefined_selections
- vacuum_clean_segment: Identifier-based selection with free-drawn outline
- vacuum_follow_path: Path selected by clicking on the map (using script)
KrzysztofHajdamowicz/miio2
- vacuum_clean_zone: Free-drawn rectangular zones on the map
- vacuum_clean_zone_predefined: Rectangular zones that can be selected on the map from predefined_selections
- vacuum_goto: Point selected by clicking in an arbitrary place on the map
- vacuum_goto_predefined: Point selected on the map from predefined_selections
- vacuum_clean_segment: Identifier-based selection with free-drawn outline
- vacuum_follow_path: Path selected by clicking on the map (using script)

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)
[[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)

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

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)
`tooltip`	string	false	-	Tooltip to be displayed on hoover

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)
`tooltip`	string	false	-	Tooltip to be displayed on hoover
`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)

Hints

Getting room/point coordinates

To get coordinates switch to a specific mode, create a selection and hold "Play" button. A popup with full service call details will be shown. This feature replaces debug option from previous versions of the card. Config will also be written in browser's console to make it easier to copy.
Creating outline

To create an outline follow these steps:
- Add - template: vacuum_follow_path to map_modes section
- Select "Path" from modes dropdown
- Mark a selected outline on a map
- Hold "Play" button
- Your outline will be in path section of service data

Advanced styling

You can add any of these variables to your theme to override default card styling.

It is also possible to style this card using card-mod.

Example - changing room selection colors

...
style: |
  .room-1-wrapper {
    --map-card-internal-room-outline-line-color: red;
    --map-card-internal-room-outline-fill-color: rgba(255, 0, 0, 0.5)
  }
  .room-2-wrapper {
    --map-card-internal-room-outline-line-color: blue;
    --map-card-internal-room-outline-fill-color: rgba(0, 0, 255, 0.5)
  }
  .room-<room_id>-wrapper {
    --map-card-internal-room-outline-line-color: green;
    --map-card-internal-room-outline-fill-color: rgba(0, 255, 0, 0.5)
  }

Adding icons/tiles to the default configuration

Generated icons/tiles will be overwritten when icons/tiles config is provided. To extract default generated configuration double-tap play icon: config will be available as a JSON in browser's console. You can convert it to YAML using json2yaml.com.

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:

English
Polish (Polski)

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 120 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 Xiaomi 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

Hints

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

Gilzy/lovelace-xiaomi-vacuum-map-card

Folders and files

Latest commit

History

Repository files navigation

Lovelace Xiaomi 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

Hints

FAQ

Migrating from v1.x.x

Translations

Special thanks

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages