Lovelace Xiaomi Vacuum Map Card 技术故障排查指南

Lovelace Xiaomi Vacuum Map Card是一款专为Home Assistant设计的地图控制插件，支持小米、Roborock、Viomi等多品牌扫地机器人。本文将通过"问题诊断-解决方案-预防建议"三段式结构，系统梳理使用过程中的核心技术问题及解决策略，帮助用户快速定位并修复各类功能异常。

1. 地图显示异常：从空白到显示的3阶段排查

故障现象：地图界面空白无内容

问题诊断

✅ 检查地图源配置完整性
确保map_source配置包含有效数据源：

map_source:
  camera: camera.xiaomi_cloud_map_extractor  # 摄像头源需配合Xiaomi Cloud Map Extractor组件
  # 或使用图片源
  image: /local/vacuum_map.png

✅ 验证校准数据有效性
使用图片源时必须配置至少3个校准点（地图坐标与实际位置的映射参数）：

calibration_source:
  calibration_points:
    - vacuum: {x: 25500, y: 25500}
      map: {x: 466, y: 1889}

⚠️ 排除前端渲染问题
按Ctrl+Shift+R执行强制刷新，清除浏览器缓存中可能存在的旧地图数据。

解决方案

1. 确认Xiaomi Cloud Map Extractor组件已正确安装并生成地图
2. 使用docs/templates/setup.md中的坐标获取工具重新校准
3. 测试地图源是否可访问：在浏览器中直接打开摄像头URL或图片路径

预防建议

💡 定期清理浏览器缓存，特别是在卡片版本更新后
💡 对地图图片进行预处理，确保分辨率不超过1000x1000像素
💡 保存校准点数据到独立配置文件，便于迁移和恢复

2. 区域清洁功能：选区无响应的底层通信修复

故障现象：框选区域后机器人无动作

问题诊断

✅ 验证地图模式配置
确认map_modes中已包含区域清洁模板：

map_modes:
  - template: vacuum_clean_zone  # 确保此模板存在
    selection_type: MANUAL_RECTANGLE  # 显式指定选择类型

✅ 测试基础指令通信
通过Home Assistant开发者工具发送原始指令：

service: vacuum.send_command
target:
  entity_id: vacuum.xiaomi_vacuum
data:
  command: app_zoned_clean
  params: [[25500,25500,26500,26500,1]]

⚠️ 检查坐标转换精度
使用坐标转换器验证真空坐标与地图坐标的映射关系，偏差应控制在10%以内。

解决方案

1. 重新配置vacuum_platform参数，确保与机器人品牌匹配：

   vacuum_platform: roborock  # 适用于Roborock品牌
   # 或
   vacuum_platform: xiaomiMiio  # 适用于小米Miio协议设备
   

2. 检查服务调用模板是否正确：

   service_call_schema:
     service: vacuum.send_command
     service_data:
       command: app_zoned_clean
       params: "[[selection]]"  # 确保selection变量正确传递
   

预防建议

💡 定期在开发者工具中测试基础服务调用，确认通信链路通畅
💡 避免同时选择超过5个清洁区域，防止指令长度超限
💡 记录不同区域的坐标范围，建立区域坐标参考表

3. 卡片性能优化：解决加载缓慢与操作卡顿

故障现象：卡片加载超时或操作延迟

问题诊断

✅ 检查地图资源大小
通过文件管理工具确认地图图片大小，建议控制在500KB以内。

✅ 优化预定义区域数量
检查predefined_selections配置，区域数量应控制在10个以内：

predefined_selections:
  - name: 客厅
    zones: [[25500,25500,26500,26500]]
  # 建议不超过10个预定义区域

⚠️ 启用前端性能优化
在Home Assistant配置中启用现代JavaScript支持：

frontend:
  javascript_version: latest

解决方案

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

   map_source:
     image: /local/map.png
     crop: {top: 50, bottom: 50, left: 30, right: 30}  # 保留有效区域
   

2. 拆分复杂配置到多个地图模式：

   map_modes:
     - template: vacuum_clean_zone_predefined
       name: 常用区域
       predefined_selections: [客厅, 卧室]
     - template: vacuum_clean_zone_predefined
       name: 其他区域
       predefined_selections: [厨房, 卫生间]
   

预防建议

💡 定期清理地图缓存文件，删除历史版本
💡 使用图片压缩工具预处理地图图片，平衡质量与大小
💡 避免在卡片配置中使用过多动态模板和条件判断

4. 多地图切换功能：预设配置与校准同步方案

故障现象：切换地图后坐标偏移或功能失效

问题诊断

✅ 检查预设配置完整性
每个预设需包含独立的地图源和校准源：

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}

✅ 验证地图切换逻辑
通过卡片UI切换预设，观察URL参数变化是否正确反映当前预设。

⚠️ 检查平台特定限制
部分平台（如Roborock）切换地图后需要重新校准，需在预设切换后执行校准操作。

解决方案

1. 为每个预设配置独立校准点：

   additional_presets:
     - preset_name: 一楼
       calibration_source:
         calibration_points:
           - vacuum: {x: 25500, y: 25500}
             map: {x: 466, y: 1889}
   

2. 使用自动化实现切换后自动校准：

   automation:
     - trigger:
         platform: state
         entity_id: input_select.vacuum_map_preset
       action:
         service: xiaomi_miio.vacuum_calibrate
   

预防建议

💡 为不同楼层/区域建立独立的校准点配置文件
💡 切换地图后等待3-5秒再执行操作，确保校准完成
💡 记录各预设的校准参数，建立校准数据库

5. 移动设备适配：响应式界面配置指南

故障现象：小屏设备显示错乱或操作困难

问题诊断

✅ 检查卡片高度设置
确认卡片高度适合移动设备：

style: |
  ha-card {
    height: 500px;  # 手机建议400-600px
    overflow: hidden;
  }

✅ 启用触摸优化参数
配置适合触摸操作的交互参数：

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

⚠️ 检查元素排列顺序
通过order参数调整关键功能的显示优先级：

tiles:
  - template: start
    order: 1  # 优先显示开始按钮
  - template: pause
    order: 2

解决方案

1. 配置响应式样式：

   style: |
     @media (max-width: 768px) {
       ha-card {
         height: 400px !important;
       }
       .tiles-wrapper {
         flex-wrap: wrap;
       }
     }
   

2. 精简移动视图元素：

   mobile_settings:
     hide_icons: true  # 移动端隐藏部分图标
     simplify_controls: true  # 简化控制界面
   

预防建议

💡 在不同尺寸设备上测试界面布局，建立适配标准
💡 优先保证核心功能（启动、暂停、区域选择）在移动端可用
💡 使用相对单位（如百分比）而非固定像素设置尺寸

问题自愈清单

问题类型	首要排查点	快速验证方法
地图显示异常	map_source配置	直接访问地图源URL
区域选择失效	vacuum_platform设置	开发者工具调用vacuum.send_command
加载性能问题	地图图片大小	检查文件属性中的尺寸和大小
多地图切换问题	预设校准配置	切换预设后观察坐标是否准确
移动适配问题	卡片高度设置	调整高度值测试显示效果

通过系统排查和针对性优化，Lovelace Xiaomi Vacuum Map Card能够提供稳定高效的地图控制体验。建议定期查阅docs/demo_config.yaml获取最新配置示例，保持卡片与Home Assistant版本同步更新。遇到复杂问题时，可提供详细配置和日志信息寻求社区支持。