This card provides a user-friendly way to fully control Xiaomi (and possibly other) vacuums in Home Assistant.

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

• 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

• 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

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

⚠️⚠️⚠️

¹ Exactly one of camera or image must be provided

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

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

Following vacuum platforms are supported at this moment:

• default: Built-in Home Assistant 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

Adding a new platform

¹ Exactly one of them has to be provided

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

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
  • 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
  • vacuum_clean_segment: Room cleaning based on identifier
  • 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
  • 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
  • vacuum_clean_segment: Room cleaning based on identifier
  • 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
  • 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
• 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
  • 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
  • vacuum_clean_segment: Room cleaning based on identifier
  • vacuum_follow_path: Following path selected by clicking on the map (using script)

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

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

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)

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

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.

• 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.

• 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.

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

Currently, this card contains translations for following languages:

• da - Danish
• de - German (Deutsch)
• en - English
• es - Spanish (Español)
• fr - French (Français)
• he - Hebrew (עברית)
• hu - Hungarian (Magyar)
• it - Italian (Italiano)
• nl - Dutch (Nederlands)
• pl - Polish (Polski)
• pt-BR - Brazilian Portuguese (Português Brasileiro)
• ru - Russian (Русский)
• uk - Ukrainian (Українська)
• zh - Chinese (中文)

Adding a new language

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