DAB-LABS/HAIR

# 头发 在 Home Assistant 中进行红外控制，过去意味着要选择您设备制造商的集成，期望其代码数据库包含您的设备型号，并且要么信任来自论坛的 JSON 文件，要么手动编写模板实体。捕获的信号存储在红外发射器上。用户则生活在 YAML 文件中。代码被 ***困在它们被学习的地方***：例如 Broadlink 应用程序的云端、供应商的中枢、或磁盘上的配置文件。 ***HAIR 将红外控制直接移入 Home Assistant。*** 将任何遥控器对准一个 ESPHome 红外接收器，按下按钮，HAIR 会将该信号转换为一个原生 HA 实体。一个可以从任何仪表板触发的按钮。一个 ***触发自动化流程*** 的事件。一个通过 HA 原生 `infrared` 平台上的任何红外发射器广播的命令，无论该发射器是 ESPHome 红外 LED、[Tuya Local](https://github.com/make-all/tuya-local) 红外发射器、Broadlink RM、SMLIGHT SLZB，还是采用该平台的任何其他设备。 无需选择制造商。无需查找型号。无需下载代码文件。无需编写 YAML。只需对准、按下、使用。 ### 红外平台兼容性 HAIR 可与任何暴露了 HA 原生 `infrared` 实体平台的集成配合工作。以下集成已采用该平台： | 集成 | 来源 | 发送 | 接收 | 状态 | |---|---|---|---|---| | [ESPHome](https://esphome.io/) | 核心 | 是 | 是 (桥接) | 自 2026.4 版起 | | [Tuya Local](https://github.com/make-all/tuya-local) | HACS | 是 | 否 | 自 2026.4 版起 | | [Broadlink](https://www.home-assistant.io/integrations/broadlink/) | 核心 | 是 | 否 | 自 2026.5 版起 | | [SMLIGHT](https://www.home-assistant.io/integrations/smlight/) | 核心 | 是 | 否 | 自 2026.5 版起 | 目前，只有 ESPHome 集成支持接收 (RX) 功能，使用的是一个临时的 YAML 桥接（见下方 [ESPHome 接收器设置](#esphome-receiver-setup)）。当 HA 原生 `InfraredReceiverEntity` 上线（预计在 2026.6 或 2026.7 版）后，任何采用它的集成都将自动作为 HAIR 接收器工作。 随着更多集成采用 `infrared` 平台，HAIR 无需自身进行任何更改即可自动支持它们。 HAIR 使用短/长脉冲持续时间 (S/L) 分析来为每个捕获的信号生成指纹。每个脉冲被分类为短或长，产生一个模式，该模式可以识别信号，而不会因按键之间的时间抖动而有所不同。S/L 技术适用于 NEC、三星、JVC、LG、索尼和 RC-5/RC-6 协议，无需解码协议本身。信号嗅探器 (Sniffer) 按源遥控器分组信号，对重复按键进行去重，过滤长按重复帧，并实时跟踪命中次数。 ## 截图 | 设备概览 | 设备详情 | |:---:|:---:| |  |  | | 动作映射 | 嗅探器 | |:---:|:---:| |  |  | | 分配信号 | 创建触发器 | 提升设备 | |:---:|:---:|:---:| |  |  |  | ## 要求 - Home Assistant **2026.4** 或更高版本 - Python 3.12+ - **用于捕获 (RX)：** 一个带有 [`remote_receiver`](https://esphome.io/components/remote_receiver.html) 组件的 ESPHome 设备（临时 YAML 桥接设置参见 [ESPHome 接收器设置](#esphome-receiver-setup)） - **用于发送 (TX)：** 至少一个采用 HA 原生红外平台的集成（ESPHome 红外实体、[Tuya Local](https://github.com/make-all/tuya-local) 红外发射器、Broadlink RM 系列等） ## 安装 ### HACS（推荐） 1. 在您的 Home Assistant 实例中打开 HACS 2. 进入 **集成** 3. 点击三点菜单 > **自定义存储库** 4. 添加 `https://github.com/DAB-LABS/HAIR`，类别选择 **集成** 5. 搜索 “HAIR” 并安装 6. 重启 Home Assistant ### 手动安装 1. 将 `custom_components/hair` 复制到您 HA 的 `custom_components/` 目录下 2. 重启 Home Assistant ## 设置 1. 进入 **设置 > 设备与服务** 2. 点击 **添加集成** 并搜索 “HAIR” 3. 配置流程会自动检测您的红外硬件（发射器和接收器） 4. 添加后，在侧边栏中找到 **HAIR** ### ESPHome 接收器设置 HAIR 的嗅探器需要将红外信号发送到 HA 事件总线上。HA 2026.4 版推出了用于发送 (TX)（发射器）的 `infrared` 平台，但接收 (RX) 端（`InfraredReceiverEntity`）尚未可用。该功能已获批准，并列入 HA 路线图，预计在 2026.6-2026.7 版实现（架构讨论 #1372）。在此之前，ESPHome 设备需要一个小型 YAML 桥接，将接收到的信号转发给 HA。 将以下内容添加到您的 ESPHome 设备的 `remote_receiver` 块中： ``` remote_receiver: id: ir_receiver pin: number: GPIO5 # your IR receiver data pin inverted: true dump: pronto on_pronto: then: - homeassistant.event: event: esphome.remote_received data: protocol: "PRONTO" code: !lambda 'return x.data;' ``` `on_pronto` 触发器捕获所有红外信号，无论其协议（NEC、三星、索尼、RC-5 等），并将其作为 `homeassistant.event` 发送到 HA 事件总线上。HAIR 的信号监视器 (Signal Monitor) 会自动订阅这些事件。 此桥接是临时的。当 HA 上线 `InfraredReceiverEntity` 时，HAIR 将迁移到官方的 `infrared.async_subscribe_receiver()` API，届时将不再需要 ESPHome YAML 自定义配置。现有的 `ir_rf_proxy` 发送 (TX) 配置不受此更改影响。 如需现成的、经过 HAIR 测试的常见 ESP32 开发板和红外设备配置，请参阅此仓库中的 [`esphome/`](esphome/) 目录。 ## 功能 **信号嗅探器** - 后台运行的被动红外监听器。您的接收器检测到的每次红外传输都会被捕获、生成指纹，并按源设备分组。信号会自动去重：按同一个按钮十次，您只会看到一个命中次数为十的信号。长按按钮时发送的重复帧会被过滤掉，因此只会显示实际的命令信号。嗅探器会实时显示您家中哪些遥控器正在活跃以及哪些按钮正在被按下。 **设备管理** - 为您的红外控制设备（电视、空调、风扇、灯、开关、屏幕）创建配置文件。从设备类型感知的模板列表中选择已学习的信号作为命名命令，或输入自定义名称。每个设备会根据其类型自动生成原生 HA 实体。 **动作映射** - 通过弹出窗口界面显式地将红外命令绑定到 HA 实体功能。当您将某个命令映射到“音量增加”时，media_player 实体就知道在 HA 调用音量服务时使用该命令。只有当命令被映射后，相应的功能才会暴露出来，从而使您的实体保持简洁。 **触发器** - 将任何红外信号转换为原生 HA 事件实体。从已学习的设备命令或从嗅探器中的未知信号创建触发器。每个触发器都会在一个虚拟的“HAIR Triggers”设备下获得一个 `event` 实体，每当接收到匹配信号时，就会触发一个 `ir_command_received` 事件。使用触发器可以构建响应物理遥控器按键的 HA 自动化流程（例如，按下电视电源按钮同时关闭房间灯）。可配置的“最小命中次数”阈值（最小按键次数）允许您要求在 5 秒窗口内进行多次按键后才触发，这有助于防止意外激活。“设备”选项卡显示所有活动的触发器，并带有实时触发动画。 **发射器路由与广播控制** - 为每个设备分配一个或多个红外发射器，并显式控制命令的广播方式。将设备锁定到单个发射器以实现房间范围控制（例如，将空调绑定到卧室发射器，这样命令永远不会泄露到客厅），或分配多个发射器进行广泛广播（单个“电视电源”命令同时通过所有房间的发射器发射）。路由是按设备配置的，因此您可以将某些设备的严格按房间定向与其他设备的全屋广播混合使用。 **命令模板** - 引导式设置会根据设备类型建议要捕获的命令。从预定义名称中选择（开机、音量增加、模式：制冷等），或为列表中未包含的任何命令输入自定义名称。 ## 使用 HAIR ### “设备”选项卡 主视图包含五个部分： **HAIR 设备** - 您管理的红外设备配置文件。每个卡片显示设备名称、类型、命令数量以及分配了多少个发射器。点击设备可展开其内联详细视图，在这里您可以更改设备类型、管理发射器，并查看所有已学习命令及其 S/L 菱形指纹模式。在此处您可以测试命令、删除命令或分配动作映射。 **触发器** - 当检测到其信号时触发 HA 事件实体的活动红外触发器。每个触发器卡片显示触发器名称和一个闪电图标。当触发器触发时，卡片会以琥珀色发光动画实时闪烁。 **发射器** - 您的红外发射器硬件（例如，ESPHome 红外实体、Tuya Local 红外发射器）。这些是发送命令的实体红外 LED。每个发射器卡片显示其实体 ID 和一个 TX 徽章。 **接收器** - 您的红外接收器硬件。这些设备将捕获的信号馈入嗅探器。每个接收器卡片显示其来源集成和一个 RX 徽章。 **代理** - 同时具有发送 (TX) 和接收 (RX) 功能的硬件设备。一个带有红外 LED 和红外接收器的 ESPHome 开发板会同时显示 TX 和 RX 徽章。 ### “嗅探器”选项卡 嗅探器是一个被动监听器，显示您的接收器接收到的每个红外信号。信号按源设备（通过载波频率和前导码指纹识别）分组显示，并带有命中次数、信号计数和最后活动时间戳。 每个源设备行都可以展开，显示其单个信号的 S/L 菱形指纹。在此处，您可以直接将信号分配给 HAIR 设备作为命名命令，或者将未知的源设备提升为完整的 HAIR 设备配置文件。在提升之前，点击源设备行上的铅笔按钮为其指定自定义名称——否则新设备将继承自动生成的源名称（例如，“未知遥控器 1”）。先设置名称意味着提升后的设备会以您想要的标签出现在“设备”选项卡中。 已被 HAIR 管理的设备会标有“HAIR 设备”徽章。您可以忽略嘈杂的源（例如，邻居的遥控器信号从窗户泄露进来），并稍后通过“显示已忽略”切换按钮将其恢复。 ### 添加设备 有两种添加设备的方法。 **从头开始：** 在“设备”选项卡的选项卡栏中点击“添加设备”按钮。输入名称，选择设备类型，并选择哪些红外发射器应为该设备广播命令。HAIR 会立即创建设备配置文件和相应的 HA 实体。 **从嗅探器（提升未知源）：** 当 HAIR 检测到它无法识别的遥控器时，它会作为未知源设备出现在嗅探器中。首先点击源行上的铅笔按钮为其指定自定义名称，然后将其提升为完整的 HAIR 设备。在提升前设置名称意味着您的新设备会以您想要的标签出现在“设备”选项卡中，而不是继承自动生成的“未知遥控器 N”名称。当您手头有物理遥控器并希望首先捕获其信号时，此路径非常理想。 ### 学习命令 导航到“嗅探器”选项卡，并按下物理遥控器上的按钮。HAIR 实时捕获每个信号。展开源设备行，然后点击信号以将其分配给您的某个 HAIR 设备。从设备类型感知的模板列表中选择命令名称（例如，“开机”、“音量增加”、“模式：制冷”）或输入自定义名称。 ### 动作映射 学习命令后，打开设备的详细视图，并点击任何命令行上的“ACTIONS”徽章。一个弹出窗口显示该设备类型的所有可用操作。选择一个操作以将其绑定到该命令。例如，将“开机”映射到 `turn_on` 操作意味着 HA 的 media_player 的电源按钮将触发该红外命令。已映射到其他命令的操作会显示其当前分配，以便您可以单击重新分配。 ### 触发器 触发器允许您将传入的红外信号用作 Home Assistant 中的自动化触发器。有两种创建触发器的方法。 从设备命令：在“设备”选项卡中展开一个设备，并点击任何命令行上的触发器按钮。这会创建一个链接到该命令信号的触发器。如果该命令已存在触发器，该按钮将改为在编辑模式下打开触发器。 从嗅探器：展开一个未知设备，并点击任何信号行上的触发器按钮。这会根据原始信号指纹创建一个触发器，适用于您希望对其做出响应但不分配给 HAIR 设备的信号。 每个触发器都有一个可配置的“最小命中次数”值（最小按键次数，1 到 10），用于控制信号必须在 5 秒窗口内被接收多少次后才会触发。将其设置为 2 或 3 有助于防止触发器因误触或意外按键而触发。 活动触发器出现在“设备”选项卡底部的“触发器”部分。当触发器触发时，其卡片会以琥珀色发光动画闪烁。每个触发器都会创建一个 `event` 实体（例如，`event.hair_triggers_tv_power`），您可以直接在 HA 的自动化编辑器中将其用作触发条件。 ## 实体平台 设备会根据其类型自动生成原生 HA 实体： | 类型 | HA 实体 | 控制功能 | |------|-----------|----------| | 媒体播放器 | `media_player` | 电源、音量、静音、信号源、频道、导航、播放控制 | | 空调 | `climate` | HVAC 模式、温度预设、风扇模式 | | 风扇 | `fan` | 电源、风速档位、摆风 | | 灯 | `light` | 开关、亮度档位 | | 开关 | `switch` | 开关 | | 屏幕 | `cover` | 打开、关闭、停止 | | 其他 | `remote` | 通用红外命令发送器 | 每个设备还会获得一个用于发送任意 Pronto 十六进制代码的 `remote` 实体，以及一个用于每个已学习命令的 `button` 实体。这些 button 实体让您可以通过仪表板、自动化或脚本一键访问任何红外命令，无论设备类型如何。 触发器会在一个共享的“HAIR Triggers”设备下创建 `event` 实体。每个触发器实体在检测到其信号时会触发一个 `ir_command_received` 事件，使其可以作为 HA 自动化编辑器中的自动化触发器。 实体功能由显式的动作映射驱动。media_player 只有在您将命令映射到音量操作时才会暴露音量控制。这使您的实体保持简洁，并避免暴露遥控器不支持的功能。 ## 工作原理 HAIR 位于您和 HA 的红外平台之间。它不会取代您的红外硬件集成（ESPHome、Tuya Local、Broadlink 等）。它通过提供这些集成所缺乏的管理层来补充它们。 ### 捕获 (RX) HAIR 通过带有 [`remote_receiver`](https://esphome.io/components/remote_receiver.html) 组件的 ESPHome 设备捕获红外信号。目前这是一个遗留的事件总线桥接（YAML 桩代码参见上方的 [ESPHome 接收器设置](#esphome-receiver-setup)）。当 HA 的原生红外接收实体上线（预计在 2026.6 或 2026.7 版）后，HAIR 将自动为用户迁移，届时将不再需要 YAML 桥接。 ### 发送 (TX) HAIR 通过任何暴露了 HA 原生 `infrared` 平台的集成发送红外信号。目前包括 ESPHome、[Tuya Local](https://github.com/make-all/tuya-local)、Broadlink、SMLIGHT 以及其他采用该平台的集成。 ### 信号指纹识别 捕获的红外信号使用 S/L（短/长）脉冲持续时间分类生成指纹。信号中的每个脉冲被分类为短或长，产生一个唯一的模式，该模式可以识别信号，而不会因按键之间的时间抖动而有所不同。在 UI 中，这些模式显示为双色调的菱形序列，以便快速视觉识别。 S/L 指纹识别涵盖了所有主要的消费类红外协议，包括 NEC、三星、JVC、LG、索尼和 RC-5/RC-6。长按发送的重复帧会被自动过滤。信号通过载波频率和前导码分析按源设备分组，因此嗅探器无需解码具体协议即可知道信号来自哪个遥控器。 ### 架构 ``` Remote Control | IR Receiver (ESPHome remote_receiver) <-- RX path: ESPHome only | HA Event Bus (esphome.remote_received) | HAIR Signal Monitor --> Signal Store (fingerprint + dedup) | | | Trigger Manager --> Event Entities (HA automations) | HAIR Admin Panel (Sniffer view) | Assign to Device --> Device Manager --> Entity Factory | HA Entities (media_player, climate, fan, light, switch, cover, remote, button) | HA infrared Platform (infrared.send_command) <-- TX path: any platform integration | IR Emitter Hardware (ESPHome, Tuya Local, Broadlink, etc.) ``` ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ## 许可证 MIT 许可证。详情参见 [LICENSE](LICENSE)。

标签：Broadlink, ESPHome, GUI管理界面, Home Assistant, SMLIGHT, Tuya Local, 家居自动化, 智能家居, 智能家居遥控, 物联网, 红外信号学习, 红外平台, 红外控制, 红外遥控器, 自动化场景, 自动化触发, 设备管理, 逆向工具, 遥控器学习