跳转到内容
ESPHome - 让智能家居更简单2026.7.0

远程接收器

remote_receiver 组件让你接收和解码各种常见的遥控信号，例如红外 或 433 MHz 射频（RF）信号。

该组件分为两个部分：

  • 远程接收器 “hub”，它定义引脚和一些附加设置，以及…
  • 单独的远程接收器二进制传感器，当接收到它们的 相应信号时会被激活。

参见 设置 IR 设备 和 设置 RF 设备 了解详情。

# 示例配置条目
remote_receiver:
  pin: GPIOXX
  dump: all

在 remote_receiver 中可以配置多个远程接收器，作为字典定义的列表。

配置变量

Section titled “配置变量”

  • pin (必选, Pin): 用于接收远程信号的引脚。

  • dump (可选, list): 解码并在日志中转储这些远程码（在 log.level=DEBUG 时）。 设置为 all 可转储所有可用的编解码器：

    • abbwelcome: 解码并转储 ABB-Welcome 码。消息通过铜线发送。参见 发射器描述 了解更多细节。

    • aeha: 解码并转储 AEHA 红外码。

    • beo4: 解码并转储 B&O Beo4 红外码。

    • brennenstuhl: 解码并转储 brennenstuhl RF 码。

    • byronsx: 解码并转储 Byron SX 门铃 RF 码。

    • canalsat: 解码并转储 CanalSat 红外码。

    • canalsatld: 解码并转储 CanalSatLD 红外码。

    • coolix: 解码并转储 Coolix 红外码。

    • dish: 解码并转储 Dish 红外码。

    • dooya: 解码并转储 Dooya RF 码。

    • drayton: 解码并转储 Drayton Digistat RF 码。

    • dyson: 解码并转储 Dyson Cool AM7 塔扇码。

    • jvc: 解码并转储 JVC 红外码。

    • gobox: 解码并转储 Go-Box 红外码。

    • keeloq: 解码并转储 KeeLoq RF 码。

    • haier: 解码并转储 Haier 红外码。

    • lg: 解码并转储 LG 红外码。

    • magiquest: 解码并转储 MagiQuest 魔杖红外码。

    • midea: 解码并转储 Midea 红外码。

    • nec: 解码并转储 NEC 红外码。

    • nexa: 解码并转储 Nexa（RF）码。

    • panasonic: 解码并转储 Panasonic 红外码。

    • pioneer: 解码并转储 Pioneer 红外码。

    • pronto: 以 Pronto 形式打印远程码。对于使用任意协议很有用。

    • raw: 以原始形式打印所有远程码。对于使用任意协议也很有用。

    • rc5: 解码并转储 RC5 IR 码。

    • rc6: 解码并转储 RC6 IR 码。

    • rc_switch: 解码并转储 RCSwitch RF 码。

    • roomba: 解码并转储 Roomba 红外码。

    • samsung: 解码并转储 Samsung 红外码。

    • samsung36: 解码并转储 Samsung36 红外码。

    • symphony: 解码并转储 Symphony 红外码。

    • sony: 解码并转储 Sony 红外码。

    • toshiba_ac: 解码并转储 Toshiba AC 红外码。

    • mirage: 解码并转储 Mirage 红外码。

    • toto: 解码并转储 Toto 红外码。

  • tolerance (可选, int, Time 或 mapping): 解码过程中远程信号长度 可以偏离的百分比或时间。默认为 25%。

    • type (必选, enum): 设置容差的类型。可以是 percentage 或 time。
    • value (必选, int 或 Time): 百分比或时间值。允许范围是从 0 到 100%，或 0 到 4294967295us。

  • buffer_size (可选, int): 用于存储远程码的内部缓冲区大小。在 ESP32 上默认为 10kB， 在 ESP8266 上为 1kB。

  • filter (可选, Time): 过滤所有短于这个时间的脉冲。用于 去除噪声信号中的毛刺。允许范围是从 0 到 4294967295us。默认为 50us。

  • idle (可选, Time): 信号保持一致/不变的时间量，超过后 被视为传输完成。默认为 10ms。允许的最大值是：

    • ESP32 和 ESP32-S2 变体上为 65536us
    • 其他带有 RMT 硬件的 ESP32 变体上为 32767us
    • 所有其他平台（包括使用软件实现的 ESP32-C2 和 ESP32-C61）上为 4294967295us

    注意：上面列出的 ESP32 RMT 值假设使用默认的 clock_resolution。如果使用了不同的 clock_resolution， 则这些值按 1000000 / clock_resolution 缩放。

  • id (可选, ID): 手动指定用于代码生成的 ID。当在单个设备上 配置多个接收器时很有用。

