Home Assistant Ecovacs 集成实战使用ecovacs.raw_get_positions获取扫地机器人与充电座原始位置【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本指南深入讲解 Home Assistant Ecovacs 集成中的ecovacs.raw_get_positions动作它用于一次性取回 Ecovacs 扫地机器人Deebot与充电座充电坞的原始位置响应数据适用于自动化、脚本、模板传感器以及故障排查场景。读完本文你将掌握该动作在 UI 与 YAML 两种模式下的完整调用方式、响应数据结构resp - body - data下的deebotPos与chargePos坐标并能将其接入自定义流程做进一步处理。动作概览ecovacs.raw_get_positions是 Ecovacs 集成 提供的动作之一其核心用途是检索 Ecovacs 扫地机器人及其充电座的原始位置响应。该动作的元信息如下动作名actionecovacs.raw_get_positions所属域domainecovacs描述Retrieves a raw response containing the positions of the charger and the vacuum检索包含充电座与扫地机器人位置的原始响应。与集成内常见的“开始清扫”“回充”等控制类动作不同本动作不产生物理动作只读取数据——它返回的是设备上报的原始坐标响应适合在需要拿到位置明细做自定义处理或排障时使用。在 UI 中调用该动作如果更习惯用图形界面编排自动化与脚本可以按以下步骤完成配置进入设置Settings自动化与场景Automations scenes。打开一个已有的自动化或脚本或者点击创建自动化Create automation创建新自动化Create new automation。如果新建的是自动化需要在When当…时区域添加一个触发器。脚本Script不需要触发器——脚本由其他自动化、仪表盘或其他脚本调用时才运行。在Then do然后执行区域点击添加动作Add action。选择要控制的目标设备。在By target按目标详见下文 动作的目标下选择对应的 Ecovacs 扫地机器人。在该目标展示的动作列表中选择获取原始位置Get raw positions。点击保存Save。UI 中的选项该动作在 UI 中没有额外的选项。也就是说图形界面下你只需要指定目标实体其余全部由 Home Assistant 自动完成。在 YAML 中调用该动作如果你直接编写 YAML或希望精确了解 Home Assistant 在底层做了什么可以参考本节的技术参考。YAML 中调用该动作的方式如下action: | action: ecovacs.raw_get_positions target: entity_id: vacuum.deebot_n8_plus response_variable: ecovacs_positions以上配置会对vacuum.deebot_n8_plus执行ecovacs.raw_get_positions并将返回结果存入响应变量ecovacs_positions供后续步骤引用。YAML 中的选项该动作在 YAML 中除 target目标之外没有额外的选项。可选的response_variable用于存储响应内容便于在后续步骤中继续使用。动作的目标Targets of the action该动作必须指定一个目标target。目标是动作的作用对象可以将动作指向单个实体、设备、区域、楼层或标签Home Assistant 会对该目标下所有匹配的vacuum实体执行动作实体Entity单个指定的vacuum实体例如vacuum.living_room。设备Device属于某台设备的所有vacuum实体。区域Area某个房间/区域内的所有vacuum实体。楼层Floor某个楼层上的所有vacuum实体。标签Label共享某个标签的所有vacuum实体。也可以在同一个动作中混合使用不同的目标类型例如同时把某个具体实体和某个区域都作为目标让动作一次性作用于两者。响应数据结构解析该动作返回的是原始响应其中包含扫地机器人和充电座的位置。需要特别注意的是确切的响应结构取决于扫地机器人的型号与固件版本不同设备返回的字段可能有所差异。响应中的坐标位于resp - body - data路径下典型结构如下vacuum.deebot_n8_plus: ret: ok resp: header: pri: 1 tzm: 480 ts: 1717748487712 ver: 0.0.1 fwVer: 1.2.0 hwVer: 0.1.1 body: code: 0 msg: ok data: deebotPos: x: 1 y: 5 a: 85 invalid: 0 chargePos: - x: 5 y: 9 a: 85 t: 1 invalid: 0 mid: 200465850 id: 5o81 payloadType: j对该响应的关键字段做如下解读路径含义ret请求整体返回状态ok表示成功resp.header协议头信息包含时区分钟偏移tzm、时间戳ts毫秒、协议版本ver、固件版本fwVer、硬件版本hwVerresp.body.code/resp.body.msg响应体状态码与消息0/ok表示正常resp.body.data.deebotPos扫地机器人当前位置坐标resp.body.data.chargePos充电座位置坐标注意是列表结构resp.body.data.mid地图 IDid/payloadType消息标识与载荷类型坐标字段说明x、y位置坐标。a角度用于表示朝向。t类型/标签仅在chargePos中出现。invalid有效性标志0表示坐标有效。deebotPos是单个对象而chargePos是数组以-开头表示列表项这一差异在编写模板提取数据时需要注意。实战将原始坐标接入自动化与模板拿到response_variable后可以在自动化后续步骤或模板中提取并使用这些坐标。例如通过自动化调用该动作并将结果写入日志或模板传感器action: ecovacs.raw_get_positions target: entity_id: vacuum.deebot_n8_plus response_variable: ecovacs_positions随后即可在后续步骤中引用ecovacs_positions中的字段。配合 Template 模板集成 的用法可以将坐标转换为可持久化的传感器状态。例如在模板传感器中读取扫地机器人当前位置template: - sensor: - name: Deebot Position X state: {{ ecovacs_positions[vacuum.deebot_n8_plus][resp][body][data][deebotPos][x] | default(unknown) }}说明由于响应结构依赖型号与固件编写模板时应做好容错例如使用default()、判断字段是否存在避免因个别设备字段差异导致模板报错。若希望稳定获取坐标最可靠的方式是在自动化中显式调用ecovacs.raw_get_positions并通过response_variable承接响应再结合resp.body.data.deebotPos与resp.body.data.chargePos字段编写提取表达式。使用场景与注意事项主要用途需要原始位置数据用于故障排查troubleshooting或自定义处理custom processing时该动作最为有用。例如当怀疑机器人的清扫地图、回充定位出现异常时可以通过该动作一次性获取坐标快照判断invalid标志是否异常、坐标是否超出预期范围。结构不固定响应结构依赖型号与固件在编写自动化解析逻辑时应做好容错避免因个别设备字段差异导致模板报错。目标为 vacuum 实体该动作按vacuum域匹配目标请确保目标选择的是 Ecovacs Deebot 扫地机器人实体如vacuum.deebot_n8_plus。不改变设备状态这是一个只读查询类动作不会启动清扫、不会触发回充也不产生清扫任务它对设备的影响仅是发起一次位置状态查询。相关阅读Ecovacs 集成完整文档包含设备前提条件、提供的实体列表传感器、开关、按钮、事件、地图图片等、真空吸尘器实体的使用寿命属性与错误处理以及自托管Self-hosted配置说明。在该集成文档的 真空吸尘器Vacuum章节 中你可以进一步了解如何通过ecovacs_error事件监听错误、通过error属性排查异常以及如何将组件寿命提取为模板传感器。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考