Lovelace Xiaomi Vacuum Map Card 故障排除指南

2026-04-14 08:28:26作者：幸俭卉

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://gitcode.com/gh_mirrors/lo/lovelace-xiaomi-vacuum-map-card

Lovelace Xiaomi Vacuum Map Card 是一款功能强大的 Home Assistant 插件，为小米、Roborock、Viomi 等品牌的扫地机器人提供直观的地图控制界面。本文将以故障诊断指南的形式，帮助用户解决使用过程中遇到的各类技术问题，确保充分发挥卡片的强大功能。

[地图显示] 界面空白无地图：配置验证方案

问题现象

卡片加载后只显示空白区域或灰色背景，没有任何地图图像显示，可能伴随浏览器控制台报错。

核心原因

地图显示问题通常源于三个关键环节：地图源配置错误、校准数据缺失或不正确、浏览器缓存干扰。这三个因素形成一个串联关系，任何一环出现问题都会导致地图无法正常显示。

解决方案

检查地图源配置完整性
- 若使用摄像头作为地图源，确保 map_source 配置中正确设置 camera 参数：
```
map_source:
  camera: camera.xiaomi_cloud_map_extractor  # 摄像头实体ID
```
- 若使用本地图片作为地图源，需正确配置 image 参数：
```
map_source:
  image: /local/vacuum_map.png  # 本地图片路径
```

验证校准数据有效性

使用图片地图源时，必须提供至少3个校准点建立坐标映射：

calibration_source:
  calibration_points:
    # 格式: 机器人坐标 -> 地图像素坐标
    - vacuum: {x: 25500, y: 25500}  # 机器人实际坐标
      map: {x: 466, y: 1889}        # 对应地图上的像素位置
    - vacuum: {x: 27500, y: 25500}
      map: {x: 666, y: 1889}
    - vacuum: {x: 25500, y: 27500}
      map: {x: 466, y: 2089}

清除浏览器缓存
- 按 Ctrl+Shift+R (Windows/Linux) 或 Cmd+Shift+R (Mac) 强制刷新页面
- 若问题持续，尝试使用隐私模式打开以排除缓存影响

技术背景：地图显示依赖于真空机器人坐标系统与地图图像像素坐标的精确映射。校准点通过建立两者之间的数学转换关系，确保用户在地图上的操作能准确转换为机器人可理解的指令。

验证方法

检查 Home Assistant 日志，确认无地图相关错误信息
在浏览器开发者工具（F12）的 Network 标签中，验证地图资源是否成功加载
临时切换地图源类型（摄像头→图片或反之），测试是否能正常显示

[指令发送] 机器人无响应：通信链路修复

问题现象

在卡片界面执行清扫、定点等操作后，机器人无任何反应，也没有错误提示。

核心原因

指令无响应是一个多环节问题，可能原因包括：实体状态异常→平台配置错误→服务调用失败，形成一个递进关系，需要按顺序排查。

解决方案

确认实体状态正常
- 进入 Home Assistant 开发者工具 → 状态页面
- 查找并检查真空实体（如 vacuum.xiaomi_vacuum）的状态
- 确保实体状态为 idle 或 docked，且包含 battery_level 等属性

验证平台配置正确性

根据机器人品牌选择正确的 vacuum_platform：

# Roborock 机器人
vacuum_platform: roborock

# 小米Miio协议机器人
vacuum_platform: xiaomiMiio

# 通用发送指令模式
vacuum_platform: send_command

完整平台列表参考 docs/templates/Roborock.md

测试基础服务调用

在开发者工具 → 服务页面，直接调用基础服务：

service: vacuum.start
target:
  entity_id: vacuum.xiaomi_vacuum  # 替换为你的实体ID

注意事项：若直接调用服务也无响应，说明问题可能出在机器人集成而非地图卡片，建议先排查机器人与 Home Assistant 的连接。

验证方法

检查 Home Assistant 日志中是否有与机器人通信相关的错误

使用 vacuum.send_command 服务发送测试指令：

service: vacuum.send_command
target:
  entity_id: vacuum.xiaomi_vacuum
data:
  command: app_zoned_clean
  params: [[25500,25500,26500,26500,1]]  # 测试区域坐标

观察机器人是否执行指定的区域清扫任务

[区域选择] 无法框选清洁区域：交互功能修复

问题现象

在地图界面尝试拖拽框选区域时，鼠标操作无反应或无法形成选择框，或选择后点击执行无动作。

