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.

https://user-images.githubusercontent.com/6118709/140251738-7fb06e81-34b0-4bf8-b7b1-2221d0062331.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.

:warning::warning::warning:

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

:warning::warning::warning:

Main options

Preset options

Map source options

¹ Exactly one of camera or image must be provided

Cropping options

Calibration source options

¹ 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: Built-in Xiaomi Miio integration
• KrzysztofHajdamowicz/miio2: Custom miio2 integration by KrzysztofHajdamowicz
• marotoweb/viomise: Custom Viomi SE integration by marotoweb
• rand256/ValetudoRE: Valetudo RE via MQTT by rand256
• send_command: Uses vacuum.send_command service with commands: app_zoned_clean, app_goto_target, app_segment_clean
• Neato: Built-in Neato integration

It's possible to configure following platforms manually:

• Xiaomi Miot: discussion, vacuum configs

Create a request for a new built-in platform

Adding a new platform

Icon list entry options

Tile list entry options

Condition options

¹ Exactly one of them has to be provided

Map modes options

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)
  • vacuum_clean_segment: Room cleaning based on identifier - room number (getting outline, config generator)
• rand256/ValetudoRE
  • vacuum_clean_segment: Room cleaning based on identifier - room number or name
  • vacuum_goto_predefined: Going to point selected on the map from predefined_selections
• 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

  https://user-images.githubusercontent.com/6118709/141666913-d95f082d-f5bf-4ab5-a478-ba44effe6f34.mp4

• PREDEFINED_RECTANGLE: Rectangular zones that can be selected on the map from predefined_selections

  Example video

  https://user-images.githubusercontent.com/6118709/141666920-492a000c-9a78-4c20-b4f5-9343928140c7.mp4

• MANUAL_POINT: Point selected by clicking in an arbitrary place on the map

  Example video

  https://user-images.githubusercontent.com/6118709/141666921-2f3d66da-6ffc-492a-8439-625da97651bd.mp4

• PREDEFINED_POINT: Point selected on the map from predefined_selections

  Example video

  https://user-images.githubusercontent.com/6118709/141666923-965679e9-25fb-44cd-be08-fc63e5c85ce0.mp4

• ROOM: Identifier-based selection with free-drawn outline

  Example video

  https://user-images.githubusercontent.com/6118709/141666925-34b01cde-82ff-447b-aecc-e9ced402b1ed.mp4

• MANUAL_PATH: Path selected by clicking on the map

  Example video

  https://user-images.githubusercontent.com/6118709/141666931-48d1717f-96d0-461d-84f4-788c071f3a78.mp4

Service call schema options

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)

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

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

Label options

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

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_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)
• 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:

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