Home

Awesome

HACS Default GitHub Latest Release GitHub All Releases Community Forum<!-- piotrmachowski_support_badges_start --> Ko-Fi buycoffee.to PayPal.Me Revolut.Me

<!-- piotrmachowski_support_badges_end -->

Lovelace Vacuum Map card

This card provides a user-friendly way to fully control map-based vacuums in Home Assistant. Supported brands include Xiaomi (Roborock/Viomi/Dreame/Roidmi/Valetudo/Valetudo RE), Neato, Wyze, Roomba, Ecovacs (and probably more).

https://user-images.githubusercontent.com/6118709/140251738-7fb06e81-34b0-4bf8-b7b1-2221d0062331.mp4

Table of contents

Features

Features include:

Installation

HACS

Manual

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

<table> <tr> <th>Key</th> <th>Type</th> <th>Required</th> <th>Default</th> <th>Description</th> </tr> <tr> <td><code>title</code></td> <td>string</td> <td>no</td> <td><i>empty</i></td> <td>Card's title</td> </tr> <tr> <td><code>language</code></td> <td>string</td> <td>no</td> <td><i>autodetected</i></td> <td>Overrides autodetected language (<a href="#translations">supported languages</a>)</td> </tr> <tr> <td><code>action_handler_id</code></td> <td>string</td> <td>no</td> <td>-</td> <td>Enables <a href="#action-handling">action handling</a></td> </tr> <tr> <td><code>additional_presets</code></td> <td>list</td> <td>no</td> <td><i>empty</i></td> <td>A list of additional <a href="#preset-options">presets</a> (e.g. with different map/vacuum)</td> </tr> <tr> <td colspan="5" style="text-align: center"> All values from <a href="#preset-options">preset options</a> section </td> </tr> </table>

Preset options

KeyTypeRequiredDefaultDescription
preset_namestringyes<sup>1</sup>-Name of the preset
entitystringyes-Vacuum entity
map_sourcestringyes-Preset's map source
calibration_sourceobjectyes<sup>2</sup>-Preset's calibration source
vacuum_platformstringnodefaultPreset's vacuum platform
map_lockedbooleannofalseDefault state of pan/zoom
two_finger_panstringnofalseEnables two finger map panning
iconslistnoautogeneratedPreset's icons
append_iconsbooleannofalseEnables appending configured icons to autogenerated ones instead of replacing them
tileslistnoautogeneratedPreset's tiles
append_tilesbooleannofalseEnables appending configured tiles to autogenerated ones instead of replacing them
map_modeslistnoautogeneratedPreset's map modes
activateobjectno-Service call that should be executed after clicking preset name
activate_on_switchbooleannofalseEnables executing activate service call after switching map preset
conditionslistno-List of conditions that need to be (all of them) met for preset to be shown
clean_selection_on_startbooleannotrueAllows to disable cleaning selection on cleanup start
internal_variablesobjectno-Allows to specify default values for internal variables

<sup>1</sup> If multiple presets are configured

<sup>2</sup> Not mandatory when used with a platform that support a default calibration

Map source options

KeyTypeRequiredDefaultDescription
camerastringno<sup>1</sup>-Entity id of map camera
imagestringno<sup>1</sup>-URL of map image
cropobjectnono croppingImages cropping options

<sup>1</sup> Exactly one of camera or image must be provided

Cropping options

KeyTypeRequiredDefaultDescription
topnumberno0Image cropping value from the top (in pixels)
bottomnumberno0Image cropping value from the bottom (in pixels)
leftnumberno0Image cropping value from the left (in pixels)
rightnumberno0Image cropping value from the right (in pixels)

Calibration source options

KeyTypeRequiredDefaultDescription
camerabooleanno<sup>1</sup>-Enables retrieving calibration from camera defined in map_source (Xiaomi Cloud Map Extractor)
entitystringno<sup>1</sup>-Entity with calibration returned as a state
attributestringno-Enables usage of a configured attribute instead of state of given entity
calibration_pointslistno<sup>1</sup>-List of 3 or 4 calibration points
identitybooleanno<sup>1</sup>-Enables using image coordinates on map (e.g. when map is used just for rooms)
platformstringno<sup>1</sup>-Enables using a default calibration from a chosen platform (provided that it supports it)