核心原因

区域选择功能依赖于正确的地图模式配置、精确的坐标校准和完整的服务调用链。这三个要素形成一个依赖关系：模式配置是基础，坐标校准是精度保障，服务调用是最终执行通道。

解决方案

配置正确的地图模式

确保 map_modes 中包含区域清洁模板：

map_modes:
  - template: vacuum_clean_zone  # 基础区域清洁模板
    name: 区域清洁              # 显示名称
    icon: mdi:select-drag        # 显示图标
    selection_type: MANUAL_RECTANGLE  # 选择类型：手动矩形

验证坐标转换准确性
- 使用坐标转换器工具验证映射关系（src/model/map_objects/coordinates-converter.ts）
- 检查校准点是否覆盖地图主要区域，避免仅集中在一个角落

检查服务调用配置

确认区域清洁对应的服务调用正确：

map_modes:
  - template: vacuum_clean_zone
    service_call_schema:
      service: vacuum.send_command
      service_data:
        command: app_zoned_clean  # 机器人支持的区域清洁指令
        params: "[[selection]]"   # 选择区域的坐标参数

排查流程：先确认地图模式已正确加载（界面应有对应图标）→ 测试选择功能是否工作 → 检查选择后服务调用是否触发 → 验证参数是否正确传递

验证方法

在地图界面切换到区域清洁模式，确认鼠标变为选择状态
尝试框选一个小区域，观察是否能形成蓝色选择框
点击执行按钮后，检查 Home Assistant 服务日志，确认服务调用已触发

[性能优化] 卡片加载缓慢：界面响应提速方案

问题现象

卡片加载时间超过5秒，或操作时出现明显卡顿、延迟，影响用户体验。

核心原因

性能问题通常源于三个方面：地图资源过大导致加载缓慢、界面元素过多增加渲染负担、浏览器未启用硬件加速影响交互流畅度。

解决方案

优化地图资源

调整地图分辨率至1000x1000像素以内

使用 crop 参数裁剪地图多余区域：

map_source:
  image: /local/map.png
  crop: 
    top: 50    # 从顶部裁剪50像素
    bottom: 50 # 从底部裁剪50像素
    left: 30   # 从左侧裁剪30像素
    right: 30  # 从右侧裁剪30像素

精简界面元素

限制 predefined_selections 中预定义区域数量不超过10个：

predefined_selections:
  - name: 客厅
    coordinates: [[25500,25500,26500,26500]]
  # 控制总数量在10个以内，过多会影响性能

禁用不常用的地图模式，减少界面元素

启用前端优化
- 在 Home Assistant 配置中启用最新 JavaScript 版本：
```
frontend:
  javascript_version: latest  # 启用现代JavaScript特性
```

技术背景：浏览器对大型图像的渲染和交互需要消耗较多内存和CPU资源。通过裁剪和降低分辨率，可以显著减少图像数据量，提升加载速度和交互流畅度。

验证方法

使用浏览器开发者工具的 Performance 标签录制卡片加载过程
比较优化前后的加载时间，目标控制在3秒以内
测试地图缩放、平移操作，确认无明显卡顿

[多地图管理] 预设切换失效：地图配置优化

问题现象

配置多个地图预设（如不同楼层）后，切换预设时地图不更新或显示错误。

核心原因

多地图切换需要每个预设包含完整的地图源和校准数据，且部分机器人平台需要额外的地图切换指令支持。预设之间的独立性和平台兼容性是关键影响因素。

解决方案

配置完整的预设参数

每个预设必须包含独立的地图源和校准配置：

additional_presets:
  - preset_name: 一楼
    entity: vacuum.xiaomi_vacuum
    map_source: 
      camera: camera.map_floor1  # 一楼地图摄像头
    calibration_source: 
      camera: true  # 使用摄像头提供的校准数据
    
  - preset_name: 二楼
    entity: vacuum.xiaomi_vacuum
    map_source: 
      camera: camera.map_floor2  # 二楼地图摄像头
    calibration_source: 
      camera: true  # 每个预设需单独校准

处理平台特定要求

Roborock 等部分平台需要发送地图切换指令：

additional_presets:
  - preset_name: 一楼
    # 其他配置...
    service_call_on_preset_change:
      service: vacuum.send_command
      service_data:
        command: load_multi_map
        params: 1  # 地图编号

验证预设切换逻辑
- 确保预设切换按钮在界面上可见且可点击
- 检查是否有冲突的预设名称或配置

