IR/RF 代理

IMPORTANT

此组件为实验性功能。API 可能会随时更改，且不遵循常规的重大变更政策。使用风险自负。一旦 API 被认为稳定，此警告将被移除。

ESPHome 的 IR/RF 代理组件与 Home Assistant 配合使用，扩展其远程控制能力。此组件为红外和 RF 信号的发送与接收提供了一个统一的、可通过 API 访问的接口，作为 Home Assistant（或其他 API 客户端）与 ESPHome 现有的 remote_receiver 和 remote_transmitter 组件之间的桥梁。请注意，如果你想使用 IR/RF 代理组件，设备的配置中必须至少包含其中之一。

IR/RF 代理支持运行时信号发送，无需重新编译和/或重新安装（刷写）固件，非常适合学习并回放 IR/RF 命令、创建万能遥控器以及与 Home Assistant 的远程控制功能集成。

IR/RF 代理提供两个平台实现：

红外平台 — 为红外用途创建一个 infrared 实体
射频平台 — 创建一个 radio_frequency 实体，包含 RF 特定元数据，如载波频率范围和调制类型

# Example configuration entry
remote_receiver:
  id: ir_rx
  pin: GPIOXX

remote_transmitter:
  - id: ir_tx
    pin: GPIOXX
    carrier_duty_percent: 50%
  - id: rf_tx
    pin: GPIOXX
    carrier_duty_percent: 100%

# Infrared platform — creates infrared entities
infrared:
  - platform: ir_rf_proxy
    name: IR Transmitter
    remote_transmitter_id: ir_tx
  - platform: ir_rf_proxy
    name: IR Receiver
    receiver_frequency: 38kHz
    remote_receiver_id: ir_rx

# Radio Frequency platform — creates radio_frequency entities
radio_frequency:
  - platform: ir_rf_proxy
    name: 433MHz RF Transmitter
    frequency: 433.92MHz
    remote_transmitter_id: rf_tx

红外平台

红外平台创建一个由 remote_transmitter 或 remote_receiver 支持的 infrared 实体。每个实例必须配置为发送器或接收器——不能同时两者都是。

infrared:
  - platform: ir_rf_proxy
    name: IR Proxy Transmitter
    remote_transmitter_id: ir_tx
  - platform: ir_rf_proxy
    name: IR Proxy Receiver
    receiver_frequency: 38kHz
    remote_receiver_id: ir_rx

红外配置变量

remote_transmitter_id（可选，ID）：用于发送信号的 remote_transmitter 组件的 ID。必须指定 remote_transmitter_id 或 remote_receiver_id 中的恰好一个。
remote_receiver_id（可选，ID）：用于接收信号的 remote_receiver 组件的 ID。必须指定 remote_transmitter_id 或 remote_receiver_id 中的恰好一个。
frequency（可选，frequency）：工作频率（例如 433 MHz、315 MHz、900 MHz）。用于 RF 硬件时设为非零值。默认值为 0（红外）。此值用于区分 IR 和 RF 硬件类型，并传递给 Home Assistant，以便其识别该 IR/RF 代理实例可能支持哪些集成。
receiver_frequency（可选，frequency）：红外接收器硬件的解调频率（例如 TSOP38238 的 38kHz）。此值对硬件无影响——它是报告给 API 客户端（如 Home Assistant）的元数据，以便其确定哪些红外协议与接收器兼容。仅在与 remote_receiver_id 一起使用时有效；与 remote_transmitter_id 一起使用将发生验证错误。如果解调频率未知或不相关，请省略。

来自 infrared 的所有其他配置变量。

NOTE

配置红外发送器（frequency: 0 或未设置）时，请确保关联的 remote_transmitter 已将 carrier_duty_percent 设为合适的值，通常为 30-50%。这对正确的红外传输是必需的。如果 carrier_duty_percent 设为 0% 或 100% 且 frequency 未设置或为零，将发生验证错误。

射频平台

射频平台创建一个由 remote_transmitter 或 remote_receiver 支持的 radio_frequency 实体。每个实例必须配置为发送器或接收器—— 如需同时使用两者，请创建单独的实例。

radio_frequency:
  - platform: ir_rf_proxy
    name: 433MHz RF Transmitter
    frequency: 433.92MHz
    remote_transmitter_id: rf_tx
  - platform: ir_rf_proxy
    name: 433MHz RF Receiver
    frequency: 433.92MHz
    remote_receiver_id: rf_rx

射频配置变量

remote_transmitter_id（可选，ID）：用于发送信号的 remote_transmitter 组件的 ID。必须指定 remote_transmitter_id 或 remote_receiver_id 中的恰好一个。
remote_receiver_id（可选，ID）：用于接收信号的 remote_receiver 组件的 ID。必须指定 remote_transmitter_id 或 remote_receiver_id 中的恰好一个。
frequency（可选，frequency）：RF 硬件的载波频率（例如 433.92MHz、 315MHz、868MHz）。这是报告给 API 客户端的元数据——它不会调整硬件。如果硬件在固定频率下运行，请设置此项以声明它。设置时，frequency_min 和 frequency_max 特性都将填充此值。

来自 radio_frequency 的所有其他配置变量。

NOTE

