石头扫地机器人接入 HomeAssistant 的本地集成方案
很多用户在使用 HomeAssistant 时,常遇到需要频繁切换 Roborock 官方 APP 和 HA 界面的困扰。通过引入专为石头扫地机器人设计的本地集成插件,可以让清洁设备真正融入智能家居生态,实现自动化联动控制,同时避免云端依赖带来的延迟或隐私问题。
为什么选择本地集成?
传统的 Xiaomi 集成往往受限于地图请求次数,且部分功能需走云端。这个定制化的本地方案完美解决了上述痛点:
- 无地图请求限制:支持实时地图显示,无需担心配额耗尽。
- 并行使用:可与官方 APP 同时在线,互不干扰。
- 丰富服务:提供底层 API 访问权限,支持更精细的控制逻辑。
环境准备与安装
网络配置要求
在开始之前,请确保你的网络环境满足以下条件,这是本地通信的基础:
- HomeAssistant 实例需在 UDP 58866 端口接收设备广播。
- TCP 58867 端口需开放用于设备控制指令传输。
- 确保 HomeAssistant 服务器与扫地机器人在同一局域网段内。
通过 HACS 安装
推荐使用 HACS(Home Assistant Community Store)进行部署,步骤如下:
- 打开 HomeAssistant 的 HACS 界面。
- 进入'自定义仓库'添加项目地址(通常指向 GitHub 上的开源镜像)。
- 搜索 "Roborock" 并下载安装对应组件。
- 重启 HomeAssistant 服务使配置生效。
注意:如果使用的是 Docker 部署,请确认容器网络模式已正确映射上述端口。
设备认证与连接
安装完成后,即可在系统设置中添加设备:
- 进入'设置' → '设备与服务'。
- 点击'添加集成',搜索 "Roborock"。
- 输入你在 Roborock APP 中绑定的用户名。
- 提交后,系统会向注册邮箱发送验证码。
- 输入验证码即可完成绑定。
如果在验证过程中遇到超时,尝试刷新浏览器页面或检查邮件垃圾箱。若仍无法连接,建议重启 HA 服务并再次尝试。
核心功能与自动化场景
成功连接后,你可以利用丰富的实体和服务实现深度控制。
基础清洁控制
集成提供了标准的 Vacuum 实体,支持一键启动/停止清扫、暂停任务、回充以及风速调节。对于定点清洁需求,可以直接调用对应的服务指令。
高级服务调用
除了标准实体,该集成还暴露了更多底层服务,适合编写复杂自动化:
- 远程遥控:支持
vacuum_remote_control_start等指令,可手动操控机器人移动方向。 - 区域管理:通过
vacuum_clean_zone指定坐标区域,或使用vacuum_goto精确导航至特定位置。 - 分段清洁:针对特定房间编号执行清扫任务。
状态监测与维护
传感器数据会被同步到 HA,包括清洁统计(时长、面积)、设备健康度(主刷、滤网寿命)、电池电量及错误代码。此外,还能检测拖布模块是否安装、水箱连接状态及缺水预警。
实用自动化建议
结合这些功能,可以构建多种实用场景:
- 离家自动清扫:当家庭安防系统触发'离家模式'时,自动下发清扫指令。
- 重点区域清洁:结合传感器数据,检测到厨房油污较重时,触发局部清洁。
- :当滤网寿命低于阈值,自动推送通知提醒更换。

