Lovelace Xiaomi Vacuum Map Card 故障排除与解决方案指南

Lovelace Xiaomi Vacuum Map Card 是一款专为智能家居环境设计的地图控制插件，为小米、Roborock、Viomi 等品牌的扫地机器人提供直观的可视化操作界面。本文针对用户在使用过程中可能遇到的九大核心问题，提供系统化的故障诊断流程和解决方案，帮助用户快速恢复卡片功能，实现自动化控制目标。

[地图显示]故障排除：从空白界面到精准定位

问题现象

卡片加载后地图区域显示空白或灰色背景，无任何地图内容呈现，但其他控制元素正常显示。

核心原因

1. 地图源配置错误：未正确设置 map_source 参数或地图源不可访问
2. 校准数据缺失：使用图片地图源时未提供足够的校准点
3. 缓存数据冲突：浏览器缓存了旧的地图数据或配置信息

分步解决方案

步骤1：验证地图源配置

检查卡片配置中的 map_source 部分，确保正确设置了有效的地图来源：

map_source:
  # 摄像头作为地图源（推荐方式）
  camera: camera.xiaomi_cloud_map_extractor
  # 或本地图片作为地图源
  # image: /local/images/vacuum_map.png

[!TIP] 若使用摄像头作为地图源，需确保已安装 Xiaomi Cloud Map Extractor 组件并正常生成地图数据。

步骤2：配置校准数据

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

calibration_source:
  calibration_points:
    - vacuum: {x: 25500, y: 25500}  # 机器人坐标系坐标
      map: {x: 466, y: 1889}         # 图片像素坐标
    - vacuum: {x: 25500, y: 27500}
      map: {x: 466, y: 1689}
    - vacuum: {x: 27500, y: 25500}
      map: {x: 666, y: 1889}

步骤3：清除浏览器缓存

1. 按下 Ctrl+Shift+R (Windows/Linux) 或 Cmd+Shift+R (Mac) 强制刷新页面
2. 或在浏览器设置中清除站点数据，包括缓存和Cookie

验证方法

1. 检查 Home Assistant 日志，确认无地图加载相关错误
2. 访问地图源直接URL（如摄像头实体页面）验证地图是否可正常显示
3. 打开浏览器开发者工具（F12），在网络面板检查地图资源加载状态

[区域选择]故障排除：如何解决无法框选清洁区域问题

问题现象

在地图上拖拽鼠标尝试框选清洁区域时无任何反应，或选择后机器人无响应。

核心原因

1. 地图模式配置不完整：未正确加载区域清洁模板
2. 坐标转换错误：真空坐标与地图坐标映射关系异常
3. 机器人指令接收故障：基础控制服务调用失败

分步解决方案

步骤1：检查地图模式配置

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

map_modes:
  - template: vacuum_clean_zone  # 确保已添加区域清洁模板
    name: 区域清洁
    selection_type: MANUAL_RECTANGLE  # 指定选择类型为矩形区域

步骤2：验证坐标转换

通过坐标转换器工具检查坐标映射是否准确：

[!WARNING] 坐标偏差超过10%会导致区域选择与实际清扫位置不符，需要重新校准

步骤3：测试基础服务调用

通过 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]]  # 格式: [x1,y1,x2,y2,重复次数]

验证方法

1. 在卡片界面尝试框选区域，确认出现蓝色选择框
2. 检查 Home Assistant 服务调用历史，确认指令已发送
3. 观察机器人状态变化，确认其接收到指令并开始移动

[卡片性能]故障排除：如何解决加载缓慢与操作卡顿问题

问题现象

卡片加载时间超过5秒，或在进行缩放、平移操作时出现明显卡顿。

核心原因

1. 地图图片尺寸过大：高分辨率图片增加加载和渲染负担
2. 预定义区域过多：超过10个预定义区域会显著影响性能
3. 浏览器硬件加速未启用：未充分利用设备图形处理能力

分步解决方案

步骤1：优化地图图片

调整地图尺寸并裁剪多余区域：

map_source:
  image: /local/map.png
  crop: {top: 50, bottom: 50, left: 30, right: 30}  # 裁剪边缘空白区域

[!TIP] 建议将地图分辨率控制在1000x1000像素以内以获得最佳性能

步骤2：优化预定义区域

将过多的预定义区域拆分到不同地图模式：

map_modes:
  - template: vacuum_clean_zone_predefined
    name: 客厅区域
    predefined_selections:
      - zones: [[25500,25500,26500,26500]]
        name: 客厅
  - template: vacuum_clean_zone_predefined
    name: 卧室区域
    predefined_selections:
      - zones: [[27500,25500,28500,26500]]
        name: 主卧

步骤3：启用硬件加速