注意事项：部分机器人型号不支持多地图功能，即使在卡片中配置了多个预设，实际也无法切换机器人内部地图。请先查阅机器人官方文档确认支持情况。

验证方法

点击界面上的预设切换按钮，观察地图是否正确更新
在不同预设下执行简单操作（如移动机器人），确认坐标是否正确映射
检查 Home Assistant 日志，确认预设切换时无错误发生

[移动适配] 小屏设备界面错乱：响应式布局调整

问题现象

在手机等小屏幕设备上，卡片界面元素重叠、按钮无法点击或地图显示不完整。

核心原因

移动设备适配问题主要源于固定尺寸设置、触摸交互支持不足和元素排列逻辑在小屏幕上的失效。

解决方案

设置自适应卡片高度

style: |
  ha-card {
    height: 500px;  # 根据设备屏幕调整，建议在400-600px范围
    overflow: hidden;  # 防止内容溢出
  }

启用触摸优化选项

two_finger_pan: true    # 启用双指拖动地图
map_locked: false       # 允许地图平移和缩放
touch_controls: true    # 优化触摸交互体验

调整元素布局顺序

tiles:
  - template: status
  - template: start
  - template: pause
  # 重要功能放在前面，确保在小屏幕上优先显示

设计原则：移动设备适配应遵循"重要功能优先"原则，确保核心操作（如开始清扫、选择区域）在小屏幕上仍能便捷访问。

验证方法

使用不同尺寸的移动设备或浏览器开发者工具的设备模拟功能测试
检查所有关键按钮是否可点击，无重叠区域
测试地图缩放、平移等触摸操作是否流畅

[版本迁移] v2.x配置失效：平滑升级指南

问题现象

从 v1.x 版本升级到 v2.x 后，原有配置无法工作，卡片显示异常或功能缺失。

核心原因

v2.x 版本引入了全新的配置结构，将地图源、校准和操作模式分离为独立配置块，与 v1.x 的扁平结构不兼容。

解决方案

理解配置结构变化

v1.x 旧配置结构：

# v1.x 旧配置
map_image: /local/map.png
camera_calibration: true
zones: [[25500,25500,26500,26500]]

v2.x 新配置结构：

# v2.x 新配置
map_source:
  image: /local/map.png  # 替代原map_image
calibration_source:
  camera: true  # 替代原camera_calibration
map_modes:
  - template: vacuum_clean_zone_predefined
    predefined_selections:
      - zones: [[25500,25500,26500,26500]]  # 替代原zones

迁移关键配置项
- 将原 map_image 迁移到 map_source.image
- 将原 camera_calibration 迁移到 calibration_source.camera
- 将原 zones、rooms 迁移到对应 map_modes 下的 predefined_selections

更新模板引用

v2.x 使用 template 系统替代原有的功能标志：

# v2.x 模板使用方式
map_modes:
  - template: vacuum_clean_zone      # 区域清洁
  - template: vacuum_clean_room      # 房间清洁
  - template: vacuum_goto            # 定点移动

迁移步骤：建议先备份原有配置 → 创建新的 v2.x 配置 → 逐步迁移功能 → 测试验证，而非直接修改旧配置。

验证方法

检查 Home Assistant 日志，确认无配置解析错误
验证所有原有功能是否在新配置下正常工作
测试新增功能（如多地图支持、自定义模板）是否可用

[平台支持] 机器人型号不兼容：扩展适配方案

问题现象

使用的机器人不在支持列表中，或选择平台后功能受限。

核心原因

不同品牌和型号的机器人使用不同的通信协议和指令集，卡片需要特定的适配代码才能支持其全部功能。

解决方案

尝试通用发送指令平台

vacuum_platform: send_command
map_modes:
  - template: vacuum_clean_zone
    service_call_schema:
      service: vacuum.send_command
      service_data:
        command: app_zoned_clean  # 机器人支持的区域清洁指令
        params: "[[selection]]"   # 将选择区域转换为参数

查找社区适配模板
- 检查 docs/templates/ 目录下是否有适用于你的机器人的模板
- 常见第三方平台模板包括：
  - docs/templates/hypferValetudo.md (Valetudo系统)
  - docs/templates/tasshackDreameVacuum.md (追觅机器人)
  - docs/templates/neato.md (Neato机器人)
自定义平台开发
- 技术用户可参考 CONTRIBUTING.md 中的平台开发指南
- 创建自定义平台模板，实现机器人特定指令的转换和发送