Home Assistant xiaomi_miio 红外遥控命令学习（Remote learn command）实战指南

Home Assistant xiaomi_miio 红外遥控命令学习（Remote learn command）实战指南

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

本指南以 Home Assistant 文档仓库中的xiaomi_miio.remote_learn_command动作文档为主体，系统讲解如何让小米（Chuangmi）红外遥控器进入学习模式、捕获实体遥控器发出的红外码，并将其保存到指定槽位以复用。读完本文，你将掌握通过可视化界面与 YAML 两种方式调用该动作、理解slot与timeout参数的真实含义，以及将学习到的红外码接入自动化、脚本和仪表盘按钮的完整流程。

动作定位：让小米红外遥控器“听懂”任何遥控器

Remote learn command（xiaomi_miio.remote_learn_command）是xiaomi_miio集成为 Xiaomi IR Remote（ChuangmiIr）设备注册的专用动作之一。它的作用是将红外遥控器切换为学习模式：动作触发后，把实体遥控器（例如电视、空调、机顶盒的遥控器）对准小米红外网关并按下按键，网关便会捕获该红外信号并解析成可存储的编码。学习完成后，Home Assistant 会在Overview（概览页）中以通知的形式展示学习到的命令内容，方便你直接复制进配置。

该动作的官方描述为：“Learns an IR command with a Xiaomi IR remote.”（使用小米红外遥控器学习一条 IR 命令）。它与通用动作remote.send_command（发送命令）形成闭环：先学习，后发送。

从集成文档可以看出，Xiaomi IR Remote 平台同时注册了“学习命令”与“控制遥控器 LED”两类小米专用动作（见 xiaomi_miio 集成文档 的 Xiaomi IR Remote 一节），其中学习相关的动作共有三个：

• xiaomi_miio.remote_learn_command：进入学习模式，捕获红外命令；
• xiaomi_miio.remote_set_led_on：打开遥控器蓝色状态 LED；
• xiaomi_miio.remote_set_led_off：关闭遥控器蓝色状态 LED。

前置条件：配置 Xiaomi IR Remote 平台

要使用该动作，首先需要让 Home Assistant 接入一台小米红外遥控器。xiaomi_miio集成的remote平台负责与设备通信，添加方式是在configuration.yaml中声明remote平台：

remote: - platform: xiaomi_miio host: 192.168.42.42 token: YOUR_TOKEN

其中host为遥控器的 IP 地址，token为通过米家 App 获取的 API 令牌（获取方法见 xiaomi_miio 集成文档 中的 Retrieving the Access Token 章节）。平台级配置还支持以下可选参数：

一个带名称、槽位与预置命令的完整配置示例：

remote: - platform: xiaomi_miio name: "bathroom remote" host: 192.168.42.42 token: YOUR_TOKEN slot: 1 timeout: 30 commands: activate_towel_heater: command: - raw:base64:[optional_frequency] read_bad_poem: command: - raw:base64:[optional_frequency] - pronto:pronto_hex:[optional_repeat]

注意：xiaomi_miio家族设备众多，请务必确认接入的确实是红外遥控器（ChuangmiIr）而非温湿度计、扫地机等其他设备。官方文档列出了至少 4 个可通过默认主机名识别的版本：chuangmi.ir.v2、chuangmi.remote.h102a03、chuangmi.remote.v2、chuangmi.remote.h102c01。其中 Pronto Hex 编码目前仅在第一版（chuangmi.ir.v2）上可用。

通过可视化界面学习一条命令

如果你习惯在界面中构建自动化与脚本，无需编写 YAML。按照动作文档给出的步骤操作即可：

1. 进入Settings>Automations & scenes（设置 > 自动化与场景）；
2. 打开一个已有的自动化或脚本，或者选择Create automation>Create new automation（创建自动化 > 创建新自动化）；
3. 如果新建的是自动化，需要在When（何时）区块添加触发器；脚本则不需要触发器——它们在被其他动作调用时才会运行；
4. 在Then do（然后执行）区块选择Add action（添加动作）；
5. 选择你要控制的对象：在By target（按目标，参见下方 Targets 一节）中选择要控制的小米红外遥控器；
6. 在目标对应的动作列表中，选择Remote learn command；
7. 可选地设置Slot（槽位）与Timeout（超时时间）；
8. 选择Save（保存）。

保存后运行该自动化或脚本，设备即进入学习模式：此时对准小米红外遥控器按下实体遥控器的按键，学习到的命令会以通知形式出现在 Overview 中。

界面中的选项

通过 YAML 调用动作

在 YAML 中（自动化、脚本或蓝图内部），该动作的引用名称为xiaomi_miio.remote_learn_command。动作文档给出的基础示例如下：

action: xiaomi_miio.remote_learn_command target: entity_id: remote.xiaomi_miio_remote data: slot: 1 timeout: 30

这段配置的作用是：让remote.xiaomi_miio_remote进入学习模式，将学习到的命令保存到槽位 1，并最多等待 30 秒。

YAML 中的参数

值得注意的一个细节：动作层面的timeout默认值是 10 秒，而平台配置层的timeout默认值是 30 秒。如果你在configuration.yaml中没有单独配置过超时，调用动作时又不显式传入timeout，实际等待学习的时间按 10 秒计；若要覆盖默认行为，请始终在动作数据中显式指定。

目标（Targets）的解析规则

