示例21:红外遥控

fastbee大约 8 分钟

示例21:红外遥控

实验概述

通过红外接收器（如 VS1838B）接收红外遥控器信号，解码后触发设备动作。FastBee 在 Standard 固件（如 esp32-F4R0）和 esp32-F8R4 Full 固件中内置红外接收驱动，支持 NEC、RC5、SONY 等协议自动解码。

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

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

规则按按键名而非硬编码引用按键，因此更换任意品牌遥控器时，只需用相同的按键名重新对码，所有规则继续生效，无需修改任何规则。

配置 红外接收头（类型 53） 外设后，每次接收到按键编码都会派发 ir_code_received 事件，事件数据格式如下：

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

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

注意：红外遥控需要编译开关 FASTBEE_ENABLE_IR_REMOTE=1。ESP32-S3 Full 当前默认关闭该开关，优先使用 Standard 固件。
ESP32-S3 RMT 驱动配置：ESP32-S3 的 RMT 驱动存在新旧版本冲突问题。如在定制 S3 固件中启用红外，需要同时处理以下配置:
-DCONFIG_RMT_ENABLE=0
-DIR_USE_GPIO=1
如果使用其他环境需要红外功能,请确保添加以上编译标志。

硬件接线

开发板标识	GPIO引脚	连接设备
IR_RX	GPIO35	VS1838B 红外接收器（OUT引脚）

VS1838B 接线：VCC→3.3V, GND→GND, OUT→GPIO35。接收头为推挽输出，无需外接上拉电阻；推荐使用输入专用脚（GPIO35/36/39），也可使用其他空闲 GPIO。

JSON 配置示例

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

类型 53 为红外接收头，Web 页面新建外设时在类型下拉中选择 红外接收头 即可，无需额外参数。

红外对码（学习按键）

Web 操作步骤

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

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

学习状态说明

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

学习窗口期间不会派发 ir_code_received 事件，因此对码时不会误触发已有规则。

按键库规则

项目	说明
按键名	仅允许字母、数字、下划线、短横线，长度 1~32 字符
数量上限	最多 40 个按键，超出后需先删除再新增
同名覆盖	保存同名按键会覆盖原编码，这正是更换遥控器时的推荐做法
持久化	`/config/ir_keys.json`，结构为 `{"keys":[{"name","code","protocol"}]}`
迁移	该文件在配置导入/导出白名单内，可随设备配置 → 高级配置 → 导出/导入配置一同迁移到其他设备

外设执行联动

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

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

Web界面配置步骤

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

外设ID：led_d1
类型：GPIO输出

步骤2：创建规则

点击左侧菜单 外设配置 → 切换到 外设执行管理 标签
点击 新增规则 按钮
填写基础配置：
- 规则名称：红外控制LED
- 上报数据：✅ 启用
- 启用：✅ 启用

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

点击 添加触发 按钮

填写触发器配置：

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

步骤4：配置动作

点击 添加动作 按钮
填写：
- 动作类型：选择 切换电平
- 目标外设：选择 led_d1
点击保存按钮

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

功能：key1 开灯，key2 关灯

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

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

规则 遥控键1开灯：
- 触发器：事件触发 → 事件 红外编码接收 → 红外按键选 key1
- 动作：设置电平，目标外设 led_d1，值 0（低电平点亮）
规则 遥控键2关灯：
- 触发器：事件触发 → 事件 红外编码接收 → 红外按键选 key2
- 动作：设置电平，目标外设 led_d1，值 1

比较值（compareValue）三种写法

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

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

Web 表单只提供“选择已学习按键”这一种方式；后两种写法用于导入的 JSON 配置或历史规则，仍可正常匹配执行。

接口参考

红外管理面板通过以下接口与固件通信（均需登录；写操作还需开发者模式）：

方法	路径	说明
GET	`/api/ir/status`	初始化状态、学习状态、按键数量、最近一次编码
POST	`/api/ir/learn/start`	开始学习，参数 `timeoutMs`（默认 10000）
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）确认硬件链路是否正常。

注意事项

固件版本：使用 Standard 或 esp32-F8R4 Full；ESP32-S3 Full 当前默认关闭红外驱动
RMT 驱动兼容性：ESP32-S3 的 RMT 新驱动(driver_ng)与旧版 legacy driver 不可共存，定制启用前必须验证启动和解码稳定性
对码需开发者模式：学习、保存、删除、清空按键均为写操作，未开启开发者模式会被拒绝
更换遥控器：用相同的按键名重新对码覆盖即可，规则无需改动；若换用不同协议的遥控器（如 NEC → SONY），按键名匹配同样有效
学习不到编码：确认接线（OUT→GPIO35、VCC→3.3V，接反会导致无输出）、遥控器电池、正对接收头 20cm 以内短按；超时后可重新点击 开始学习
接收距离：VS1838B 典型接收距离 8-10m，需对准接收器
环境光干扰：强烈阳光或荧光灯可能干扰红外接收
协议支持：自动识别 NEC、RC5、RC6、SONY、Samsung 等协议；事件中的 protocol 字段为协议名，code 为十六进制编码
重复码与防抖：长按产生的 NEC 重复码固件已自动过滤，同时内置 150ms 防抖；外设执行的同一触发器还有 1 秒最小重复间隔，长按不会连续触发
无红外发射功能：当前仅支持接收/解码，不支持红外码发射