Home Assistant ISY994 集成：使用 isy994.get_zwave_parameter 动作读取 Z-Wave 设备参数
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
本文围绕 Home Assistant 官方文档中 isy994.get_zwave_parameter 动作文档 展开，完整讲解如何通过 ISY/IoX 控制器向 Z-Wave 设备发起参数读取请求，以及如何理解返回值、配置 UI 与 YAML 两种调用方式、正确选择动作目标（Targets），并结合仓库中 Universal Devices ISY/IoX 集成文档 与其姊妹动作 isy994.set_zwave_parameter 补充底层原理与实战要点。读完本文，你将能独立编写一条"读取 Z-Wave 参数"的自动化或脚本，并能利用返回的ZW#实体属性做进一步判断或联动。
动作概述：通过 ISY 查询 Z-Wave 设备参数
Z-Wave 设备的许多行为（如报告间隔、LED 指示、双击行为等）由编号化的配置参数控制。Home Assistant 的isy994集成本身并不直接暴露这些底层参数，而是将查询任务委托给 ISY/IoX 控制器完成。isy994.get_zwave_parameter动作正是为此设计：
With this action, you can request a Z-Wave device parameter through the ISY. The parameter value is returned as an entity attribute named
ZW#, where#is the parameter number.
即：
- 发起方：Home Assistant（通过动作调用）；
- 执行方：ISY/IoX 控制器（向物理 Z-Wave 节点发送读取指令）；
- 返回值：以目标实体的属性（attribute）
ZW#形式呈现，#即所查询的参数编号。例如查询参数 8，结果会出现在实体的ZW8属性中。
该动作属于isy994域，文档中标注的related_actions为 isy994.set_zwave_parameter，二者构成"读取 / 写入"一对完整能力：get负责把设备当前参数读回 Home Assistant，set负责把新值写回设备并同样返回ZW#属性。
适用前提
根据 Universal Devices ISY/IoX 集成文档，isy994是一个ha_integration_type: hub类型的核心集成分（ha_release: 0.28，支持配置流、SSDP 与 DHCP 发现），适用于：
- 旧款 ISY994 硬件家族；
- 当前 ISY-on-Anything（IoX）硬件，如 eisy、Polisy；
- 控制器下接入的 Insteon、X10、Z-Wave 与 Zigbee/Matter 设备。
动作文档明确要求：目标实体必须是 ISY 的 Z-Wave 节点（"The entity must be an ISY Z-Wave node."）。也就是说，只有由该集成导入的 Z-Wave 实体（如switch.garage_door）才能作为本动作的查询对象，普通非 Z-Wave 实体（Insteon、Zigbee 等）不适用。参数编号的具体含义由设备厂商定义，需要查阅对应 Z-Wave 设备的参数表（Parameter Table）确认每个编号对应的功能。
在 UI 中创建自动化或脚本
按官方动作文档，在 Home Assistant 界面中配置该动作的步骤如下：
- 进入设置（Settings）> 自动化与场景（Automations & scenes）；
- 打开一个已有的自动化或脚本，或选择创建自动化（Create automation）> 创建新自动化（Create new automation）；
- 如果是新建自动化，在When（当...时）部分添加一个触发器；脚本不需要触发器，它们由其他东西调用时运行；
- 在Then do（则执行）部分选择添加动作（Add action）；
- 选择要控制的对象：在By target（按目标，见下文 Targets 部分）下选择要查询的 ISY Z-Wave 实体；
- 从该目标可用的动作列表中选择ISY: Get Z-Wave parameter；
- 在Parameter（参数）字段中输入要读取的参数编号；
- 点击保存（Save）。
UI 中的选项
UI 中本动作只暴露一个字段：
| 字段 | 说明 |
|---|---|
| Parameter | 要从设备读取的参数编号（The parameter number to retrieve from the device） |
界面上没有可选填的参数值或大小字段——因为"读取"只需告诉设备"读几号参数"，无需像 set 动作 那样额外提供value（要写入的值）与size（参数大小，1、2 或 4 字节）。
在 YAML 中使用动作
在 YAML 配置（自动化actions或脚本sequence）中，动作以isy994.get_zwave_parameter引用。官方文档给出的基础示例如下：
action: isy994.get_zwave_parameter target: entity_id: switch.garage_door data: parameter: 8该示例向switch.garage_door这个 Z-Wave 设备请求参数 8。
放在完整自动化中的形态如下（组合触发器与后续动作，便于理解实际调用场景）：
automation: - alias: "Read Z-Wave parameter 8 on garage door at startup" triggers: - trigger: homeassistant event: start actions: - action: isy994.get_zwave_parameter target: entity_id: switch.garage_door data: parameter: 8YAML 选项参数表
依据 isy994.get_zwave_parameter 动作文档 中的options_yaml定义：
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
parameter | 是 | integer（整数） | 要从设备读取的参数编号 |
该表与 UI 字段完全对应：唯一的必填参数就是parameter，类型为整数。与写入侧的差异值得注意——isy994.set_zwave_parameter 需要三个必填参数（parameter、value、size），其中size只能是 1、2 或 4（字节）；读取侧只需parameter，因为返回值的字节宽度由设备决定，动作会自动以ZW#属性回传。
理解返回值：ZW#实体属性
动作文档的核心语义是：参数值以名为ZW#的实体属性返回，#为参数编号。例如请求参数 8 后，目标实体switch.garage_door上会出现属性ZW8，其值即设备返回的参数 8 的当前值。
在自动化中可以利用该属性做条件判断或状态展示，例如用模板读取：
action: notify.mobile_app_phone data: message: >- 车库门设备参数 8 当前值为 {{ state_attr('switch.garage_door', 'ZW8') }}需要说明的是：ZW#属性是异步由设备回报更新的，属性出现的时机取决于 ISY 返回查询结果的速度；在动作执行后立即读取模板可能拿到旧值，实践中常配合延时、事件或状态变更触发器使用。这是从动作"请求—返回"语义与属性命名规则推断出的使用要点，具体时序以你的 ISY 与设备表现为准。
由于该集成还提供了写入侧动作，读取与写入常组合成"先读后写、读回校验"的工作流：先用get_zwave_parameter确认当前值，再用set_zwave_parameter写入新值（新值同样会回写到ZW#属性），从而在 Home Assistant 中形成可观测、可审计的参数管理闭环。
动作目标（Targets）详解
isy994.get_zwave_parameter要求必须指定目标（target），目标即动作的作用对象。你可以把动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对目标背后每一个匹配的 ISY 实体执行动作。官方文档列出了五种目标类型：
- 实体（Entity）：一个具体的 ISY Z-Wave 实体，如
switch.garage_door； - 设备（Device）：属于某台设备的所有 ISY Z-Wave 实体；
- 区域（Area）：某个房间/区域内的所有 ISY Z-Wave 实体；
- 楼层（Floor）：某个楼层上的所有 ISY Z-Wave 实体；
- 标签（Label）：共享某个标签的所有 ISY Z-Wave 实体。
你还可以在同一个动作中混用不同类型的目标，例如同时添加一个具体实体和一个区域，让动作一次性对两者执行：
action: isy994.get_zwave_parameter target: entity_id: switch.garage_door area_id: garage data: parameter: 8注意：无论目标如何扩展，其背后的每个实体都必须是 ISY 的 Z-Wave 节点。若目标范围包含非 Z-Wave 的 ISY 实体，动作可能无法对其正确执行，请在选定目标时确认实体来源。
补充：isy994 域的其他相关动作
围绕 Z-Wave 参数管理与节点控制，source/_actions/目录下与isy994域相关的动作文档还包括：
- isy994.set_zwave_parameter：写入 Z-Wave 设备参数（
parameter、value、size三个必填参数，size取值 1/2/4），新值回写为ZW#属性； - isy994.set_zwave_lock_user_code 与
isy994.delete_zwave_lock_user_code：管理 Z-Wave 门锁的用户码槽位； - isy994.send_node_command：向节点发送预定义命令（
beep、brighten、dim、fast_on、query等）； - isy994.send_raw_node_command：向节点发送原始 ISY REST 命令（如
DON/DOF），用于尚未被 Home Assistant 完整支持的设备。
这些动作共享同一目标（Targets）语义，均要求目标是 ISY 实体，可交叉参考以构建更完整的 ISY 设备控制方案。
总结
isy994.get_zwave_parameter是 Home Assistant 与 Universal Devices ISY/IoX 控制器协同管理 Z-Wave 设备配置的关键桥接动作。其要点可概括为：
- 作用：委托 ISY 向 Z-Wave 节点发起参数读取，结果以
ZW#实体属性返回； - 唯一必填参数：
parameter（整数），即设备参数表中的参数编号； - 目标约束：必须指定目标，且目标背后的实体须为 ISY Z-Wave 节点；
- 两种配置方式：UI（设置 > 自动化与场景）与 YAML（
action: isy994.get_zwave_parameter）均可，参数语义一致； - 配套能力：与
set_zwave_parameter成对使用可实现参数的读取、写入与回读校验。
掌握该动作后，你可以把 Z-Wave 设备的深层配置（如上报频率、灵敏度、LED 行为等）纳入 Home Assistant 的自动化逻辑与状态观测中，不必再依赖 ISY Admin Console 手工查询。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