在 Home Assistant 配置中添加前端优化设置：

frontend:
  javascript_version: latest  # 使用最新JavaScript引擎

验证方法

1. 使用浏览器开发者工具的性能面板记录卡片加载时间
2. 观察缩放和平移操作的流畅度，确认无明显卡顿
3. 比较优化前后的加载时间，目标减少50%以上加载时间

[机器人通信]故障排除：解决指令发送后无响应问题

问题现象

在卡片界面发送清洁指令后，机器人无任何反应，状态也未发生变化。

核心原因

1. 真空实体状态异常：机器人实体未正确连接或处于错误状态
2. 平台配置不匹配：选择的 vacuum_platform 与实际设备不匹配
3. 权限或网络问题：Home Assistant 无法与机器人建立通信

分步解决方案

步骤1：检查实体状态

在 Home Assistant 开发者工具中检查真空实体状态：

• 确认实体 vacuum.xiaomi_vacuum 存在且状态正常
• 验证是否能看到 battery_level、status 等属性

步骤2：配置正确平台

根据机器人品牌选择合适的平台：

vacuum_platform: roborock  # Roborock品牌
# 或
# vacuum_platform: xiaomiMiio  # 小米Miio平台
# vacuum_platform: deebot  # Ecovacs Deebot平台

完整平台列表可参考项目中的平台模板文档。

步骤3：测试基础控制

直接调用基础控制服务验证通信：

service: vacuum.start
target:
  entity_id: vacuum.xiaomi_vacuum

验证方法

1. 检查 Home Assistant 日志，确认无通信错误
2. 观察机器人实体状态变化，确认指令已接收
3. 测试多个基础指令（开始、暂停、返回充电座）验证通信链路

[多地图管理]故障排除：如何解决多楼层地图切换失效问题

问题现象

配置多个地图预设后，切换预设时地图未能正确更新，或显示错误的地图内容。

核心原因

1. 预设配置不完整：每个预设缺少必要的地图源或校准配置
2. 校准数据共享冲突：不同地图使用相同的校准数据导致坐标偏差
3. 平台限制：部分机器人平台对多地图支持有限制

分步解决方案

步骤1：正确配置多预设

为每个地图预设单独配置完整参数：

additional_presets:
  - preset_name: 一楼
    entity: vacuum.xiaomi_vacuum
    map_source: {camera: camera.map_floor1}
    calibration_source: {camera: true}  # 单独的校准源
    icon: mdi:floor-plan
  - preset_name: 二楼
    entity: vacuum.xiaomi_vacuum
    map_source: {camera: camera.map_floor2}
    calibration_source: {camera: true}  # 单独的校准源
    icon: mdi:floor-plan

步骤2：验证地图切换逻辑

确保每个预设使用独立的地图源和校准数据，避免共享配置。

[!WARNING] Roborock等部分平台在切换地图后可能需要重新校准，请在切换后确认坐标准确性

步骤3：添加切换反馈

配置切换成功的通知提示：

map_modes:
  - template: preset_selection
    name: 切换地图
    icon: mdi:map-switch

验证方法

1. 切换不同预设，确认地图内容正确更新
2. 在每个地图上执行简单操作（如定位机器人）验证功能正常
3. 检查日志确认切换过程无错误信息

[移动设备适配]故障排除：解决小屏设备界面错乱问题

问题现象

在手机等移动设备上查看卡片时，界面元素重叠、按钮不可点击或地图显示不完整。

核心原因

1. 固定高度设置不当：卡片高度未适配不同屏幕尺寸
2. 触摸操作冲突：单指操作同时触发地图拖动和页面滚动
3. 元素布局未优化：关键控制元素在小屏幕上被遮挡

分步解决方案

步骤1：设置响应式高度

使用相对单位设置卡片高度：

style: |
  ha-card {
    height: 60vh;  # 使用视口高度单位，适配不同屏幕
    overflow: hidden;
  }

步骤2：优化触摸交互

启用双指操作模式避免冲突：

two_finger_pan: true  # 双指拖动地图
map_locked: false     # 允许地图平移缩放

步骤3：调整元素布局

通过 order 参数控制元素显示优先级：

tiles:
  - template: clean_stop
    order: 1  # 优先显示
  - template: fan_speed
    order: 2
  - template: preset_selection
    order: 3

验证方法

1. 在不同尺寸设备上测试界面显示效果
2. 验证触摸操作（缩放、平移、点击）是否流畅
3. 确认所有关键控制元素均可访问

[语言显示]故障排除：解决翻译混乱或未翻译问题

问题现象

卡片界面显示混合语言、部分文本未翻译或翻译不准确。

核心原因