<sup>1</sup> Exactly one of camera, entity, calibration_points, identity or platform 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:

Create a request for a new built-in platform

Adding a new platform

Icon list entry options

icons image

KeyTypeRequiredDefaultDescription
iconstringyes-An icon to be displayed (mdi)
icon_idstringno-Icon ID that can be used to override the configuration
tap_actionactionnomore-infoAction that will be triggered when an icon is tapped. </br>Warning: use service_data instead of data
hold_actionactionno-Action that will be triggered when an icon is held and released. </br>Warning: use service_data instead of data
double_tap_actionactionno-Action that will be triggered when an icon is double-tapped. </br>Warning: use service_data instead of data
conditionslistno-List of conditions that need to be (all of them) met for an icon to be shown
tooltipstringno-Tooltip to be displayed on hoover
ordernumberno-Used to sort the icons
replace_configbooleannofalseMarks that this icon should override the config of an already existing icon with the same icon_id
menu_idstringno-Adds this icon to the menu with given ID
labelstringno-Label that should be displayed in the menu
variablesobjectno-Variables that should be passed to to service calls

Menu icon additional options

KeyTypeRequiredDefaultDescription
typestringyes-Has to be set to menu
menu_idstringyes-A menu ID
entitystringyes-Entity that should be used to generate the menu
current_value_attributestringno-Changes the source of the selected value to given attribute
available_values_attributestringyes-Configures an attribute that contains all available values for the menu
icon_mappingobjectno-A mapping of possible entity value -> icon that should be used for the value
value_translation_keysobjectno-A mapping of possible entity value -> label that should be used for the value
tap_actionobjectno-Action that should enable a specific value

Examples:

Tile list entry options

tiles image

KeyTypeRequiredDefaultDescription
labelstringno-Label of a tile
entitystringno-Entity which should be shown on a tile
internal_variablestringno-Internal variable which should be shown on a tile
iconstringno-An icon to be displayed (mdi)
icon_sourcestringno-Source of an icon, e.g: vacuum.xiaomi.attributes.battery_icon
attributestringno-Attribute that should be shown on a tile
multipliernumberno-Multiplier that should be used to calculate value shown on a tile
precisionnumberno-Precision that should be used to present value on a tile
unitstringno-Unit to be used
tap_actionactionnomore-infoAction that will be triggered when a tile is tapped. </br>Warning: use service_data instead of data
hold_actionactionno-Action that will be triggered when a tile is held and released. </br>Warning: use service_data instead of data
double_tap_actionactionno-Action that will be triggered when a tile is double-tapped. </br>Warning: use service_data instead of data
conditionslistno-List of conditions that need to be (all of them) met for a tile to be shown
tooltipstringno-Tooltip to be displayed on hoover
translationsmapno-Translations that should be applied to tile's value
tile_idstringno-ID of an autogenerated tile that should be replaced with this one
ordernumberno-Used to sort the tiles
replace_configbooleannofalseMarks that this tile should override the config of an already existing tile with the same tile_id
variablesobjectno-Variables that should be passed to to service calls

Condition options

KeyTypeRequiredDefaultDescription
entitystringno-Entity ID
attributestringno-Attribute to use instead of entity state
internal_variablestringno-Name of internal variable to use instead of entity state
valuestringno<sup>1</sup>-Entity state/attribute has to be equal to this value
value_notstringno<sup>1</sup>-Entity state/attribute has to be unequal to this value

<sup>1</sup> Exactly one of them has to be provided

Map modes options

map modes image

KeyTypeRequiredDefaultDescription
templatestringno<sup>1</sup>-Map mode template to be used (supported templates)
namestringyes<sup>2</sup>-Name of map mode
iconstringyes<sup>2</sup>-Icon of map mode (mdi)
selection_typestringyes<sup>2</sup>-Type of selection, one of supported ones
service_call_schemaobjectyes<sup>2</sup>-Service call schema that should be used in this mode
run_immediatelybooleannofalseEnables calling service immediately after choosing a selection
coordinates_roundingbooleannotrueEnables coordinates rounding
max_selectionsintegerno1Maximal number of selections
repeats_typestringnoNONEType of repeats inclusion, one of supported ones
max_repeatsintegerno1Maximal value of repeats
variablesobjectno-Variables that should be passed to service_call_schema
predefined_selectionslistno<sup>3</sup>-

