企业官网建设流程全解析

Home Assistant RFXtrxrfxtrx.send动作完整指南：通过 433.92 MHz 射频发送原始事件

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

导读

rfxtrx.send是 Home Assistant 中 RFXCOM RFXtrx 集成提供的核心动作（action），用于通过 433.92 MHz 射频收发器向空中发送原始事件数据包（十六进制字符串），从而模拟遥控器按键、控制未自动接入 Home Assistant 的旧式射频设备（例如老式无线插座、门铃、卷帘遥控等）。本文以 source/_actions/rfxtrx.send.markdown 为骨架，结合 RFXCOM RFXtrx 集成文档 与仓库中的渲染插件实现，系统讲解该动作在 UI 与 YAML 两种场景下的完整用法、事件码生成方法、常见自动化示例以及底层原理，帮助你在不依赖设备自动发现的情况下直接通过原始射频数据包控制设备。

一、动作概述与适用场景

rfxtrx.send的动作描述为："Sends a raw event over the radio with the RFXtrx device"，即通过 RFXtrx 设备在无线电上发送一条原始事件。

它主要面向以下两类典型场景：

1. 模拟按钮按下：例如模拟遥控器按键，触发本应由实体遥控器完成的动作；
2. 控制未自动加入 Home Assistant 的设备：部分旧式遥控插座、卷帘、铃铛等设备无法被 Home Assistant 自动识别为实体，此时可跳过设备发现流程，直接向设备发送已知的原始事件码即可完成控制。

关键事实：不支持 targets

该动作不支持目标（targets）。在 UI 中，它不会提示你选择区域（area）、设备（device）、实体（entity）或标签（label）。这一点与大多数面向实体的动作（如light.turn_on、switch.toggle）有本质区别——rfxtrx.send的操作对象是"空中无线电信号"，而非某个具体实体，因此无需也不应指定目标。

二、在 UI 中使用rfxtrx.send

Home Assistant 的 UI 构建工具会逐步引导你配置此动作，无需编写 YAML。操作步骤如下：

1. 进入Settings（设置） > Automations & scenes（自动化与场景）；
2. 打开一个现有的自动化或脚本，或选择Create automation（创建自动化）>Create new automation（创建新自动化）；
3. 若在创建新的自动化，请在When（当……时）部分添加一个触发器；脚本（scripts）则不需要触发器，它们在被其他内容调用时才运行；
4. 在Then do（则执行）部分，选择Add action（添加动作）；
5. 搜索并选择RFXCOM RFXtrx: Send；
6. 在Event（事件）字段中输入一个十六进制字符串；
7. 选择Save（保存）。

UI 流程说明来自 ui_header 包含文件："If you prefer building automations and scripts visually, Home Assistant walks you through this action step by step. You pick what to target, tweak a few options, and save. No YAML knowledge required."

UI 中的选项

在 UI 中，该动作只暴露一个选项：

UI 中的选项渲染由仓库中的 options_ui.rb 插件 实现：该插件将{% options_ui %}块中的 YAML 转换为带有名称、必需/可选徽标与描述的可视化选项卡片，因此你在界面上看到的字段说明与上表一一对应。

三、在 YAML 中使用rfxtrx.send

在 YAML 中，该动作以rfxtrx.send被引用。基本用法如下：

action: rfxtrx.send data: event: "0b1111e003af16aa10000060"

此示例通过在无线电上发送原始事件来模拟按下按钮。YAML 场景的说明来自 yaml_header 包含文件，其定位是面向直接编写 YAML、或希望了解 Home Assistant 底层行为的用户，提供字段名、类型与必填性的技术参考。

YAML 选项参考

YAML 选项的渲染由 options_yaml.rb 插件 实现，它复用共享的ConfigurationBlock渲染逻辑，输出与配置变量相同的布局、类型链接和 Required/Optional 徽标。

在自动化/脚本中的完整形态