ESP32 RMT 配置变量

Section titled “ESP32 RMT 配置变量”

NOTE

以下选项仅适用于带有 RMT 硬件的 ESP32 变体。它们在 ESP32-C2 和 ESP32-C61 上不可用，这两个变体使用软件实现。

  • rmt_symbols (可选, int): 当启用 use_dma 时，此选项设置驱动内部 DMA 缓冲区的大小。 当 DMA 禁用时，它指定分配给组件的 RMT 内存量。RMT 内存在所有组件之间共享， 应按块大小的倍数分配。在 ESP32 和 ESP32-S2 变体上，RMT 内存在 RX 和 TX 组件之间共享。在其他变体上，RX 和 TX 有独立专用的 RMT 内存。
ESP32 变体可用内存块大小
ESP32512 symbols64 symbols
ESP32-C396 symbols48 symbols
ESP32-C596 symbols48 symbols
ESP32-C696 symbols48 symbols
ESP32-H296 symbols48 symbols
ESP32-P4192 symbols48 symbols
ESP32-S2256 symbols64 symbols
ESP32-S3192 symbols48 symbols

  • receive_symbols (可选, int): 最大接收长度（以符号为单位）。在某些变体上，最大接收 长度受限于 rmt_symbols。

  • filter_symbols (可选, int): 过滤掉所有长度（以符号为单位）小于 filter_symbols 的接收数据。用于过滤掉短暂的噪声突发。

  • clock_resolution (可选, int): RMT 外设使用的时钟分辨率，单位为 Hz。默认为 1000000。

  • use_dma (可选, boolean): 在支持的变体上启用 DMA。如果启用，rmt_symbols 控制 DMA 缓冲区大小，可以设置为很大的值。

信号解调

Section titled “信号解调”

在罕见的情况下，如果硬件配置使微控制器接收调制信号，RMT 外设支持 信号解调。如果你不确定，你可能不需要它。例如，红外遥控信号 通常在到达微控制器之前就已被红外接收模块（IRM）解调。

要启用信号解调，请配置信号载波频率和占空比：

  • carrier_duty_percent (可选, int): RMT 外设中用于信号解调的载波占空比，单位 Hz。默认为 100。

  • carrier_frequency (可选, int): RMT 外设中用于信号解调的载波频率，单位 Hz。 默认为 0Hz（载波解调禁用）。

NOTE

转储的原始（raw）码是一系列脉冲宽度（以微秒为单位的持续时间），正值表示开启脉冲（mark）， 负值表示关闭脉冲（space）。通常你可以直接将其复制到配置或自动化中 供以后使用。

自动化

Section titled “自动化”
# 用于解码信号的示例自动化
remote_receiver:
  ...
  on_samsung:
    then:
    - if:
        condition:
          or:
            - lambda: 'return (x.data == 0xE0E0E01F);'  # VOL+ 新型
            - lambda: 'return (x.data == 0xE0E0E01F0);' # VOL+ 旧型
        then:
          - ...

二进制传感器

Section titled “二进制传感器”

remote_receiver 二进制传感器让你跟踪遥控器上的按钮何时被按下。

每次收到预定义的信号时，二进制传感器会短暂变为 ON，然后立即变为 OFF。

NOTE

针对 IR 遥控二进制传感器：如果你使用二进制传感器跟踪 IR 遥控按钮按下，并且 遇到快速按键未被检测到的问题（例如，快速的 ON→OFF 转换被错过）， 请考虑在你的 API 配置 中设置 batch_delay: 0ms。这将立即发送状态 变化而不是批量发送，确保快速的转换得以保留。但是，这会增加 网络流量，只应在必要时使用。

