在Xiaomi Vacuum Map Card中实现Roborock静态地图支持的技术方案

背景介绍

Xiaomi Vacuum Map Card是Home Assistant中一款流行的扫地机器人地图卡片插件。随着Roborock官方集成的更新，地图显示方式从实时摄像头视图转变为静态图像更新，这导致用户在使用过程中遇到了一些兼容性问题。

核心问题分析

原插件设计主要针对摄像头视图进行优化，而Roborock新版本集成提供了静态图像作为地图源。这种变化带来了两个主要技术挑战：

1. 校准机制不兼容：静态图像需要手动校准，而原插件依赖摄像头的自动校准功能
2. 命令接口差异：Roborock官方集成与第三方集成的API调用方式不同

解决方案详解

静态图像校准方法

要实现静态图像的正确显示和操作，需要手动配置校准点。具体步骤如下：

1. 首先安装Roborock自定义集成，获取初始校准点数据
2. 通过开发者工具中的"States"界面查找"camera.roborock"实体，获取其中的calibration_points数据
3. 将这些校准点转换为卡片配置中的格式

示例配置片段：

calibration_source:
  calibration_points:
    - vacuum:
        x: 25500
        y: 25500
      map:
        x: 266
        y: 336
    - vacuum:
        x: 26500
        y: 25500
      map:
        x: 286
        y: 336
    - vacuum:
        x: 25500
        y: 26500
      map:
        x: 266
        y: 316

坐标系统理解

Roborock设备使用的坐标系统基于毫米单位，通过仿射变换将图像像素坐标转换为设备理解的物理坐标。理解这一点对于手动调整房间图标位置非常重要：

• vacuum坐标：设备理解的物理坐标，单位毫米
• map坐标：图像上的像素坐标

命令接口适配

由于Roborock官方集成使用不同的命令接口，需要调整卡片配置：

1. 将vacuum_platform设置为"send_command"
2. 确保房间ID使用数字而非字符串格式
3. 添加必要的模板配置

关键配置示例：

vacuum_platform: send_command
map_modes:
  - template: vacuum_clean_segment
    id_type: number
    predefined_selections:
      - id: 16
        comment: 走廊
        icon:
          name: mdi:walk
          x: 23100
          y: 34200
  - template: vacuum_clean_zone
  - template: vacuum_goto

常见问题解决

1. 房间清洁不工作：确保ID使用数字格式而非字符串，添加id_type: number配置
2. 图标位置不正确：检查校准点配置，可能需要微调map坐标
3. 命令执行失败：确认vacuum_platform设置正确，并检查服务调用参数格式

最佳实践建议

1. 先使用自定义集成完成初始配置，再切换回官方集成
2. 备份完整的卡片配置，避免重复工作
3. 使用开发者工具监控服务调用，便于调试
4. 对于复杂地图，可分区域逐步校准

技术展望

随着Roborock集成的持续发展，未来可能会提供更完善的地图校准支持。目前的手动方案虽然需要一定技术门槛，但能够实现完整的控制功能。社区开发者正在与核心团队合作，推动更优雅的解决方案。

通过本文介绍的方法，用户可以在保持Roborock官方集成优势的同时，继续使用Xiaomi Vacuum Map Card提供的丰富功能，实现静态地图的完美支持。