在自动化中，动作通常与触发器配合使用：

automation: - alias: "Switch on the porch light at sunset" triggers: - trigger: sun.sunset actions: - action: rfxtrx.send data: event: "0b1111e003af16aa10000060"

四、实战示例：日落时控制未接入 Home Assistant 的设备

原文档给出了一个完整的实战案例：当太阳落山时，向一个 Home Assistant 无法直接控制的设备（例如旧式遥控插座）发送原始事件来打开它。

• 触发器（Trigger）：Sunset（日落）
• 动作（Action）：RFXCOM RFXtrx: Send
  • Event（事件）：0b1111e003af16aa10000060

完整 YAML：

automation: - alias: "Switch on the porch light at sunset" triggers: - trigger: sun.sunset actions: - action: rfxtrx.send data: event: "0b1111e003af16aa10000060"

该示例展示了rfxtrx.send的典型用法闭环：通过时间/太阳位置等系统触发器，在任意时刻向射频设备注入预先采集好的原始事件码。因为发送的是原始无线电数据包，无需该设备在 Home Assistant 中注册为实体，这正是它区别于普通实体动作的价值所在。

五、事件码从哪里来：Generate codes 与事件码采集

要使用rfxtrx.send，最核心的前置条件是获得合法的事件码（十六进制字符串）。原文档明确指向集成页面的 Generate codes 章节（对应仓库文件 rfxtrx.markdown 的 Generate codes 部分），其提供两条主要途径：

5.1 使用模板生成新设备的事件码

对于开关和灯光（例如 COCO 开关），可以在Settings（设置） > Tools（工具） > Template（模板）中使用以下模板生成随机事件码：

开关：ARC 协议

0b11000{{ range(100,700) | random | int }}bc0cfe0{{ range(0,10) | random | int }}010f70

灯光：ARC 协议

0b11000{{ range(100,700) | random | int }}bc0cfe0{{ range(0,10) | random | int }}020f70

灯光：Lightwave RF 协议

0a14000{{ range(100,700) | random | int }}bc0cf{{ range(0,10) | random | int }}100f70

生成后：

1. 使用此代码在集成选项菜单中添加一个新开关（对应"按事件码添加设备"功能）；
2. 启动 Home Assistant 并打开网站；
3. 开启开关的学习模式（按下学习按钮或将其插入墙式插座）；
4. 在 Home Assistant 界面中切换你的新开关。

注意：模板中的range(100,700) | random每次渲染都会生成不同的随机数值，因此同一模板可重复用于生成不同设备的独立事件码。

5.2 从日志/状态属性采集已有设备的事件码

对于已存在的物理设备：

• 开启集成选项中的Automatic add（自动添加），让设备触发一次发送，即可在系统日志中看到类似Added binary sensor 0913000022670e013970 (Device_id: 22670e ...)的条目，其中包含完整事件码；
• 对于已作为开关接入的设备，可从开关实体状态属性（实体详情窗口底部）复制其事件码。

5.3 将开关事件码转换为调光事件码

要将普通开关转换为可调光灯光，通常只需改动事件码中的一个字节：

• ARC：0b11000248bc0cfe09 **01** 0f70→0b11000248bc0cfe09 **02** 0f70（01为开/调光命令字节，02为亮度命令字节）
• LightwaveRF：0a14000101f20302 **01** 0080→0a14000101f20302 **10** 0080
• Waveman：710030e4102 **01** 50→710030e4102 **02** 50

这些转换后的事件码同样可以直接用于rfxtrx.send。

六、Good to know 与常见问题

• 事件码生成：开关与灯光的事件码生成方法见 RFXCOM RFXtrx 集成页面的 Generate codes 章节，本文第五节已给出可直接使用的模板。
• 发送对象是原始射频数据包：rfxtrx.send不依赖设备发现机制，因此对于"识别不出"的老旧设备（如老式遥控插座）依然有效。
• 不指定目标：该动作无 targets 支持，配置时只需填写event字段。

