/lovelace-xiaomi-vacuum-map-card

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

Primary LanguageTypeScriptMIT LicenseMIT

Lovelace Xiaomi Vacuum Map card

HACS Default GitHub Latest Release GitHub All Releases Community Forum Buy me a coffee PayPal.Me

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

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

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

1 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 boolean no1 - Enables retrieving calibration from camera defined in map_source (Xiaomi Cloud Map Extractor)
entity string no1 - 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 no1 - List of 3 or 4 calibration points

1 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:

Adding a new platform

Icon list entry options

icons image

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

Tile list entry options

tiles image

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

Condition options

Key Type Required Default Description
entity string yes - Entity ID
attribute string no - Attribute to use instead of entity state
value string no1 - Entity state/attribute has to be equal to this value
value_not string no1 - Entity state/attribute has to be unequal to this value

1 Exactly one of them has to be provided

Map modes options

map modes image

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

1 Not required if all parameters with (2) are provided

2 Required if template is not provided

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

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)

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)

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:

  • da - Danish
  • de - German (Deutsch)
  • en - English
  • es - Spanish (Español)
  • fr - French (Français)
  • hu - Hungarian (Magyar)
  • it - Italian (Italiano)
  • nl - Dutch (Nederlands)
  • pl - Polish (Polski)
  • pt-BR - Brazilian Portuguese (Português Brasileiro)
  • ru - Russian (Русский)
  • uk - 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:

Buy Me A Coffee