Home Assistant KNX 集成knx.event_register动作详解：动态注册 KNX 组地址事件过滤器
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
本篇技术指南聚焦 Home Assistant KNX 集成提供的knx.event_register动作（action），讲解如何动态地向knx_event事件过滤器添加或移除组地址，从而让原本未建模为实体的 KNX 组地址在指定时间段内向 Home Assistant 事件总线投递事件。读完本文，你将掌握该动作在 UI 与 YAML 两种方式下的完整配置方法、address/type/remove三个核心参数的含义与取值，以及如何结合自动化在 Home Assistant 启动时注册组地址并消费knx_event事件数据。
背景：knx_event事件与事件过滤器
KNX 集成通过event配置键维护一个事件过滤器。凡目的地址与过滤器模式匹配的 KNX 报文，都会被投递到 Home Assistant 事件总线，作为knx_event事件发出，可用于自动化触发。
在configuration.yaml中，event键的配置形式如下（完整定义见 KNX 集成 Events 章节）：
knx: event: - address: - "0/1/*" - address: - "1/2/*" - "1/3/2-4" type: "2byte_unsigned" - address: - "3/4/5" type: "2byte_float"地址支持通配符（如"0/1/*"）与范围（如"1/3/2-4"）。配置了type的地址块，其报文负载会按对应 DPT（Data Point Type，数据点类型）解码后写入事件数据的value键。
knx.event_register动作正是对这一过滤器的运行时扩展：它允许你在自动化或脚本中按需添加或移除组地址，无需改动configuration.yaml、也无需重启 Home Assistant。
核心机制：注册与注销如何工作
当某个组地址通过knx.event_register注册后，发送到该地址的报文就会触发一个knx_event事件。该事件在事件总线上携带以下数据属性（字段说明见 KNX 集成 Events 章节）：
| 属性 | 说明 |
|---|---|
data | 原始报文负载（如1或[12, 55]） |
destination | 报文发送到的 KNX 组地址字符串（如"1/2/3"） |
direction | 报文方向字符串（Incoming/Outgoing） |
source | 发送方 KNX 个体地址字符串（如"1.2.3"） |
telegramtype | APCI 服务类型；GroupValueWrite、GroupValueRead、GroupValueResponse会生成knx_event |
value | 若该地址配置了type，此处为按 DPT 解码后的值；GroupValueRead报文此键为None |
注册（remove: false）与注销（remove: true）本质上是同一动作的两种操作模式，因此你可以"按需开启、按需关闭"，从而只在特定时间段内监听某些地址。
适用场景
该动作主要面向以下两类需求（详见原动作文档）：
- 响应未建模为实体的 KNX 地址：某些组地址（如中间状态、动作触发位）不需要创建传感器或开关实体，只需在事件层面被感知。
- 按时间动态监听：通过在自动化中动态注册、注销，只在特定时间段内将地址纳入过滤器，避免事件总线长期被无关报文占用。
需要特别指出：在configuration.yaml中通过event键配置的组地址始终处于激活状态，无法通过该动作移除。此外，若你只是想"在自动化中响应报文"，官方推荐优先使用knx.telegram触发平台，而不是knx_event事件——关于两者的取舍，下文"与knx.telegram触发器的对比"一节会展开说明。
在 UI 中注册组地址
按以下步骤在自动化或脚本中使用该动作：
- 进入Settings > Automations & scenes。
- 打开现有自动化或脚本，或选择Create automation>Create new automation。
- 若是新建自动化，在When部分添加一个触发器；脚本不需要触发器，它们在被其他内容调用时运行。
- 在Then do部分选择Add action。
- 在搜索框中搜索并选择KNX: Register knx_event。
- 填写要注册的Group address。可选地，设置Value type用于解码负载，或打开Remove event registration以移除该地址。
- 选择Save。
该动作不支持 targets：在 UI 中不会提示你选择区域、设备、实体或标签。且只有具有管理员权限的用户才能运行此动作。
UI 选项一览
| 选项 | 必填 | 说明 |
|---|---|---|
| Group address | 是 | 要添加或移除的组地址；提供列表可一次注册多个组地址 |
| Value type | 否 | 若设置，负载将按给定 DPT 解码并写入事件数据的value键；可取 KNX sensor 类型的合法值，详见 KNX Sensor 章节 |
| Remove event registration | 否 | 若开启，将把组地址从过滤器中移除 |
YAML 用法与参数详解
在 YAML 中，动作名称为knx.event_register。最基本的使用示例：
action: knx.event_register data: address: "0/4/20"该示例将组地址0/4/20注册进过滤器，此后发往该地址的报文会触发knx_event事件。
YAML 参数
| 参数 | 必填 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
address | 是 | string / list | — | 要添加或移除的组地址；传入列表可一次注册多个组地址 |
type | 否 | string / integer | — | 若设置，负载按给定 DPT 解码并写入事件数据value键；可取 KNX sensor 类型的合法值 |
remove | 否 | boolean | false | 若为true，将把组地址从过滤器中移除 |
address：目标组地址
必填参数，支持单个地址字符串或字符串列表。一次注册多个地址的写法：
action: knx.event_register data: address: - "0/4/20" - "0/4/21"type：负载解码的 DPT
可选参数。当设置为某个 DPT 类型时，收到报文后会按该类型解码负载，并将解码结果写入knx_event事件数据的value键；未设置时value键为None，但data键仍保存原始负载（DPT 1、2、3 这类 1 字节类型尤其适合直接用原始负载）。
type的合法取值为 KNX sensor 类型，即 Value types 表 中列出的类型名（如percent、1byte_signed、2byte_float、temperature等），也可以使用 DPT 编号字符串（如"5.001"）。常见类型示例：
| DPT | type 取值 | 大小（字节） | 取值范围 | 单位 |
|---|---|---|---|---|
| 5.001 | percent | 1 | 0 ... 100 | % |
| 6 | 1byte_signed | 1 | -128 ... 127 | |
| 7 | 2byte_unsigned | 2 | 0 ... 65535 | |
| 8 | 2byte_signed | 2 | -32768 ... 32767 | |
| 9.001 | temperature | 2 | -273 ... 670760 | °C |
| 9.004 | illuminance | 2 | 0 ... 670760 | lx |
| 9.007 | humidity | 2 | 0 ... 670760 | % |
| 12 | 4byte_unsigned | 4 | 0 ... 4294967295 |
remove：注册还是注销
布尔参数，默认false。设为true时，动作改为将指定组地址从过滤器中移除，之后发往该地址的报文不再产生knx_event事件。配合自动化条件即可实现"仅在特定时间段监听"：
action: knx.event_register data: address: "0/4/20" remove: true完整自动化示例：Home Assistant 启动时注册组地址
以下自动化在 Home Assistant 启动时注册一个"卷帘移动"组地址，使该地址的报文触发knx_event，供后续动作使用。配置取自原动作文档的示例：
automation: alias: "Register KNX event on startup" triggers: - trigger: homeassistant event: start actions: - action: knx.event_register data: # Cover move trigger address: "0/4/20"此模式非常适合蓝图（blueprint）创作者：蓝图可以在安装或初始化阶段动态注册所需的组地址，而不要求用户在configuration.yaml中手工维护event列表。这也是该动作的主要设计意图之一。
消费knx_event事件数据
注册成功后，可在自动化中以事件触发的方式消费knx_event。例如结合type: "2byte_float"注册后，触发数据中可同时取到trigger.event.data（原始负载）与trigger.event.value（解码后的值）。事件数据中的destination、source、direction、telegramtype字段可用于在动作中进一步分流处理。
若你的目标是"收到某地址的报文就执行某动作"，更轻量的做法是直接使用knx.telegram触发器（配置与触发数据说明见 KNX 集成 Telegram trigger 章节）：
- alias: "Single group address trigger" triggers: - trigger: knx.telegram destination: 1/2/3 group_value_read: false outgoing: false conditions: "{{ trigger.value == 0 }}" actions: []knx.telegram触发器提供trigger.destination、trigger.source、trigger.value、trigger.payload、trigger.telegramtype等丰富的触发数据，且无需先经过事件过滤器注册。
注意事项与边界
event键配置的地址无法移除：凡在configuration.yaml的knx: event:下配置的组地址，始终处于激活状态，remove: true对它们无效。- 无 targets 支持：该动作不针对区域、设备、实体或标签执行，UI 中不会出现相关选择器。
- 管理员权限限制：只有管理员用户可以运行该动作。
- 优先使用触发器：如需在自动化中响应报文，官方建议优先使用 knx.telegram 触发器；
knx.event_register更适用于蓝图作者与"临时按需监听"的场景。 - 历史演进：
knx.event_register服务自 Home Assistant 2021.2 版本加入（见发布说明）；在 core-2026.6 中修复了该动作吞掉异常的问题（见更新日志），使用时应保持 Home Assistant 处于较新版本。
相关动作
knx.event_register属于 KNX 集成动作家族，与之配套的还有：
- knx.send：向 KNX 总线发送报文（写入）。
- knx.read：向 KNX 总线发送 GroupValueRead 读请求，配合
knx.telegram触发器可主动刷新实体状态。 - knx.exposure_register：动态注册"暴露"配置，将 Home Assistant 实体状态、属性或时间广播到 KNX 总线。
实际使用中，knx.read读回的响应与knx.event_register注册的地址报文都会以knx_event/ 触发器形式进入事件流，两者常搭配使用以构建"按需轮询 + 被动监听"的混合方案。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