卡住时的排查思路

如果发送事件后设备无响应，可参考以下排查方向：

1. 确认协议已启用：RFXcom 收发器默认只启用部分协议，且启用协议过多会显著降低接收灵敏度。若你的设备协议未启用（例如某些协议只能通过设备配置在每次连接时启用，如undecoded），发送将失败。参见集成文档的 "Supported protocols" 章节。
2. 确认事件码完整准确：十六进制字符串必须逐字节正确，可通过日志中自动添加设备时打印的完整事件码进行核对。
3. 开启调试日志：在configuration.yaml中配置homeassistant.components.rfxtrx: debug与RFXtrx: debug（注意RFXtrx区分大小写），观察发送路径上的日志输出。
4. 先在 Tools（工具）> Actions（动作）中试跑：打开Settings（设置） > Tools（工具） > Actions（动作），搜索该动作、填入字段并选择Perform action（执行动作），在不写任何 YAML 的情况下即可在真实实体上观察效果。这一"Try it yourself"验证方式来自 try_it 包含文件。

七、底层原理与实现佐证

7.1 动作文档的渲染管线

rfxtrx.send的文档页面由 Jekyll 站点构建，其 Front Matter 定义如下：

--- title: "Send" action: rfxtrx.send domain: rfxtrx description: "Sends a raw event over the radio with the RFXtrx device." ---

页面中的{% options_ui %}与{% options_yaml %}块分别由 options_ui.rb 和 options_yaml.rb 插件渲染：

• options_ui.rb面向 UI 受众，将选项渲染为带必需/可选徽标的可视化卡片；
• options_yaml.rb面向 YAML 受众，复用ConfigurationBlock（configuration.rb）渲染类型链接与徽标。

两个插件都通过SafeYAML.load解析选项 YAML，并强制要求每个选项必须包含description，否则抛出ArgumentError——这保证了每个文档化动作的选项都有完整说明。

7.2 在集成文档中的关联位置

在 RFXCOM RFXtrx 集成文档 中，通过 actions.md 包含文件 自动列出该域下的全部动作：文档会按ha_domain从site.actions中筛选出rfxtrx域的所有动作并逐一链接，rfxtrx.send（Send）即其中之一。这也解释了为什么该动作页面与集成页面互为补充：集成页面负责设备接入、协议、事件码采集，动作页面负责具体的发送动作配置。

7.3 与其他 RFXtrx 机制的关系

• 事件接收（rfxtrx_event）：集成文档中的 Events 章节说明，当设备开启fire_event参数后，接收到的消息会以rfxtrx_event事件形式广播（包含packet_type、sub_type、type_string、id_string、data、values等字段）。rfxtrx.send是与之对应的发送方向动作——两者共同构成"接收-发送"的双向射频通道。
• Somfy RTS 等特殊协议：Somfy RTS 设备不支持接收（无法自动添加），必须在 rfxmngr 工具中配置并记录 ID/Unit Code，再以071a0000[id][unit_code]形式的 ID 手动添加设备。这类设备同样可以通过rfxtrx.send发送控制指令。

八、总结

rfxtrx.send是 Home Assistant 中面向原始射频数据包的发送动作，其核心价值在于：

• 绕过设备发现：即使设备无法自动接入，也能通过十六进制事件码直接控制；
• 模拟按键：可复现任何遥控器按键行为，用于自动化联动；
• 配置极简：仅需一个必填的event字段，UI 与 YAML 两套配置方式完全等价。

使用该动作的关键在于获得准确的事件码——无论是通过 Template 模板生成新码，还是从日志/实体状态属性采集已有设备的码，均可配合 Generate codes 章节的指引完成。结合 RFXtrx 集成文档 中关于协议启用、调试日志与事件接收的说明，你可以构建出完整可靠的 433.92 MHz 射频设备控制方案。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io