解决Home Assistant Roborock集成故障：从报错到稳定运行的完整指南

问题自查清单

请根据以下症状快速定位问题类型（可多选）：

• □ 集成页面显示"未找到设备"
• □ 设备状态显示"离线"但APP可正常控制
• □ 地图加载失败或显示空白
• □ 控制指令无响应（如启动/暂停清洁）
• □ 日志中出现"认证失败"相关错误
• □ 设备属性（如电池电量）不更新

一、问题定位：精准识别故障类型

1.1 集成状态诊断

现象识别：在Home Assistant的"设置 > 设备与服务"页面中，Roborock集成显示"已配置"但设备状态异常。

工具检测：

1. 进入集成详情页面查看设备连接状态
2. 检查设备实体是否存在于"开发者工具 > 状态"页面

解决方案：

• 若设备实体缺失，需重新加载集成
• 若状态显示"未知"，检查设备是否已开机并联网
• 难度指数：★☆☆☆☆ | 预计耗时：3分钟

[!NOTE] 确保Roborock设备固件已更新至最新版本，旧版本固件可能存在API兼容性问题。

验证步骤：刷新集成页面，确认设备状态变为"已连接"。

1.2 错误日志分析

现象识别：系统日志中出现Roborock相关错误信息，如认证失败、连接超时等。

工具检测：

1. 启用调试日志：

logger:
  logs:
    homeassistant.components.roborock: debug
    roborock: debug

2. 重启Home Assistant后查看日志文件

解决方案：

• 搜索关键词"roborock"筛选相关日志
• 记录错误代码和时间戳以便进一步分析
• 难度指数：★★☆☆☆ | 预计耗时：5分钟

验证步骤：确认日志中是否有明确的错误类型提示，如"RoborockInvalidCode"或"RoborockUrlException"。

二、环境诊断：排查系统与网络因素

2.1 网络环境验证

现象识别：设备在APP中正常工作，但Home Assistant无法连接。

工具检测：

1. 确认设备与Home Assistant在同一局域网
2. 检查路由器防火墙设置，确保端口未被阻止

解决方案：

• 为Roborock设备分配固定IP（通过路由器DHCP设置）
• 配置示例：

# configuration.yaml
roborock:
  username: [e-mail]
  devices:
    - host: 192.168.1.100  # 替换为设备实际IP
      token: your_device_token

• 难度指数：★★☆☆☆ | 预计耗时：8分钟

[!NOTE] 国内用户需确保Home Assistant可访问Roborock服务器，必要时配置网络代理。

验证步骤：使用ping命令测试Home Assistant到设备IP的连通性。

2.2 依赖版本检查

现象识别：集成配置成功但功能异常，如地图不加载或控制无响应。

工具检测：

1. 查看Roborock集成的依赖要求：

依赖包	最低要求	推荐版本	检查命令
python-roborock	2.40.0	2.47.1	pip show python-roborock
vacuum-map-parser-roborock	0.1.0	0.1.4	pip show vacuum-map-parser-roborock

解决方案：

• 更新依赖包：

pip install --upgrade python-roborock vacuum-map-parser-roborock

• 难度指数：★☆☆☆☆ | 预计耗时：5分钟

验证步骤：重启Home Assistant后检查依赖版本是否符合要求。

三、深度修复：解决核心技术问题

3.1 认证流程重建

现象识别：反复出现"验证码无效"或"认证超时"错误。

工具检测：

1. 检查Home Assistant日志中的认证流程记录
2. 确认Roborock APP中账号状态正常

解决方案：

1. 删除现有Roborock集成
2. 清除浏览器缓存（避免旧会话干扰）
3. 重新添加集成，确保在收到验证码后30秒内完成输入
4. 难度指数：★★★☆☆ | 预计耗时：10分钟

[!NOTE] API认证流程类似银行ATM取款验证：需要账号密码（邮箱）+动态验证码（短信）双重验证，超时或错误输入都会导致认证失败。

验证步骤：成功添加后，集成页面应显示设备列表和状态信息。

3.2 配置参数优化

现象识别：设备连接成功但部分功能异常，如无法获取地图或控制失败。

工具检测：

1. 检查配置文件完整性
2. 验证设备token有效性

解决方案：

• 配置文件优化示例：

roborock:
  username: [e-mail]
  password: your_password
  country: cn  # 【适用于国内用户】
  devices:
    - host: 192.168.1.100
      token: your_device_token
      model: S7  # 指定设备型号

• 难度指数：★★☆☆☆ | 预计耗时：7分钟

验证步骤：重启集成后检查是否所有功能恢复正常。

四、预防机制：长期稳定运行保障

4.1 自动化维护任务

现象识别：设备运行一段时间后出现连接中断或功能退化。

工具检测：

1. 查看设备运行日志
2. 分析连接中断规律

解决方案：

• 创建定期维护自动化：

# 每周重启Roborock设备
alias: "维护：每周重启Roborock"
trigger:
  platform: time_pattern
  week: /1
  day: mon
  hour: 3
  minute: 0
action:
  - service: vacuum.stop
    target:
      entity_id: vacuum.roborock_s7
  - delay: "00:01:00"
  - service: vacuum.start
    target:
      entity_id: vacuum.roborock_s7

• 难度指数：★★★☆☆ | 预计耗时：15分钟

验证步骤：检查自动化历史记录，确认任务正常执行。

4.2 版本兼容性管理

现象识别：Home Assistant更新后Roborock集成失效。

工具检测：

1. 查看Home Assistant更新日志
2. 检查Roborock集成的版本兼容性公告

解决方案：

• 建立版本更新 checklist：
  1. 更新前备份配置文件
  2. 查看集成最新兼容性信息
  3. 分阶段更新（先更新依赖，再更新Home Assistant）
• 难度指数：★★★★☆ | 预计耗时：20分钟

验证步骤：更新完成后，确认所有功能正常工作。

问题速查表

错误类型	解决方案
RoborockInvalidCode	重新获取验证码并在30秒内完成输入
RoborockUrlException	检查网络连接或配置国内服务器地址
mapFlag 错误	更新vacuum-map-parser-roborock至0.1.4+
network_info.mac缺失	确认设备WiFi连接正常，重启路由器
RoborockAccountDoesNotExist	使用Roborock APP注册的邮箱重新配置
设备离线但APP正常	检查IP地址是否正确或配置静态IP

官方资源

• 文档：Home Assistant官方文档Roborock集成章节
• 社区：Home Assistant论坛"roborock"标签
• 源码：Roborock集成组件源码目录

通过以上系统化的诊断和修复流程，大多数Roborock集成问题都能得到有效解决。对于复杂场景，建议收集详细日志和设备信息后寻求社区支持。

图1：Home Assistant集成页面展示了包括Roborock在内的多种设备集成选项

图2：Home Assistant状态页面显示了设备控制界面和家庭地图