石头扫地机器人接入 HomeAssistant 的本地集成方案

石头扫地机器人接入 HomeAssistant 的本地集成方案

很多用户在使用 HomeAssistant 时，常遇到需要频繁切换 Roborock 官方 APP 和 HA 界面的困扰。通过引入专为石头扫地机器人设计的本地集成插件，可以让清洁设备真正融入智能家居生态，实现自动化联动控制，同时避免云端依赖带来的延迟或隐私问题。

为什么选择本地集成？

传统的 Xiaomi 集成往往受限于地图请求次数，且部分功能需走云端。这个定制化的本地方案完美解决了上述痛点：

• 无地图请求限制：支持实时地图显示，无需担心配额耗尽。
• 并行使用：可与官方 APP 同时在线，互不干扰。
• 丰富服务：提供底层 API 访问权限，支持更精细的控制逻辑。

环境准备与安装

网络配置要求

在开始之前，请确保你的网络环境满足以下条件，这是本地通信的基础：

• HomeAssistant 实例需在 UDP 58866 端口接收设备广播。
• TCP 58867 端口需开放用于设备控制指令传输。
• 确保 HomeAssistant 服务器与扫地机器人在同一局域网段内。

通过 HACS 安装

推荐使用 HACS（Home Assistant Community Store）进行部署，步骤如下：

1. 打开 HomeAssistant 的 HACS 界面。
2. 进入'自定义仓库'添加项目地址（通常指向 GitHub 上的开源镜像）。
3. 搜索 "Roborock" 并下载安装对应组件。
4. 重启 HomeAssistant 服务使配置生效。

注意：如果使用的是 Docker 部署，请确认容器网络模式已正确映射上述端口。

设备认证与连接

安装完成后，即可在系统设置中添加设备：

1. 进入'设置' → '设备与服务'。
2. 点击'添加集成'，搜索 "Roborock"。
3. 输入你在 Roborock APP 中绑定的用户名。
4. 提交后，系统会向注册邮箱发送验证码。
5. 输入验证码即可完成绑定。

如果在验证过程中遇到超时，尝试刷新浏览器页面或检查邮件垃圾箱。若仍无法连接，建议重启 HA 服务并再次尝试。

核心功能与自动化场景

成功连接后，你可以利用丰富的实体和服务实现深度控制。

基础清洁控制

集成提供了标准的 Vacuum 实体，支持一键启动/停止清扫、暂停任务、回充以及风速调节。对于定点清洁需求，可以直接调用对应的服务指令。

高级服务调用

除了标准实体，该集成还暴露了更多底层服务，适合编写复杂自动化：

• 远程遥控：支持 vacuum_remote_control_start 等指令，可手动操控机器人移动方向。
• 区域管理：通过 vacuum_clean_zone 指定坐标区域，或使用 vacuum_goto 精确导航至特定位置。
• 分段清洁：针对特定房间编号执行清扫任务。

状态监测与维护

传感器数据会被同步到 HA，包括清洁统计（时长、面积）、设备健康度（主刷、滤网寿命）、电池电量及错误代码。此外，还能检测拖布模块是否安装、水箱连接状态及缺水预警。

实用自动化建议

结合这些功能，可以构建多种实用场景：

• 离家自动清扫：当家庭安防系统触发'离家模式'时，自动下发清扫指令。
• 重点区域清洁：结合传感器数据，检测到厨房油污较重时，触发局部清洁。
• ：当滤网寿命低于阈值，自动推送通知提醒更换。