配置 RF 发送器时，关联的 remote_transmitter 必须将 carrier_duty_percent 设为 100%。RF 硬件自行处理调制；应用载波占空比会损坏信号。如果 carrier_duty_percent 设为任何其他值，将发生验证错误。

使用 CC1101（或其他 RF 前端）

要在射频平台中使用 CC1101 等可编程 RF 芯片，请将其状态控制操作连接到 remote_transmitter 的 on_transmit / on_complete 触发器。下面的示例展示了推荐的双引脚配置（CC1101 GDO0 → remote_transmitter，CC1101 GDO2 → remote_receiver）。对于单引脚变体或更多详细信息，请参见 CC1101 文档（ESP32 上为开漏， ESP8266 上为自动切换）——引脚配置会有所不同，但这里所示的触发器接线方式相同。

# CC1101 GDO0 wired to one GPIO pin
remote_transmitter:
  id: rf_tx
  pin: GPIOXX
  carrier_duty_percent: 100%
  on_transmit:
    then:
      - cc1101.begin_tx: cc1101_radio
  on_complete:
    then:
      - cc1101.begin_rx: cc1101_radio

# CC1101 GDO2 wired to a second GPIO pin
remote_receiver:
  id: rf_rx
  pin: GPIOXX

radio_frequency:
  - platform: ir_rf_proxy
    name: RF Proxy Transmitter
    frequency: 433.92MHz
    remote_transmitter_id: rf_tx
    # Optional: retune the CC1101 when an API request specifies a different
    # carrier frequency.  `x` is the radio_frequency call object.
    on_control:
      then:
        - if:
            condition:
              lambda: "return x.get_frequency().has_value() && *x.get_frequency() > 0;"
            then:
              - cc1101.set_frequency:
                  id: cc1101_radio
                  value: !lambda "return *x.get_frequency();"
  - platform: ir_rf_proxy
    name: RF Proxy Receiver
    frequency: 433.92MHz
    remote_receiver_id: rf_rx

上面使用的触发器：

remote_transmitter 上的 on_transmit — 每次传输前触发。在此调用 cc1101.begin_tx 将芯片置于 TX 状态。
remote_transmitter 上的 on_complete — 传输完成后触发。在此调用 cc1101.begin_rx 将芯片恢复到 RX 状态（空闲监听）。
radio_frequency 实体上的 on_control — 收到传输请求时触发，在底层传输开始之前。调用对象（x）提供 get_frequency()、get_modulation() 和 get_repeat_count()——使用该触发器进行每次调用的调整，例如将芯片重新调谐到请求的载波频率。

相同的接线模式适用于其他 RF 前端（SX127x、自定义外部组件）——用芯片等效的状态更改操作替代 cc1101.begin_tx / cc1101.begin_rx。

工作原理

IR/RF 代理组件创建可通过 API 访问的实体，可以从 Home Assistant 或其他 API 客户端进行控制。每个实例可以通过指定相应的硬件组件 ID 配置为发送器或接收器。

发送信号

两个平台都使用原始时序发送信号，这提供了对发送到硬件的确切波形的完全远程控制。当配置 remote_transmitter_id 时，组件可以通过接受一个微秒时序值数组来发送 IR/RF 信号，表示交错的 mark（LED 亮）和 space（LED 灭）时段。

传输参数：

原始时序数组：交错的 mark/space 持续时间（微秒）（与 remote_transmitter.transmit_raw 操作所使用的格式相同）
载波频率（红外平台）：可选载波频率，单位为 Hz（0 = 无载波调制）
重复次数：发送信号的次数（默认为 1）

对于射频平台，载波频率始终设为 0（无红外载波调制），因为专用 RF 硬件在物理层处理调制。

原始时序格式提供了最大的灵活性，可以支持更多或更少的协议，无论是否在 ESPHome 中实现。Home Assistant 集成可以将协议特定的命令编码为原始时序，并通过 IR/RF 代理组件发送。

接收信号

当配置 remote_receiver_id 时，IR/RF 代理捕获原始时序并将其发送给 API 客户端以进行解码或分析。这可以：

从现有遥控器学习 IR/RF 命令
分析未知协议
创建万能遥控器

两个平台共享相同的接收事件流——接收到的信号包含实体键，因此 API 客户端可以识别产生该事件的具体实体（红外或射频）。

接收是非阻塞的，允许其他监听器同时处理信号。

硬件支持

IR/RF 代理可与红外和 RF 硬件配合使用：

红外（infrared 平台）：不要设置 frequency（或设置 frequency: 0，这是默认值），并使用标准 IR LED/接收器。对于接收器，你可以设置 receiver_frequency 来声明硬件的解调频率（例如 TSOP38238 的 38kHz）。
RF（radio_frequency 平台）：使用射频平台进行 RF 配置。设置 frequency 以匹配你的 RF 硬件（例如 433.92MHz）。射频平台向 API 客户端报告 RF 特定元数据（支持的调制方式、频率范围）。

你可以为不同目的创建单独的实例：

仅发送（仅指定 remote_transmitter_id）
仅接收（仅指定 remote_receiver_id）
为不同硬件或频率创建上述任意实例的多个副本。例如，单个 ESPHome 设备可以有多个发送 LED，每个位于不同的房间/机柜中。