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

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

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	no1	-	Entity id of map camera
image	string	no1	-	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	Default	Description
top	number	no	0	Image cropping value from the top (in pixels)
bottom	number	no	0	Image cropping value from the bottom (in pixels)
left	number	no	0	Image cropping value from the left (in pixels)
right	number	no	0	Image cropping value from the right (in pixels)

Calibration source options

Key	Type	Required	Default	Description
camera	string	no1	0	Camera with calibration (Xiaomi Cloud Map Extractor)
entity	string	no1	0	Entity with calibration returned as a state
attribute	string	no	0	Enables usage of a configured attribute instead of state of given entity
calibration_points	list	no1	0	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	no1	-	Map mode template to be used (supported templates)
name	string	yes2	-	Name of map mode
icon	string	yes2	-	Icon of map mode (mdi)
selection_type	string	yes2	-	Type of selection, one of supported ones
service_call_schema	object	yes2	-	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	no3	-

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:

• Brazilian Portuguese (Português Brasileiro)
• English
• French (Français)
• Italian
• Polish (Polski)
• Spanish (Español)
• Ukrainian (Українська)

Adding a new language

Special thanks

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

• Bartosz Orczyk
• Filip Schramm
• Kamil Dryzek
• Marek Trochimiak