示例21:红外遥控

实验概述

通过红外接收器（如 VS1838B）接收红外遥控器信号，解码后触发设备动作。是否编入红外接收驱动取决于固件环境，实际协议由构建中的 IRremoteESP8266 决定。编入驱动不等于目标板已经完成接线与接收验收。

红外遥控采用通用对码方案，配置流程分两步：

1. 对码：在 Web 红外管理 面板中启动限时学习窗口，按下遥控器按键，把捕获到的编码保存为一个按键名（如 power、key1）。按键库随 /config/periph_exec.json 的 irKeys 数组持久化
2. 绑定：外设执行规则的触发器选择 红外编码接收（ir_code_received）事件，在 红外按键 下拉中选择已学习的按键即可

规则按按键名而非硬编码引用按键，因此更换为驱动可正确解码的遥控器时，可以用相同的按键名重新对码。保存成功后仍需验证原规则的匹配与重复触发行为。

配置 红外接收头（类型 53） 外设后，在正常接收模式下收到未被重复过滤的有效编码时会派发 ir_code_received 事件，事件数据格式如下：

{"protocol":"NEC","code":"0x00FF6897","bits":32,"key":"power"}

key 字段仅在该编码命中按键库中的某个按键时才会出现；未对码的按键只有 protocol / code / bits。

构建边界：需要 FASTBEE_ENABLE_IR_REMOTE=1。当前标准矩阵仅 esp32s3-F8R8 显式关闭红外并排除 IRremoteESP8266；esp32s3-F8R0、esp32s3-F16R8 及其余标准环境编入驱动。定制环境须检查实际构建配置与依赖，并验证启动、解码和并行外设共存；不要套用未在当前环境中定义的通用 RMT 编译标志。

事件来源边界：ir_code_received 是全局事件，载荷没有接收器 ID。驱动不直接产生“接收器 ID + 编码”的 MQTT 上报，规则决定后续动作和上报。

硬件接线

开发板标识	GPIO引脚	连接设备
IR_RX	GPIO35（仅为经典 ESP32 示例，需逐板核对）	红外接收器 OUT 信号

先依据实际接收头数据手册确认引脚顺序、供电、输出电平及是否需要上拉，再依据目标板的资源预检结果选择接收 GPIO。GPIO35/36/39 的能力和占用不是跨 ESP32/C3/S3/C6 通用结论；不得直接照搬到其他板卡。

JSON 配置示例

{
  "peripherals": [
    {
      "id": "ir_recv",
      "name": "红外接收头",
      "type": 53,
      "enabled": false,
      "pins": [35],
      "pinCount": 1,
      "params": {}
    }
  ]
}

类型 53 为红外接收头，驱动使用 pins[0]，无需额外参数。示例保持禁用；替换为经过目标板校验的实际 GPIO，确认接线后再启用。没有发射引脚、协议或载波频率参数。

红外对码（学习按键）

Web 操作步骤

1. 开启页面右上角的 开发者模式（对码、删除按键、清除全部均为写操作，需要此模式；打开面板本身属于查看操作）
2. 进入 外设配置 页面，在“红外接收头”所在行点击 红外管理 按钮
3. 在 对码 (学习按键) 区设置 学习超时 (秒)（默认 10 秒，可填 3~60 秒），点击 开始学习
4. 将遥控器对准接收头，按下要录入的按键；捕获成功后页面显示编码与协议
5. 在 按键名称 输入框填写名字（如 power、vol_up、key1），点击 保存按键
6. 重复 3~5 步录入其余按键；已保存的按键在下方 按键库 表格中列出，可单个删除或点击 清除全部

若面板顶部提示“红外接收头尚未初始化”，说明外设未启用或初始化失败，请先在外设管理中启用该外设。

学习状态说明

状态	含义	页面表现
idle	空闲	未进入学习窗口
learning	学习中	显示剩余倒计时，等待按键
captured	已捕获	显示编码与协议，可命名保存
timeout	超时	窗口内未收到有效编码，可重新点击 开始学习

学习状态为 learning 时，捕获的有效编码用于学习，不派发该次 ir_code_received 事件。捕获后状态变为 captured，接下来的按键恢复正常接收，可能触发已启用规则。不要把整个面板打开期间都当作动作隔离窗口。

按键库规则

项目	说明
按键名	仅允许字母、数字、下划线、短横线，长度 1~32 字符
数量上限	最多 40 个按键，超出后需先删除再新增
同名覆盖	保存同名按键会覆盖原编码，这正是更换遥控器时的推荐做法
持久化	当前保存在 /config/periph_exec.json 的 irKeys 数组中，每项含 name、code、protocol
迁移	旧 /config/ir_keys.json 是兼容迁移输入。迁移配置应保全当前 periph_exec.json，按实际导入结果核验映射与规则，勿手动恢复为旧独立文件

外设执行联动

场景1：任意按键控制LED（事件触发）

功能：任意红外按键按下时切换 LED 状态

Web界面配置步骤

步骤1：确保已配置LED外设

• 外设ID：led_d1
• 类型：GPIO输出

步骤2：创建规则

1. 点击左侧菜单 外设执行
2. 点击 新增规则 按钮
3. 填写基础配置：
   • 规则名称：红外控制LED
   • 上报数据：✅ 启用
   • 启用：✅ 启用

步骤3：配置触发器（事件触发）

1. 点击 添加触发 按钮