该动作必须指定目标（target），目标即动作的作用对象。你既可以指向单个实体，也可以指向设备、区域、楼层或标签，Home Assistant 会对目标背后所有匹配的remote实体执行动作：

• Entity（实体）：某个具体的remote实体，例如remote.living_room；
• Device（设备）：某设备下所有的remote实体；
• Area（区域）：某个房间或区域内的所有remote实体；
• Floor（楼层）：某一楼层上的所有remote实体；
• Label（标签）：共享同一标签的所有remote实体。

你也可以在同一动作中混合多种目标类型，例如同时加入一个具体实体和一个区域，动作会同时作用于二者。

学习到的命令如何使用

学习动作本身只是“采集红外码”的第一步，真正发挥价值的是将采集到的编码喂给remote.send_command发送。集成文档对学习产物与发送机制给出了明确的说明。

学习结果的呈现

动作执行完成后，学习到的命令会以base64 字符串的形式作为通知显示在 Overview 中，你可以直接复制。集成文档在remote.send_command一节中明确指出：“To learn a new command, use the Remote learn command action. After learning, the base64 string is shown as a notification in Overview, where you can copy it.”

Raw 命令格式

remote.send_command支持两种命令格式，其中Raw格式正是由remote_learn_command学习得到的编码。它形如：

raw:Z6UFANEAAAAjAQAAAwkAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQIAE=

可选地，可以在末尾追加载波频率参数：

raw:Z6UFANEAAAAjAQAAAwkAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQIAE=:38400

Pronto Hex 命令格式

另一种格式是Pronto Hex，通常由设备厂商直接提供，无需学习。它的样子是：

pronto:0000 006C 0022 0002 015B 00AD 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0041 0016 0041 0016 0041 0016 0041 0016 0041 0016 0041 0016 0041 0016 0016 0016 0016 0016 0041 0016 0016 0016 0041 0016 0016 0016 0016 0016 0016 0016 0016 0016 0041 0016 0016 0016 0041 0016 0016 0016 0041 0016 0041 0016 0041 0016 0041 0016 0623 015B 0057 0016 0E6E

对于某些设备，可在末尾追加重复次数参数：

pronto:0000 006C 0022 0002 015B 00AD 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0041 0016 0041 0016 0041 0016 0041 0016 0041 0016 0041 0016 0041 0016 0016 0016 0016 0016 0041 0016 0016 0016 0041 0016 0016 0016 0016 0016 0016 0016 0016 0016 0041 0016 0016 0016 0041 0016 0016 0016 0041 0016 0041 0016 0041 0016 0041 0016 0623 015B 0057 0016 0E6E:2

槽位的复用特性

集成文档特别说明了一个容易被忽略的行为：学习到同一槽位的命令即使被覆盖，仍然可以通过remote.send_command发送。也就是说，槽位中保存的编码在后续学习中会被新编码覆盖，但旧编码只要你还保留着副本，就依然可用——这为在多个槽位间轮换、批量学习提供了灵活性。

将学习命令接入自动化与仪表盘

学习到编码后，最典型的落地方式有三种。

方式一：在脚本中定义具名命令并调用

script: towel_heater: sequence: - action: remote.send_command target: entity_id: "remote.bathroom_remote" data: command: - "activate_towel_heater"

这里command引用的是configuration.yaml中commands下定义的具名命令（如activate_towel_heater），也可以直接传入raw:...或pronto:...编码。

方式二：将具名命令绑定为仪表盘实体按钮

type: entity-button tap_action: action: call-service action: remote.send_command data: command: activate_towel_heater entity_id: remote.xiaomi_miio_ir hold_action: action: more-info show_icon: true show_name: true entity: remote.xiaomi_miio_ir icon: "mdi:radiator" name: Activate Towel Heater

方式三：完整的自动化闭环——先学习，后发送。例如在自动化中先触发学习动作把新遥控器的按键存入槽位，再通过remote.send_command立即复现该信号：

action: xiaomi_miio.remote_learn_command target: entity_id: remote.xiaomi_miio_ir data: slot: 1 timeout: 30

与相关动作配合使用

动作文档将以下两个动作列为与本动作协同使用的最佳拍档：

• Remote set LED on：打开小米红外遥控器的蓝色状态 LED，可用于学习或调试时确认设备在线；
• Remote set LED off：关闭蓝色状态 LED。

典型的调试流程是：先通过 LED 动作确认遥控器响应正常，再执行学习动作，等待 Overview 中的通知确认学习成功。

立即验证与排障建议

无需编写任何 YAML，你可以直接在Settings>Tools>Actions（设置 > 工具 > 动作）中搜索xiaomi_miio.remote_learn_command，填入字段并点击Perform action（执行动作），在真实实体上观察效果。

几个实用的排障思路：

• 学习超时（没有收到通知）：确认遥控器与手机/网关距离足够近、实体遥控器电量充足，并适当调大timeout（动作层默认仅 10 秒）；
• 学习成功但发送无效：检查学习时是否对准了红外发射口，必要时使用带频率参数的raw:...:38400格式重试；
• 多个遥控器并存：为每台设备分配独立的slot，避免不同设备的编码互相覆盖；
• Pronto Hex 无法发送：该格式目前仅支持chuangmi.ir.v2版本，其他版本请改用 raw 学习方式。

至此，你已经掌握了从设备接入、命令学习、编码理解到自动化落地的完整链路，可以开始把家中任何红外设备纳入 Home Assistant 的统一控制了。

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