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
Installation
- HACS
- Manual
Configuration
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
`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	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
`internal_variables`	object	no	-	Allows to specify default values for internal variables

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 out of the box at this moment:

default (Xiaomi Miio)
KrzysztofHajdamowicz/miio2
marotoweb/viomi SE
tykarol/ViomiVacuumV8
rand256/ValetudoRE
Hypfer/Valetudo
send_command
al-one/Xiaomi MIoT (additional manual configuration required)
Neato
Roomba

Create a request for a new built-in platform

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. Warning: use `service_data` instead of `data`
`hold_action`	action	no	-	Action that will be triggered when an icon is held and released. Warning: use `service_data` instead of `data`
`double_tap_action`	action	no	-	Action that will be triggered when an icon is double-tapped. Warning: use `service_data` instead of `data`
`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	no	-	Entity which should be shown on a tile
`internal_variable`	string	no	-	Internal variable 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. Warning: use `service_data` instead of `data`
`hold_action`	action	no	-	Action that will be triggered when a tile is held and released. Warning: use `service_data` instead of `data`
`double_tap_action`	action	no	-	Action that will be triggered when a tile is double-tapped. Warning: use `service_data` instead of `data`
`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
`tile_id`	string	false	-	ID of an autogenerated tile that should be replaced with this one

Condition options

Key	Type	Required	Default	Description
`entity`	string	no	-	Entity ID
`attribute`	string	no	-	Attribute to use instead of entity state
`internal_variable`	string	no	-	Name of internal variable 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
`variables`	object	no	-	Variables that should be passed to `service_call_schema`
`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

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
`target`	object	no	-	Target that should be passed to service call
`evaluate_data_as_template`	boolean	no	`false`	Enables support for jinja templates in service calls

It is possible to use several built-in 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)
[[variables]]: a list of variables for all selections

It is possible to use any value from variables section (wrapped with double rectangular brackets):

variables:
  test_variable: 123
service_call_schema:
  service: fake.service
  service_data:
    var: "[[test_variable]]"

It is possible to use following modifiers in service_data section:

|[[jsonify]]: if value ends with this modifier it will be decoded as a JSON and attached to service call in unwrapped form
|[[jsonify_jinja]]: behaves in the same way as |[[jsonify]], but is executed after jinja templating

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
`variables`	object	no	-	Variables that should be passed to `service_call_schema`

See this page 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
`variables`	object	no	-	Variables that should be passed to `service_call_schema`

See this page 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
`variables`	object	no	-	Variables that should be passed to `service_call_schema`

See this page 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)

Action handling

To enable handling actions you have to configure action_handler_id in Main options. This card handles following actions:

Set a value of internal variable

  tap_action:
    action: fire-dom-event
    xiaomi_vacuum_map_card:
      action_handler_id: xiaomi_vacuum_map_card_id_1
      action: set_internal_variable
      variable: variable_1
      value: "some value"

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)

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]]

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)

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]]

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)
nb-NO - Norwegian Bokmål (Norsk bokmål)
nl - Dutch (Nederlands)
pl - Polish (Polski)
pt-BR - Brazilian Portuguese (Português Brasileiro)
ru - Russian (Русский)
sk - Slovak (Slovenčina)
sv - Swedish (Svenska)
tr - Turkish (Türkçe)
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:

alisonmwhite / lovelace-xiaomi-vacuum-map-card Goto Github PK

lovelace-xiaomi-vacuum-map-card's Introduction