红外遥控接收器

功能与固件边界

IR_RECEIVER（type 53）通过接收头解码遥控器信号，支持学习按键并触发规则。当前实现只有接收功能，没有红外发射、发射引脚或载波频率配置；实际可解码的协议由构建中的 IRremoteESP8266 决定。

需要 FASTBEE_ENABLE_IR_REMOTE=1。当前标准构建矩阵中，esp32s3-F8R8 显式关闭红外并排除其依赖；esp32s3-F8R0、esp32s3-F16R8 及其余标准环境编入红外。不能把所有 S3 环境都视为关闭，也不能把编入驱动当成对应板卡已经通过接线、启动与接收验收。定制环境以实际构建配置为准，参见 构建配置。

接线与外设配置

先核对接收头型号、引脚顺序、供电和输出电平，再按目标板的引脚与资源校验结果选择 OUT 接收脚。下例的 GPIO15 仅为占位示例，不是所有 ESP32/C3/S3/C6 板卡的推荐或安全引脚。不得根据接收头正面外形推断引脚顺序。

接收头端子	连接要求
OUT	已确认空闲、支持输入且电平兼容的 GPIO
VCC	按接收头数据手册与板卡供电规格连接
GND	与控制器共地

在 Web 外设配置 中新增 红外接收头，填写唯一 ID、名称和一个接收引脚，确认接线与预检后再启用。此驱动通过 pins[0] 初始化，没有 params.driver、params.protocol 或 params.interval 设置。

以下对象供配置导入时参考；保持禁用，替换引脚并通过目标设备校验后再启用：

{
  "id": "ir_recv1",
  "name": "红外接收器",
  "type": 53,
  "enabled": false,
  "pins": [15],
  "pinCount": 1,
  "params": {}
}

学习按键

1. 登录后开启开发者模式，进入接收器的 红外管理 面板。
2. 启动限时学习，短按遥控器按键。Web 默认 10 秒；驱动将学习超时限制在 1~60 秒。
3. 捕获编码后填写按键名，例如 power、key1，保存并检查返回结果。
4. 在外设执行规则中选择 红外编码接收 事件，再选择已保存的按键。

按键名只允许字母、数字、下划线与短横线，长度 1~32，最多保存 40 个。同名保存用于替换映射。当前映射随 /config/periph_exec.json 的 irKeys 数组持久化；/config/ir_keys.json 仅属于旧版迁移输入，不是当前独立配置文件。详细流程见 示例21：红外遥控。

学习状态为 learning 时，捕获到的有效编码用于学习并结束本次窗口，不派发该次规则事件；捕获结束后恢复正常接收，后续按键可能触发已启用规则。保存或清空的 HTTP 成功响应不能替代重启后的持久化核验。

事件与匹配

正常接收到有效编码时，驱动派发内部事件 ir_code_received（事件枚举编号 125），事件数据示例：

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

key 仅在命中按键库时出现。驱动不自动按“外设 ID + 编码”的 MQTT 数据格式上报；实际动作和上报由匹配的外设执行规则决定。该事件目前是全局事件，载荷中没有接收器 ID，不能据此区分多个接收器来源。

compareValue	含义
key:power	按学习按键名匹配，大小写不敏感
NEC:0x00FF6897	限定协议与编码
0x00FF6897 或 00FF6897	按编码匹配，允许省略 0x
空字符串	不按编码过滤

按编码匹配时直接使用面板捕获的完整编码。匹配不会自动补齐缺失的前导零，不能把 0xFF6897 当作 0x00FF6897 的等价规则字符串。

规则示例

先配置并验证一个低压 LED 输出 led1，并学习名为 power 的按键。下面是用于规则导入的内容片段；规则保持禁用，目标类型、接线与动作校验通过后再启用。导入外壳和规则 ID 按目标设备的实际配置格式填写。

{
  "name": "遥控切换LED",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "ir_code_received",
      "operatorType": 0,
      "compareValue": "key:power"
    }
  ],
  "actions": [
    {"actionType": 30, "targetPeriphId": "led1"}
  ]
}

收到红外事件本身不授予目标输出额外权限。规则动作仍须通过对应目标的启用、配置、资源与输出来源检查；收到编码不等于 LED 或其他负载已产生物理动作。

接口权限与排查

所有红外接口都要求登录。开始学习、保存、删除和清空按键还要求开发者模式；当前取消学习接口只要求登录。接口清单见 红外示例。

接收失败时先检查驱动是否编入、外设初始化结果、实际接线、遥控器电池和环境光，再查看学习结果或接收日志。不要用固定距离、接收角度或通用 RMT 编译标志代替对应型号验证。

驱动过滤解码值 0 和 0xFFFFFFFFFFFFFFFF，并抑制 150ms 内的相同编码。这不保证所有遥控器长按都只触发一次；超过该间隔的有效重复编码仍可能进入规则。应在实际遥控器上验证所需的长按和重复动作行为。

学习、停止与保存失败

学习和接收器停止共享生命周期保护。状态接口中的 stopping=true 表示停止尚未完成；此时不能开始新的学习或重启接收器。停止会等待正在提交的解码事件结束后由管理器重试清理，不能把一次未完成的停止当作资源已释放。已经进入规则系统的事件不会由接收器停止自动撤销，目标动作仍按其自身的取消与资源检查执行。

按键保存、删除、清空都须先完成配置提交，再更新运行映射。写盘失败或并发配置发生变化时返回503，并保留原运行表；请重新读取按键库和错误后再处理。只有删除的名称确实不存在才返回404。不要把503当成“未找到”或已清空。

学习请求的 timeoutMs 为1000~60000的纯十进制整数，省略为10000；非法值返回400。接收器未就绪或正在停止时开始学习返回409。状态/按键快照暂时忙时返回503，不显示一组未确认的混合状态。

这些软件故障处理仍需对应固件的集中测试与实际设备验收。物理接收、长按规则行为和重启持久化尚不能仅凭本页或HTTP成功响应判为通过。

定制构建若保留红外而关闭外设执行功能，接收和学习仍可用；按键库与规则服务不可用，按键编辑返回503/IR_KEYS_STORE_DISABLED，不会存入另一份配置文件。