对于新项目，考虑使用带有 on_* 触发器（如上所述）的自动化 而不是二进制传感器，因为它们更适用于处理瞬时按键事件。

# 示例配置条目
binary_sensor:
  - platform: remote_receiver
    name: "Panasonic Remote Input"
    panasonic:
      address: 0x4004
      command: 0x100BCBD
# 快速按键使用 batch_delay: 0 的示例
api:
  batch_delay: 0ms  # 立即发送状态变化


remote_receiver:
  pin: GPIOXX
  dump: all


binary_sensor:
  - platform: remote_receiver
    name: "TV Remote Power"
    nec:
      address: 0x1234
      command: 0x5678

配置变量

Section titled “配置变量”

  • receiver_id (可选, ID): 用于接收远程码的远程接收器。如果 配置了多个接收器，则为必选。

  • Binary Sensor 的所有其他选项。

远程码选择（必须包含下列恰好一项）：

  • abbwelcome: 使用给定的数据在解码后的 ABB-Welcome 码上触发，参见 发射器描述 了解更多信息。

    • source_address (必选, int): 要触发匹配的源地址。

    • destination_address (必选, int): 要触发匹配的目标地址。

    • three_byte_address (可选, boolean): 源地址和目标地址的长度。false 表示 两个字节，true 表示三个字节。默认为 false。

    • retransmission (可选, boolean): 如果消息被重传则为 true。默认为 false。

    • message_type (必选, int): 要触发匹配的消息类型。

    • message_id (可选, int): 要触发匹配的随机消息 ID，参见 dumper 输出了解更多信息。默认为 任何 ID。

    • data (可选, 0-7 字节列表): 要监听的码。通常你只需要直接从 dumper 输出中 复制此内容。默认为 []。

  • aeha: 使用给定的数据在解码后的 AEHA 遥控码上触发。

    • address (必选, int): 要触发匹配的地址，参见 dumper 输出了解更多信息。
    • data (必选, 3-35 字节列表): 要监听的码，参见 发射器描述 了解更多信息。通常你只需要直接从 dumper 输出中 复制此内容。

  • beo4: 使用给定的数据在解码后的 B&O Beo4 红外遥控码上触发。

    • source (必选, int): 要触发匹配的 8 位源，例如 0x00=video, 0x01=audio,…，参见 dumper 输出了解更多信息。
    • command (必选, int): 要监听的 8 位命令，例如 0x00=number0, 0x0C=standby,…，参见 dumper 输出了解更多信息。

  • brennenstuhl: 使用给定的数据在解码后的 brennenstuhl RF 码上触发。

    • code (必选, int): 要触发匹配的 24 位码，参见 dumper 输出了解更多信息。

  • byronsx: 使用给定的数据在解码后的 Byron SX 门铃 RF 遥控码上触发。

    • address (必选, int): 要触发匹配的 8 位 ID 码，参见 dumper 输出了解更多信息。
    • command (可选, int): 要监听的 4 位命令。如果省略，将匹配任何命令。

  • canalsat: 使用给定的数据在解码后的 CanalSat 遥控码上触发。

    • device (必选, int): 要触发匹配的设备，参见 dumper 输出了解更多信息。

    • address (可选, int): 要触发匹配的地址（或子设备），参见 dumper 输出了解更多信息。 默认为 0。

    • command (必选, int): 要监听的命令。

  • canalsatld: 使用给定的数据在解码后的 CanalSatLD 遥控码上触发。

    • device (必选, int): 要触发匹配的设备，参见 dumper 输出了解更多信息。

    • address (可选, int): 要触发匹配的地址（或子设备），参见 dumper 输出了解更多信息。 默认为 0。

    • command (必选, int): 要监听的命令。

  • coolix: 使用给定的数据在解码后的 Coolix 遥控码上触发。可以直接指定一个 24 位 码，它将与两个接收到的数据包中的至少一个进行匹配检查。主要的配置方案 如下。

    • first (必选, uint32_t): 要触发匹配的第一个 24 位 Coolix 码，参见 dumper 输出了解更多信息。
    • second (可选, uint32_t): 要触发匹配的第二个 24 位 Coolix 码，参见 dumper 输出了解更多信息。 如果未设置，则仅在 first 参数指定的单个非严格数据包上触发。

  • dish: 使用给定的数据在解码后的 Dish Network 遥控码上触发。 请注意，Dish 遥控器使用不同的载波频率（57.6kHz），许多接收器硬件无法解码。

    • address (可选, int): 要针对的接收器编号，范围 1 到 16（含）。默认为 1。
    • command (必选, int): 要监听的 Dish 命令，范围 0 到 63（含）。

  • dooya: 使用给定的数据在解码后的 Dooya RF 遥控码上触发。

    • id (必选, int): 要触发匹配的 24 位 ID 码。
    • channel (必选, int): 要监听的 8 位通道。
    • button (必选, int): 要监听的 4 位按钮。
    • check (必选, int): 要监听的 4 位校验值。包含按钮被按住的状态指示。

  • drayton: 使用给定的数据在解码后的 Drayton Digistat RF 遥控码上触发。

    • address (必选, int): 要触发匹配的 16 位 ID 码，参见 dumper 输出了解更多信息。
    • channel (必选, int): 要监听的 7 位开关/通道。
    • command (必选, int): 要监听的 5 位命令。

  • dyson: 使用给定的数据在解码后的 dyson cool AM07 红外遥控码上触发。

    • code (必选, int): 要触发匹配的 16 位码，例如 0x1200=power, 0x1215=fan++,0x122a=swing…，参见 dumper 输出了解更多信息。
    • index (可选, int): 8 位滚动索引 [0..3]，每次发送都会递增，参见 dumper 输出了解更多信息。

  • gobox: 使用给定的数据在解码后的 Go-Box 遥控码上触发。

    • code (必选, int): 要触发匹配的 Go-Box 码，参见 dumper 输出了解更多信息。

  • jvc: 使用给定的数据在解码后的 JVC 遥控码上触发。

    • data (必选, int): 要触发匹配的 JVC 码，参见 dumper 输出了解更多信息。

  • keeloq: 使用给定的数据在解码后的 KeeLoq RF 遥控码上触发。

    • address (必选, int): 要触发匹配的 32 位 ID 码，参见 dumper 输出了解更多信息。
    • command (可选, int): 要监听的 8 位开关/命令。如果省略，将匹配任何命令/按钮。

  • haier: 使用给定的码在 Haier 遥控码上触发。

    • code (必选, 13 字节列表): 要监听的码，参见 发射器描述 了解更多信息。通常你只需要直接从 dumper 输出中复制 此内容。

  • lg: 使用给定的数据在解码后的 LG 遥控码上触发。

    • data (必选, int): 要触发匹配的 LG 码，参见 dumper 输出了解更多信息。
    • nbits (可选, int): 遥控码的位数。默认为 28。

  • magiquest: 使用给定的魔杖 ID 在解码后的 MagiQuest 魔杖遥控码上触发。

    • wand_id (必选, int): 要触发匹配的 MagiQuest 魔杖 ID，参见 dumper 输出了解更多信息。
    • magnitude (可选, int): 魔杖挥舞和旋转的幅度。如果省略，将匹配魔杖的任意 激活。

  • midea: 使用给定的码在 Midea 遥控码上触发。

    • code (必选, 5 字节列表): 要监听的码，参见 发射器描述 了解更多信息。通常你只需要直接从 dumper 输出中复制 前 5 个字节。

  • nec: 使用给定的数据在解码后的 NEC 遥控码上触发。

    • address (必选, int): 要触发匹配的地址，参见 dumper 输出了解更多信息。
    • command (必选, int): 要监听的 NEC 命令。

  • nexa: 使用给定的数据在解码后的 Nexa RF 码上触发。

    • device (必选, int): 要触发匹配的 Nexa 设备码，参见 dumper 输出了解更多信息。
    • group (必选, int): 要触发匹配的 Nexa 组码，参见 dumper 输出了解更多信息。
    • state (必选, int): 要触发匹配的 Nexa 状态码，参见 dumper 输出了解更多信息。
    • channel (必选, int): 要触发匹配的 Nexa 通道码，参见 dumper 输出了解更多信息。
    • level (必选, int): 要触发匹配的 Nexa 级别码，参见 dumper 输出了解更多信息。

  • panasonic: 使用给定的数据在解码后的 Panasonic 遥控码上触发。

    • address (必选, int): 要触发匹配的地址，参见 dumper 输出了解更多信息。
    • command (必选, int): 命令。

  • pioneer: 使用给定的数据在解码后的 Pioneer 遥控码上触发。

    • rc_code_1 (必选, int): 要触发匹配的遥控码，参见 dumper 输出了解更多细节。

  • pronto: 使用给定的码在 Pronto 遥控码上触发。

    • data (必选, string): 要监听的码，参见 发射器描述 了解更多信息。通常你只需要直接从 dumper 输出中复制此内容。

    • delta (可选, integer): 此参数允许你手动指定 指定的 Pronto 码与遥控器实际发送的 IR 信号之间允许的差异。

  • raw: 使用给定的码在原始（raw）遥控码上触发。

    • code (必选, list): 要监听的码，参见 发射器描述 了解更多信息。通常你只需要直接从 dumper 输出中复制此内容。

  • rc5: 使用给定的数据在解码后的 RC5 遥控码上触发。

    • address (必选, int): 要触发匹配的地址，参见 dumper 输出了解更多信息。
    • command (必选, int): 要监听的 RC5 命令。

  • rc6: 使用给定的数据在解码后的 RC6 遥控码上触发。

    • address (必选, int): 要触发匹配的地址，参见 dumper 输出了解更多信息。
    • command (必选, int): 要监听的 RC6 命令。

  • rc_switch_raw: 使用给定的数据在解码后的 RC Switch 原始遥控码上触发。

    • code (必选, string): 要监听的遥控码，从 dumper 输出中复制。要在接收数据中忽略 某一位，请在code中的相应位置使用 x。

    • protocol (可选): 要使用的 RC Switch 协议，参见 RC Switch 协议 了解 更多信息。

  • rc_switch_type_a: 使用给定的数据在解码后的 RC Switch A 型遥控码上触发。

    • group (必选, string): 组，二进制字符串。
    • device (必选, string): 组中的设备，二进制字符串。
    • state (必选, boolean): 要触发匹配的开/关状态。
    • protocol (可选): 要使用的 RC Switch 协议，参见 RC Switch 协议 了解 更多信息。

  • rc_switch_type_b: 使用给定的数据在解码后的 RC Switch B 型遥控码上触发。

    • address (必选, int): 地址，整数 1 到 4。
    • channel (必选, int): 通道，整数 1 到 4。
    • state (必选, boolean): 要触发匹配的开/关状态。
    • protocol (可选): 要使用的 RC Switch 协议，参见 RC Switch 协议 了解 更多信息。

  • rc_switch_type_c: 使用给定的数据在解码后的 RC Switch C 型遥控码上触发。

    • family (必选, string): 系列。范围是 a 到 p。
    • group (必选, int): 组。范围是 1 到 4。
    • device (必选, int): 设备。范围是 1 到 4。
    • state (必选, boolean): 要触发匹配的开/关状态。
    • protocol (可选): 要使用的 RC Switch 协议，参见 RC Switch 协议 了解 更多信息。

  • rc_switch_type_d: 使用给定的数据在解码后的 RC Switch D 型遥控码上触发。

    • group (必选, int): 组。范围是 1 到 4。
    • device (必选, int): 设备。范围是 1 到 3。
    • state (必选, boolean): 要触发匹配的开/关状态。
    • protocol (可选): 要使用的 RC Switch 协议，参见 RC Switch 协议 了解 更多信息。

  • roomba: 使用给定的数据在解码后的 Roomba 遥控码上触发。

    • data (必选, int): 要触发匹配的 Roomba 码，参见 dumper 输出了解更多信息。

  • samsung: 使用给定的数据在解码后的 Samsung 遥控码上触发。

    • data (必选, int): 要触发匹配的数据，参见 dumper 输出了解更多信息。
    • nbits (可选, int): 遥控码的位数。默认为 32。

  • samsung36: 使用给定的数据在解码后的 Samsung36 遥控码上触发。

    • address (必选, int): 要触发匹配的地址，参见 dumper 输出了解更多信息。
    • command (必选, int): 命令。

  • sony: 使用给定的数据在解码后的 Sony 遥控码上触发。

    • data (必选, int): 要触发匹配的 Sony 码，参见 dumper 输出了解更多信息。
    • nbits (可选, int): 遥控码的位数。默认为 12。

  • symphony: 使用给定的数据在解码后的 Symphony 遥控码上触发。

    • data (必选, int): 要触发匹配的 Symphony 码，参见 dumper 输出了解更多信息。
    • nbits (必选, int): 遥控码的位数。典型值：8、12 或 16。

  • toshiba_ac: 使用给定的数据在解码后的 Toshiba AC 遥控码上触发。

    • rc_code_1 (必选, int): 要触发匹配的遥控码，参见 dumper 输出了解更多细节。
    • rc_code_2 (可选, int): 要触发匹配的遥控码的第二部分，参见 dumper 输出了解 更多细节。

  • mirage: 使用给定的码在 Mirage 遥控码上触发。

    • code (必选, 14 字节列表): 要监听的码，参见 发射器描述 了解更多信息。通常你只需要直接从 dumper 输出中复制 此内容。

  • toto: 使用给定的数据在解码后的 Toto 遥控码上触发。

    • command (必选, int): 要触发匹配的 1 字节 Toto 命令码。范围是 0 到 0xFF。
    • rc_code_1 (可选, int): 要触发匹配的第一个 4 位 Toto 码（通常是一个命令参数）。范围是 0 到 0xF。
    • rc_code_2 (可选, int): 要触发匹配的第二个 4 位 Toto 码（通常是一个命令参数）。范围是 0 到 0xF。