2. 填写触发器配置：

   字段	填写内容	说明
   触发类型	选择 事件触发	响应红外事件
   事件	选择 红外编码接收	即 ir_code_received
   红外按键	保持 -- 任意红外按键 --	留空表示收到任何红外编码都触发

步骤4：配置动作

1. 点击 添加动作 按钮

2. 填写：

   • 动作类型：选择 切换电平
   • 目标外设：选择 led_d1

3. 点击 保存 按钮

---

场景2：不同按键执行不同动作（按按键名）

功能：key1 开灯，key2 关灯

前置条件：已按上文完成对码，按键库中存在 key1、key2。

选择 红外编码接收 事件后，表单会出现 红外按键 下拉，自动从按键库加载已学习的按键（选项显示为“按键名 (编码)”）。创建两条规则：

1. 规则 遥控键1开灯：
   • 触发器：事件触发 → 事件 红外编码接收 → 红外按键选 key1
   • 动作：设置电平，目标外设 led_d1，值按已验证 LED 接线填写（仅当低电平点亮时使用 0）
2. 规则 遥控键2关灯：
   • 触发器：事件触发 → 事件 红外编码接收 → 红外按键选 key2
   • 动作：设置电平，目标外设 led_d1，值按已验证接线填写（仅当高电平熄灭时使用 1）

比较值（compareValue）三种写法

下拉选择后保存的 compareValue 形如 key:key1。固件同时兼容按编码匹配，便于直接编辑 JSON 或沿用旧规则：

写法	示例	说明
key:按键名	key:key1	推荐。按已学习按键名匹配（大小写不敏感），换遥控器无需改规则
协议:编码	NEC:0x00FF30CF	限定协议 + 编码，兼容旧规则
编码	0x00FF30CF 或 00FF30CF	任意协议 + 编码，0x 前缀可省，大小写不敏感
留空	—	任意红外编码均触发

Web 表单提供已学习按键选择；按协议或编码的写法可用于 JSON 配置或历史规则。编码比较不会补齐前导零，请照抄面板捕获的完整编码；0xFF30CF 不等同于 0x00FF30CF。

接口参考

红外管理面板通过以下接口与固件通信。所有接口均需登录；开始学习、保存、删除、清空还需开发者模式，当前取消学习只要求登录。

方法	路径	说明
GET	/api/ir/status	初始化状态、学习状态、按键数量、最近一次编码
POST	/api/ir/learn/start	开始学习，参数 timeoutMs（默认10000，纯十进制整数1000~60000，非法值返回400）
GET	/api/ir/learn/status	学习状态、剩余毫秒、捕获到的编码与协议
POST	/api/ir/learn/stop	取消学习
GET	/api/ir/keys	列出按键库
POST	/api/ir/keys	保存/覆盖按键，参数 name、code、protocol（可选）
POST	/api/ir/keys/delete	删除单个按键，参数 name
POST	/api/ir/keys/clear	清除全部按键

常见遥控器键值参考（NEC协议）

对码方式无需手填编码，下表仅供排查时对照（普中等常见小型 NEC 遥控器）：

按键	键值（缩写）	32位完整编码
1	0xFF30CF	0x00FF30CF
2	0xFF18E7	0x00FF18E7
3	0xFF7A85	0x00FF7A85
OK	0xFF02FD	0x00FF02FD
▲	0xFF629D	0x00FF629D
▼	0xFFA857	0x00FFA857

💡 提示：不同品牌遥控器键值不同，无需查表——直接用 红外管理 面板对码即可；也可在 系统日志 中查看实际解码结果（如 [IR] Received: NEC value=0x00FF30CF bits=32）确认硬件链路是否正常。

注意事项

1. 固件与硬件：核对实际环境的红外开关、接收头型号和 GPIO 占用，开启外设后确认初始化结果；构建成功不代表接收或物理动作通过。
2. 权限：开始学习、保存、删除和清空按键要求登录与开发者模式；当前取消学习只要求登录。
3. 保存与恢复：按键表与外设执行配置共同持久化。保存、删除或清空后检查接口与日志结果，并在恢复或重启验收中确认映射，不仅凭页面提示判定持久化成功。
4. 更换遥控器：用相同按键名重新对码后，验证协议解码、规则匹配与长按行为；不承诺支持任意品牌或任意协议。
5. 学习不到编码：核对接线、电源与输出电平、遥控器电池、朝向和环境光。接收距离与角度按实际接收头和遥控器验证，不采用统一固定数值。
6. 重复码与防抖：驱动过滤值 0 和 0xFFFFFFFFFFFFFFFF，并抑制 150ms 内的相同编码。该措施不是“长按永不连续触发”的保证，应在实际规则与遥控器上验收。
7. 无红外发射功能：当前仅接收和解码。学习/删除按键属于接收器与配置操作，不是红外发送命令；规则命中的目标输出仍须通过该目标的权限和资源检查。
8. 保存失败保全：保存、删除、清空先提交配置，再更新运行表。存储失败或并发源冲突返回503并保留原运行映射；delete只有确实不存在时返回404。失败后重新读取按键库，不根据按钮提示假定已修改。
9. 生命周期交错：stopping=true 时停止尚未完成，新的学习请求返回409。状态暂时忙时返回503。接收器的停止不自动撤销已经进入规则系统的事件，涉及负载的验收仍需确认目标规则的安全状态。

以上失败语义随对应固件变更验收；当前不能由此宣称接收硬件、物理动作或重启恢复已通过。