Home Assistant Ecovacs 集成实战：使用 `ecovacs.raw_get_positions` 获取扫地机器人与充电座原始位置-开发者社区

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 扫地机器人及其充电座的原始位置响应。

该动作的元信息如下：

动作名（action）：ecovacs.raw_get_positions
所属域（domain）：ecovacs
描述：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`、硬件版本`hwVer`
`resp.body.code`/`resp.body.msg`	响应体状态码与消息，`0`/`ok`表示正常
`resp.body.data.deebotPos`	扫地机器人当前位置坐标
`resp.body.data.chargePos`	充电座位置坐标（注意是列表结构）
`resp.body.data.mid`	地图 ID
`id`/`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）。
不改变设备状态：这是一个只读查询类动作，不会启动清扫、不会触发回充，也不产生清扫任务；它对设备的影响仅是发起一次位置状态查询。

Home Assistant Ecovacs 集成实战：使用 `ecovacs.raw_get_positions` 获取扫地机器人与充电座原始位置