You can override any value from built-in template by providing it in your configuration

<sup>1</sup> Not required if all parameters with (<sup>2</sup>) are provided

<sup>2</sup> Required if template is not provided

<sup>3</sup> 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:

Service call schema options

KeyTypeRequiredDefaultDescription
servicestringyes-Service that should be called in a given mode
service_dataobjectno-Data that should be passed to service call
targetobjectno-Target that should be passed to service call
evaluate_data_as_templatebooleannofalseEnables 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:

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:

Supported repeats types

Following repeats types are supported at this moment:

Predefined selection options

Format of data depends on selected selection_type:

KeyTypeRequiredDefaultDescription
idstring or numberyes-Room's identifier
outlinelistno-List of points forming an outline of a room (e.g. [[25500,25500],[26500,25500],[25500,26500]]
iconobjectno-Icon definition
labelobjectno-Label definition
variablesobjectno-Variables that should be passed to service_call_schema

See this page to check how to easily create outline.

Icon options

KeyTypeRequiredDefaultDescription
namestringyes-An icon to be displayed (mdi)
xnumberyes-X coordinate of an icon (in vacuum's coordinate system)
ynumberyes-Y coordinate of an icon (in vacuum's coordinate system)

Label options

KeyTypeRequiredDefaultDescription
textstringyes-Text to be displayed
xnumberyes-X coordinate of a label (in vacuum's coordinate system)
ynumberyes-Y coordinate of a label (in vacuum's coordinate system)
offset_xnumberno-Offset that should be applied to label in X direction (in pixels)
offset_ynumberno-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:

FAQ

Migrating from v1.x.x

<details> <summary>Configuration with <code>map_image</code></summary> <table> <tr> <th>Old config (<code>v1.x.x</code>)</th><th>New config (<code>v2.x.x)</code></th> </tr> <tr> <td> <pre> 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]] </pre> </td> <td> <pre> 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]] </pre> </td> </tr> </table> </details> <br/> <details> <summary>Configuration with <code>map_camera</code></summary> <table> <tr> <th>Old config (<code>v1.x.x</code>)</th><th>New config (<code>v2.x.x)</code></th> </tr> <tr> <td> <pre> 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]] </pre> </td> <td> <pre> 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]] </pre> </td> </tr> </table> </details>

Translations

Currently, this card contains translations for following languages:

Adding a new language

Special thanks

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

<!-- piotrmachowski_support_links_start -->

Support

If you want to support my work with a donation you can use one of the following platforms:

<table> <tr> <th>Platform</th> <th>Payment methods</th> <th>Link</th> <th>Comment</th> </tr> <tr> <td>Ko-fi</td> <td> <li>PayPal</li> <li>Credit card</li> </td> <td> <a href='https://ko-fi.com/piotrmachowski' target='_blank'><img height='35px' src='https://az743702.vo.msecnd.net/cdn/kofi3.png?v=0' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a> </td> <td> <li>No fees</li> <li>Single or monthly payment</li> </td> </tr> <tr> <td>buycoffee.to</td> <td> <li>BLIK</li> <li>Bank transfer</li> </td> <td> <a href="https://buycoffee.to/piotrmachowski" target="_blank"><img src="https://buycoffee.to/btn/buycoffeeto-btn-primary.svg" height="35px" alt="Postaw mi kawę na buycoffee.to"></a> </td> <td></td> </tr> <tr> <td>PayPal</td> <td> <li>PayPal</li> </td> <td> <a href="https://paypal.me/PiMachowski" target="_blank"><img src="https://www.paypalobjects.com/webstatic/mktg/logo/pp_cc_mark_37x23.jpg" border="0" alt="PayPal Logo" height="35px" style="height: auto !important;width: auto !important;"></a> </td> <td> <li>No fees</li> </td> </tr> <tr> <td>Revolut</td> <td> <li>Revolut</li> <li>Credit Card</li> </td> <td> <a href="https://revolut.me/314ma" target="_blank"><img src="https://www.revolut.com/favicon/android-chrome-192x192.png" height="35px" alt="Revolut"></a> </td> <td> <li>No fees</li> </td> </tr> </table> <!-- piotrmachowski_support_links_end -->