解决Home Assistant Roborock集成故障的完整指南

问题定位：识别Roborock集成常见故障类型

在智能家居系统中，Roborock扫地机器人集成故障通常表现为三类典型问题，每种问题对应不同的排查方向：

• 设备未发现：Home Assistant界面中无法找到Roborock设备，常见于首次配置或网络环境变化后。此问题可能涉及DHCP（动态主机配置协议，用于自动分配IP地址）服务异常或设备网络隔离。

• 认证失败：提示"Invalid credentials"或验证码无效，主要与账号验证流程相关。核心代码逻辑在[config_flow.py]中实现，涉及邮箱验证、验证码时效性检查等步骤。

• 控制无响应：设备在线但无法执行清洁指令或状态不更新，通常与API通信故障有关。相关处理逻辑可参考[coordinator.py]中的设备状态同步机制。

故障排查决策树

系统分析：从日志到依赖的全面诊断

收集关键日志信息

通过SSH连接Home Assistant主机，执行以下命令获取Roborock相关日志：

grep -i "roborock" /config/home-assistant.log

执行效果：返回包含"roborock"关键词的日志条目，按时间顺序排列最近的交互记录。

常见日志模式及分析：

• RoborockInvalidCode：验证码错误或已过期（有效期通常为5分钟）
• RoborockUrlException：API端点连接失败，可能需要检查[const.py]中的服务器地址配置
• mapFlag相关错误：地图数据解析异常，需验证[vacuum.py]中的地图处理逻辑

注意事项：启用调试日志可获取更详细信息，需在configuration.yaml中添加：

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

验证依赖版本兼容性

Roborock集成依赖特定版本的Python库，需确保：

• python-roborock版本不低于2.47.1
• vacuum-map-parser-roborock版本应为0.1.4

通过以下命令检查当前安装版本：

pip list | grep -E "roborock|vacuum-map-parser"

分步解决：从基础到进阶的修复方案

1. 重建认证连接

当遇到持续认证失败时，需执行完整的认证流程重置：

1. 删除现有Roborock集成（设置 > 设备与服务 > Roborock > 删除）
2. 清除浏览器缓存（避免旧会话Cookie干扰新认证）
3. 重新添加集成：
   • 输入注册邮箱（必须与Roborock APP使用的邮箱一致）
   • 等待验证码短信（通常在60秒内送达）
   • 收到验证码后30秒内完成输入

原理依据：重置流程可清除存储的过期token，重建与Roborock服务器的信任关系，相关实现见[config_flow.py]中的code_login方法。

2. 网络配置优化

对于设备发现问题，可采用以下网络调试步骤：

1. 确认网络归属：登录路由器管理界面，检查Roborock设备与Home Assistant是否在同一子网
2. 手动指定IP：在configuration.yaml中添加静态设备配置：

   roborock:
     username: [e-mail]
     devices:
       - host: 192.168.1.100  # 替换为实际IP
         token: your_device_token  # 从Roborock APP获取
   

3. 验证网络连通性：执行ping测试确认设备可达：

   ping 192.168.1.100  # 替换为设备实际IP
   

检查点：若ping测试失败，需检查防火墙设置或尝试重启路由器

3. 进阶网络抓包分析

当基础排查无效时，可使用tcpdump抓取API通信包：

tcpdump -i any port 443 and host api.roborock.com -w roborock_traffic.pcap

分析方法：使用Wireshark打开捕获文件，过滤"http"流量，检查是否存在：

• TLS握手失败（可能是证书问题）
• HTTP 401/403响应（认证失败）
• 响应超时（网络丢包）

预防优化：构建稳定运行环境

定期维护任务

1. 自动化设备重启：创建每周重启Roborock设备的自动化：

   alias: "每周重启Roborock"
   trigger:
     platform: time_pattern
     week: /1
     hour: 3
     minute: 0
   action:
     service: vacuum.restart
     target:
       entity_id: vacuum.roborock_device
   

2. 依赖版本监控：每月检查[manifest.json]中的依赖声明，执行升级命令：

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

系统级优化建议

• 网络稳定性增强：为Roborock设备配置固定IP地址，避免DHCP地址变更
• 日志监控：设置日志告警，当出现"Roborock"错误时自动通知管理员
• 定期备份：使用Home Assistant的备份功能，保存Roborock集成配置

常见问题速查表

• Q: 验证码从未收到？
  A: 检查垃圾邮件文件夹；确认使用与Roborock APP相同的邮箱；尝试国际短信通道（部分地区需开启）

• Q: 地图加载空白？
  A: 清除浏览器缓存；验证vacuum-map-parser-roborock版本；检查设备是否支持地图功能

• Q: 设备离线但APP可连接？
  A: 检查Home Assistant IP是否在设备允许列表；验证网络子网掩码是否正确；尝试重启Home Assistant服务

• Q: 依赖升级后集成失效？
  A: 回滚到[manifest.json]指定的版本；检查Python版本兼容性（需3.9+）；查看升级日志中的冲突提示

通过以上系统化的排查与优化方案，可有效解决90%以上的Roborock集成问题。对于复杂场景，建议收集完整日志（包含[coordinator.py]中的设备属性信息）并提交社区支持。