1. 语言配置未明确指定：未在卡片配置中设置正确语言
2. 翻译文件缺失或不完整：对应语言的翻译文件存在缺失
3. 浏览器缓存问题：更新翻译后未清除缓存导致旧文本残留

分步解决方案

步骤1：明确指定语言

在卡片配置中强制设置所需语言：

language: zh  # 强制使用中文
# 或其他支持的语言代码：en, de, fr, es等

步骤2：检查翻译文件完整性

确认项目中存在对应语言的完整翻译文件，如 src/localize/languages/zh.json。

步骤3：清除缓存并刷新

1. 清除浏览器缓存（Ctrl+Shift+R）
2. 重启 Home Assistant 前端服务

[!TIP] 如需贡献翻译，可参考项目中的贡献指南文档

验证方法

1. 检查界面所有文本是否使用指定语言
2. 确认特殊术语（如地图模式名称）翻译准确
3. 测试动态生成的文本（如状态信息）是否正确翻译

[版本升级]故障排除：从v1.x迁移到v2.x后配置失效问题

问题现象

升级到v2.x版本后，原有配置无法正常工作，卡片无法加载或功能异常。

核心原因

1. 配置结构变化：v2.x采用全新的配置结构，与v1.x不兼容
2. 参数名称变更：多个关键参数名称和层级发生变化
3. 模板系统重构：地图模式和操作模板的定义方式完全改变

分步解决方案

步骤1：理解配置结构变化

v1.x旧配置：

map_image: /local/map.png
camera_calibration: true
zones: [[25500,25500,26500,26500]]

v2.x新配置：

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

步骤2：更新地图模式配置

v2.x使用模板化地图模式：

map_modes:
  - template: vacuum_clean_zone  # 手动区域清洁
  - template: vacuum_clean_point  # 定点清洁
  - template: vacuum_clean_predefined  # 预定义区域

步骤3：迁移自定义功能

重新实现v1.x中的自定义功能：

# v1.x自定义按钮
custom_buttons:
  - name: 回充
    service: vacuum.return_to_base
    icon: mdi:home

# v2.x中迁移为tiles
tiles:
  - template: custom_button
    icon: mdi:home
    service: vacuum.return_to_base
    service_data:
      entity_id: vacuum.xiaomi_vacuum

验证方法

1. 检查配置文件无语法错误
2. 确认所有原有功能在新配置下正常工作
3. 测试新增功能（如多地图支持）是否正常

[设备支持]故障排除：如何为非列表机器人添加支持

问题现象

使用的机器人不在支持列表中，无法通过标准配置实现控制功能。

核心原因

1. 平台模板缺失：项目中没有针对该机器人型号的平台模板
2. API接口差异：机器人使用与现有平台不兼容的控制协议
3. 指令格式不同：清洁区域、定点等指令参数格式有差异

分步解决方案

步骤1：尝试通用发送指令平台

使用 send_command 平台通过原始指令控制：

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]]"   # 传递选择的区域坐标

步骤2：自定义服务调用格式

根据机器人API文档调整指令参数格式：

map_modes:
  - template: vacuum_clean_zone
    service_call_schema:
      service: vacuum.send_command
      service_data:
        command: zone_clean
        params:
          - x0: "[[selection.x1]]"
            y0: "[[selection.y1]]"
            x1: "[[selection.x2]]"
            y1: "[[selection.y2]]"
            times: 1

步骤3：创建自定义平台模板

技术用户可创建自定义平台模板文件，放置在 src/model/generators/platform_templates/ 目录下。

验证方法

1. 测试基础移动指令（前进、后退）确认通信正常
2. 验证区域清洁和定点清洁功能是否按预期工作
3. 检查是否有错误日志或异常行为

问题速查表

故障现象	可能原因	解决方案索引
地图空白	地图源配置错误	[地图显示]故障排除
⚠️ 无法框选区域	地图模式配置问题	[区域选择]故障排除
⚡ 卡片加载缓慢	地图尺寸过大	[卡片性能]故障排除
🤖 机器人无响应	实体状态异常	[机器人通信]故障排除
🌍 多地图切换失效	预设配置不完整	[多地图管理]故障排除
📱 移动设备界面错乱	高度设置不当	[移动设备适配]故障排除
🌐 翻译显示异常	语言配置问题	[语言显示]故障排除
🔄 升级后配置失效	版本结构变化	[版本升级]故障排除
🚫 设备不支持	平台模板缺失	[设备支持]故障排除

通过以上系统化的故障排除流程，大部分使用问题都能得到有效解决。如遇到特殊情况，建议先检查项目文档中的详细配置指南，或在社区讨论区搜索类似问题。对于持续存在的问题，可准备详细的配置信息和日志提交issue请求支持。