NOTE

CanalSat 和 CanalSatLD 协议使用更高的载波频率（56kHz），并且非常相似。 根据所使用的硬件，同时启用时它们可能会相互干扰。

NOTE

NEC 码：在 2021.12 版本中，位传输的顺序按照 NEC 标准从 MSB 纠正为 LSB。因此，如果配置文件来自 ESPhome 的早期版本， 转到 2021.12 或更高版本时，需要反转地址和命令位的顺序。例如， address: 0x84ED、command: 0x13EC 分别变为 0xB721 和 0x37C8。

NOTE

一些接收器（如 TSOP38238）可能需要使用上拉电阻。你可以按如下方式启用：

remote_receiver:
  pin:
    number: GPIOXX
    inverted: true
    mode:
      input: true
      pullup: true
  dump: all

NOTE

对于黑色 Sonoff RF 桥接器，你可以通过 这个 hack 绕过 EFM8BB1 微控制器来处理 RF 信号，该 hack 由 GitHub 用户 wildwiz 创建。然后为远程接收器/发射器 hub 使用此配置：

remote_receiver:
  pin: 4
  dump: all


remote_transmitter:
  pin: 5
  carrier_duty_percent: 100%

还有一个软件”hack” 允许无线电芯片将所有电压镜像到 ESP 上进行解码， 使硬件 hack 变得不必要。这种软件直通模式可用于 OB38S003（白色）和 EFM8BB1（黑色）sonoff RF 桥接器。然后为远程接收器/发射器 hub 使用此配置：

remote_receiver:
  pin:
    # sonoff 和 wemos 开发板
    number: GPIO3
    mode:
      input: true
      pullup: false
  tolerance: 60%
  filter: 4us
  idle: 4ms


remote_transmitter:
  pin: 1
  carrier_duty_percent: 100%

另请参阅

Section titled “另请参阅”