RT-Thread 红外框架 IF 重构:从单设备 NEC 解码到多实例收发,原理、优化与使用指南

摘要:RT-Thread Infrared Framework 新增多实例 FRAMEWORK 模式,保留旧版 LEGACY 接口,解耦红外采样、NEC 编解码和 PWM 发送。基于 master 源码介绍重构收益、通信原理、配置方法与应用示例。

在这里插入图片描述

[TOC]

一次重构,让红外收发从“单套驱动”走向可复用设备框架

IF(Infrared Framework)是运行于 RT-Thread 的红外收发软件包,用于把 MCU 的 GPIO、定时器、Input Capture、PWM 等驱动组合起来,完成红外遥控信号的接收、协议解码与发送。典型用途包括遥控器按键接收、设备红外控制、家电遥控指令转发和嵌入式红外协议实验。它处理的是红外遥控的脉冲与协议帧,不是 IrDA 文件传输或通用串口通信。

仓库已在 infrared_framework 的 master 分支提供新一轮框架扩展。原有单设备实现没有被直接删除,而是保留为 LEGACY;新的多实例框架通过 FRAMEWORK 模式独立编译。 本文以 2026 年 11 月 15 日核对的 master 提交 2828de15c386db5e7f2b6034b95fdbeb9aaa7e56 为技术基线,下面的接口、配置和示例均以该版本为依据。[S1]

新框架面向的不是“让一颗红外接收头多出几个功能”,而是让多个红外逻辑设备能够使用相同 API,并把硬件采样、红外协议、上层业务分离。需要接收的设备可以配置 PIN/HWTIMER 或 Input Capture,发射端可以配置 PWM/HWTIMER;每个实例拥有自己的协议状态和帧数据。[S3][S4]

IF 到底在处理什么:红外遥控的物理信号与协议帧

红外遥控通常由红外发光二极管发射调制光信号,接收端通过红外接收头对载波进行接收和解调,输出能供 MCU 识别的脉冲电平。为了区分信号与环境光干扰,常见遥控方式会采用约 38 kHz 的载波;这不是每种红外协议、每种接收模块都必须采用的固定频率。当前 PWM 后端设置的目标载波周期为 26316 ns,对应约 38 kHz,属于本软件包的默认实现参数,而非实板测量值。[S4]

理解红外控制,首先区分两个层次:

  • 载波:红外 LED 快速开关形成的高频光信号;PWM 适合产生这一层的周期波形。
  • 包络(Envelope):载波发射一段时间、关闭一段时间,形成 MARK(有载波)与 SPACE(无载波)的交替时长;这些时长才用于表达协议中的引导码、数据位和重复帧。

接收头往往输出已经解调的逻辑电平,因此 GPIO 上的高电平或低电平不等于“协议逻辑 1 或 0”。接收电平的有效极性由 active_level 配置,输入后端将边沿间隔换算成 MARK/SPACE 时长,再交给 Codec(编码器/解码器)。[S4]

1
2
3
4
5
6
7
flowchart LR
A["遥控器红外光"] --> B["接收头解调"]
B --> C["PIN/HWTIMER 或 Input Capture"]
C --> D["原始脉冲队列"]
D --> E["应用 Poll 或 Event 工作线程"]
E --> F["NEC Codec"]
F --> G["完整协议帧 / 应用"]

用 NEC 协议看懂一条指令

NEC 是本框架已提供的红外协议实现之一。以源码中的标准 NEC 帧为例,一次正常指令包含约 9000 μs 的引导 MARK 和 4500 μs 的引导 SPACE,随后传输 32 个数据位;每个数据位有约 560 μs 的 MARK,SPACE 约为 560 μs(逻辑 0)或 1690 μs(逻辑 1)。解码器还会检查地址与命令各自的反码字节,以判断完整命令是否有效。[S5]

当前 NEC Codec 对应用输出的完整帧是一个 struct infrared_frame,其中 length=3 时:

字段 意义 示例
data[0] 地址 0x12
data[1] 命令 0x34
data[2] 已识别的重复次数 0 表示普通新命令

这三个字节是软件包提供给应用的解码结果,不是直接复刻的 32 位原始波形。NEC 发送时,Codec 根据地址与命令构造反码并转换为一组 MARK/SPACE 时间段;当前实现对一个正常帧生成 68 个包络段,并支持附加重复包络,最大重复次数按源码限制为 8。它面向当前实现的标准 NEC 格式,不代表自动兼容所有 NEC 扩展变体。[S5]

在软件内部,每个原始包络记录使用 infrared_pulse_t(32 位):高四位 0xA 表示 MARK、0xB 表示 SPACE,低 28 位保存微秒时长。这里的 0xA/0xB 是内部标记,不是 GPIO 实际高低电平,也不是空中传输的报文头。[S3]

为什么要重构:旧的单实例设计遇到了什么限制

原有 LEGACY 实现通过单个全局 infrared_class 管理当前 Decoder、Decoder 表和接收 Ringbuffer。应用使用 infrared_init()、infrared_read()、infrared_write()、ir_decoder_register() 等接口。采样驱动调用 driver_report_raw_data() 上报脉冲后,会直接调用当前 Decoder 的 decode()。这种设计适合简单的单路红外遥控接收,但设备数量与业务复杂度增长后,状态所有权容易聚集在同一组全局对象里。[S2]

新框架没有要求旧应用一次性迁移:Kconfig 提供互斥的 INFRARED_LEGACY、INFRARED_FRAMEWORK,默认仍为 LEGACY。SConscript 根据模式编译不同目录,不共享同一个运行期实例表和解码器对象。因此,旧 API 仍然可用,不等于两种模式能够同时编译,或者旧 API 自动具备多实例语义。[S1][S2]

比较维度 原有 LEGACY 新 FRAMEWORK
设备组织 全局红外对象、单套接收/发送驱动状态 显式索引注册多个独立 infrared_device
协议选择 当前 Decoder 选择与全局表 注册时绑定每实例 Codec 与独立上下文
接收处理 脉冲上报路径直接触发解码 ISR/驱动先采集,应用线程 poll() 再解码
输入适配 原有 PIN/HWTIMER 路径 PIN/HWTIMER 或 RT-Thread Input Capture 二选一
发送适配 固定 PWM/HWTIMER 驱动 后端操作表 + 后端持有的稳定发送缓冲
交付给应用 原有解码器专用数据接口 统一的完整帧及 rt_device_read/write
配置和资源 面向单套设备与驱动 多设备容量、独占检查、按后端裁剪
迁移方式 继续使用旧 API 显式启用 FRAMEWORK、配置或注册设备

上述差异来自当前两套源码的结构与 API,并非量化的吞吐量、CPU 占用或 RAM 基准测试结果。[S2][S3][S4]

新框架做了哪些实质优化

1. 多实例:固定索引,不再依赖“全局当前设备”

infrared_device_register() 按应用指定的 index 注册逻辑设备,infrared_device_get() 根据索引访问。INFRARED_MAX_DEVICES 可配置为 1~16,默认 3,但它仅代表注册表容量,不会自动创建同等数量的设备。例如可以只注册索引 1 而不注册索引 0;索引不会因注册顺序改变。[S3][S6]

每个实例可以只接收、只发送,也可以同时配置收发。接收 Codec 保持各自的 NEC 解析状态与重复历史;不同设备不会再依赖同一个全局“当前 Decoder”。对需要多个红外输入或输出的控制板,这改变了扩展设备时的基本组织方式。[S3][S5]

2. 硬件后端与协议 Codec 解耦

infrared_backend_ops 让框架通过统一操作表调用物理输入/输出;infrared_codec_ops 则定义 reset、decode、encode 等协议操作。输入采样只需要产出时长和 MARK/SPACE,后续如何识别 NEC 命令由 Codec 决定。[S3][S4]

新实现包括 PIN + HWTIMER 接收、Input Capture 接收、PWM + HWTIMER 发射以及 NEC Codec。还提供可选的通用 pulse-distance(脉冲距离编码)辅助模块,用于其他采用相近包络形式的自定义 Codec;它不代表软件包已经内置所有遥控协议。扩展新协议仍需实现 Codec,并在设备注册时绑定,当前不支持运行期动态切换 Codec。[S3][S5]

3. 中断只采样,协议解析转到应用上下文

PIN 边沿中断计算脉冲宽度并放入原始 Ringbuffer;Input Capture 则从 BSP 驱动内部缓冲读取采样。框架核心中的 infrared_device_poll() 每次至多取一条原始脉冲,调用对应 Codec 的 decode(),仅当构成完整帧后才将结果交给应用。[S3][S4]

应用可以周期轮询,也可以使用示例中的一个 RT-Thread Event 工作线程:中断只发送“有数据”通知,工作线程收到设备对应的事件位后再执行 Poll。框架核心本身不会创建后台线程;事件线程是 INFRARED_USING_THREAD_EXAMPLE 控制的可选示例。解析工作从 IRQ 上报路径解耦,有助于控制 ISR 的职责,但并不意味着硬件中断次数自动减少。[S3][S6]

完成帧支持两种交付方式:帧队列和同步帧回调。infrared_device_set_frame_callback() 设置的帧回调运行于调用 poll() 的线程,而不是硬件中断中;不启用帧回调时,完整帧进入每实例 Ringbuffer,可通过 infrared_device_read_frames() 或 RT-Thread read 读取。[S3]

4. 发送缓存、计时和资源所有权更明确

发送方向先由 Codec 把完整协议帧编码成 MARK/SPACE 时长数组,PWM 负责产生 MARK 期间的载波,HWTIMER 以一次性计时器控制每个包络段,并通过中断推进后续段。发送线程等待 Completion,结束时关闭输出并获取发送结果。[S3][S4]

1
2
3
4
5
6
flowchart LR
A["应用提交完整帧"] --> B["Codec 编码脉冲"]
B --> C["后端稳定脉冲数组"]
C --> D["HWTIMER 包络计时"]
D --> E["PWM 载波开关"]
E --> F["红外 LED 发射"]

发送缓冲由 PWM 后端状态持有,不是要求另一生产者持续填充的 TX Ringbuffer。框架也检查设备资源归属:同一 PWM 通道不能被不同实例重复占用;同一 PWM 设备的不同通道可以共享,但载波周期需一致;RX 和 TX 物理 HWTIMER 不应被多个逻辑实例重用。[S3][S4]

infrared_device_write_frames() 返回的是完成发送的协议帧数,不是负错误码;部分失败需结合返回数量与日志判断。timeout_ticks=0 或 RT_WAITING_FOREVER 表示无限等待,正值表示有限 Tick 超时。异常关闭仅尽力执行一次清理,硬件未确认停机时不会擅自复用占用资源。这些是清晰的失败边界,而不是自动恢复或重试的承诺。[S3][S4]

5. 按需选编和静态容量,有利于嵌入式资源预算

Kconfig 可以单独打开 PIN、Capture、PWM、NEC、诊断、MSH 或示例线程;SConscript 只选入需要的源码。逻辑设备容量、原始脉冲队列、完整帧队列、发送脉冲数组和 NEC 上下文数量分别可配置。部分框架缓冲来自按启用实例数预留的静态池,便于在编译期估算资源。[S1][S6]

这不等于“整个框架完全不用 Heap”:Input Capture 适配器在目标 RT-Thread 驱动中可能需要 Heap,示例线程也需要线程控制块及栈等资源。最终 RAM 大小依赖具体配置、sizeof() 对齐与 BSP,不能仅凭代码结构声称较旧版节省了固定百分比内存。[S4][S6]

怎样接入 RT-Thread 并让第一条 NEC 指令跑通

第一步:确认使用的是新源码及其 Kconfig

推荐从项目仓库的 master 分支和仓库内的配置与移植说明开始。master 的 Kconfig 在 PKG_USING_INFRARED 下提供互斥的 LEGACY/FRAMEWORK 选择,默认是 LEGACY;要使用新功能,必须显式切到 FRAMEWORK。[S1][S6]

集成提示: 截至本文核对时,RT-Thread/packages 官方索引的 peripherals/infrared/Kconfig 仍是旧版菜单,未包含新的模式选择。因此仅在常规在线软件包菜单中勾选 infrared,不保证已经启用新框架。工程必须让 infrared_framework 的目标源码和对应新 Kconfig/SConscript 一同参与配置与构建;不要把旧索引配置和新源码混合后直接假设可用。项目是 RT-Thread 软件包而非独立 BSP,编译应从目标 BSP 的 SCons 入口发起。[S1][S7]

第二步:选择硬件驱动和一个 NEC 实例

在工程的 menuconfig 中选择以下配置方向,具体菜单会随 RT-Thread 版本变化:

目标 相关配置 前提
启用新框架 INFRARED_FRAMEWORK=y 与 LEGACY 互斥
接收方式一 INFRARED_DEVICE_PIN=y RT_USING_PIN、RT_USING_HWTIMER
接收方式二 INFRARED_USING_INPUT_CAPTURE=y RT_USING_INPUT_CAPTURE、RT_USING_HEAP
红外发送 INFRARED_DEVICE_PWM=y RT_USING_PWM、RT_USING_HWTIMER
NEC 编解码 INFRARED_FRAMEWORK_NEC_CODEC=y 为启用的接收实例预留 NEC 上下文
快速体验 INFRARED_USING_EXAMPLE=y 选择一个 Kconfig 示例槽位,如 ir0
自动接收处理 INFRARED_USING_THREAD_EXAMPLE=y 还需 RT_USING_EVENT、Heap 与组件初始化
串口交互 INFRARED_USING_MSH=y MSH、诊断组件已启用

对于一个只接收 NEC 的最小应用,选择 PIN + HWTIMER 或 Input Capture 中的一种即可;不需要同时启用 PWM 发射。例子中的 timer16、timer15、pwm4、GPIO 编号只是配置默认值,必须核对目标 BSP 已注册的物理设备、计时器能力和引脚连接,不能照搬当成板卡承诺。[S6]

INFRARED_USING_EXAMPLE 的设备注册发生在 INIT_APP_EXPORT(infrared_example_init),只会注册实际启用且已配置 Codec 的槽位。仅启用示例而不开启线程时,应用还需自行打开设备并调用 poll();开启示例事件线程后,它负责打开并轮询这些实例,不应再启动第二个线程竞争同一实例的 Poll。[S6]

第三步:先用 MSH 查看与发送指令

启用示例设备、MSH,以及相应的收发硬件后,可使用以下命令。N 是实例固定索引,以下使用 0:

1
2
3
4
5
6
ir help
ir list
ir info 0
ir codec list
ir codec nec read 0
ir codec nec tx 0 12 34 0

其中 ir codec nec tx 0 12 34 0 表示向设备 0 发送地址 0x12、命令 0x34、不附加重发的 NEC 指令;要求该设备配置了 PWM 发送后端,且处于已打开状态。命令是否真正发出红外光还取决于 BSP 设备、PWM/HWTIMER 及红外 LED 驱动电路。[S6]

手动轮询场景还可以使用 ir open 0、ir poll 0、ir read 0。需要注意,一次 ir poll 至多处理一条原始脉冲,而一个完整 NEC 命令包含多条脉冲;单次 Poll 没有读到完整帧不是异常。实际应用更适合使用自己的轮询任务或框架提供的可选 Event 示例。[S3][S6]

第四步:应用通过帧接口收发

如果已经通过 Kconfig 示例注册了索引 0,且未启用自动事件线程,应用可在自己的接收任务中执行如下代码。代码展示完整帧消费的最小调用关系;线程创建、BSP 设备注册、配置选项和异常策略由实际项目负责,尚未针对指定目标板编译。[S3][S6]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
#include <rtthread.h>
#include <rtdevice.h>
#include "infrared_device.h"

static void ir_receive_task(void *parameter)
{
struct infrared_device *ir = infrared_device_get(0);
struct infrared_frame frame;
rt_device_t rtdev;
rt_err_t result;
(void)parameter;

if (ir == RT_NULL)
return;

rtdev = infrared_device_rt_device(ir);
if (rt_device_open(rtdev, RT_DEVICE_OFLAG_RDWR) != RT_EOK)
return;

for (;;)
{
result = infrared_device_poll(ir);
while (infrared_device_read_frames(ir, &frame, 1) == 1)
{
if (frame.length == 3)
{
rt_kprintf("NEC addr=%02X cmd=%02X repeat=%u\n",
frame.data[0], frame.data[1], frame.data[2]);
}
}
if (result != RT_EOK && result != -RT_EEMPTY && result != -RT_EFULL)
{
rt_kprintf("infrared poll error: %d\n", result);
}
rt_thread_mdelay(2);
}
}

对于已经打开并配置 PWM 发射的实例,发送一个 NEC 帧的应用写法可以简化为:

1
2
3
4
5
6
7
8
struct infrared_frame tx = {0};
tx.length = 3;
tx.data[0] = 0x12; /* NEC address */
tx.data[1] = 0x34; /* NEC command */
tx.data[2] = 0; /* repeat count */

/* Return value is completed frame count, not bytes or a signed errno. */
rt_size_t sent = infrared_device_write_frames(ir, &tx, 1);

上面的 ir 必须是有效、已打开并具有发送后端的设备句柄,发送必须在允许等待 Completion 的线程上下文执行。infrared_device_read_frames()、infrared_device_write_frames() 以及对应 rt_device_read/write 的 size 都以完整协议帧条数计,而不是以字节数计。[S3]

master 已实现哪些能力,哪些仍需要上板确认

master 源码已经包含 LEGACY/FRAMEWORK 互斥选编、多实例逻辑设备、PIN/HWTIMER 和 Input Capture 接收后端、PWM/HWTIMER 发送后端、NEC Codec,以及可选的 MSH 诊断和 Event 工作线程。这些属于代码实现及配置层面已确认的能力,不是对任意 BSP 的即插即用保证。[S1][S3][S4][S6]

工程接入仍依赖具体 RT-Thread 版本及目标 BSP 是否提供匹配的 PIN、HWTIMER、Input Capture、PWM 设备与回调接口。尤其要核对 HWTIMER 设备 API、Capture 缓存控制与清空语义、PWM 通道及计时器独占关系;不能因为 Kconfig 选项可选,就默认相关外设已经具备可用实现。[S4][S6]

本文没有针对 master 的目标源码重新执行 BSP 编译,也没有进行实机红外收发验证。 对载波频率、GPIO 边沿时间、Capture 采样、NEC 解码准确性、多实例同时收发及异常关闭后的资源状态,仍需在对应硬件上分别确认。构建成功与硬件时序正确是两个不同的验证层次。[S4][S6]

不同 MCU/BSP 上最值得分享的证据包括:实际注册的物理设备名、红外接收头有效电平、HWTIMER 计数周期、Input Capture 缓冲行为、PWM 载波及 MARK/SPACE 示波器波形,以及出现错误时的返回码和日志。

欢迎使用,也欢迎为不同 BSP 提供反馈

IF 这次重构带来了独立多实例、可替换接收后端、协议 Codec 解耦、完整帧 API、事件驱动示例以及可裁剪资源池,同时保留已有 LEGACY 使用路径。对使用 RT-Thread 进行遥控接收、红外控制或自定义脉冲协议开发的项目,这提供了一个更清晰的复用基础。[S1][S3]

欢迎从 GitHub master 分支获取源码,在适配的 BSP 上尝试并提交使用反馈。提交 Issues 时附上 MCU/BSP、RT-Thread 版本、LEGACY/FRAMEWORK 配置、输入/输出后端、实际设备名、现象及必要的示波器或日志证据,将有助于逐步扩展实机兼容性。源码具备相应功能不等于所有 BSP 已完成适配,仍欢迎社区通过真实硬件验证收发效果。

深入了解可以阅读 master 分支的架构说明、接收流程、发送及 NEC和移植配置。另有在线文档及 Doxygen API 参考便于浏览;在线站点可能随部署分支更新,本文的技术引用以 master 源码为准。

资料来源

[S1] IF master 分支、构建选择与软件包说明

  • 类型:开源仓库 master 源码,核对基线为 2026-11-15 提交 2828de15c386db5e7f2b6034b95fdbeb9aaa7e56。
  • 定位:README、Kconfig、SConscript。
  • 使用位置:开篇、模式切换、编译裁剪与使用建议。
  • 支撑内容:LEGACY/FRAMEWORK 互斥、master 版本与目录选编事实。

[S2] 旧版 LEGACY 单实例实现

  • 类型:同一 master 提交保留的旧实现。
  • 定位:inc/infrared.h、src/infrared.c、src/drv_infrared.c;infrared_class、driver_report_raw_data()、ir_select_decoder()。
  • 使用位置:新旧对比。
  • 支撑内容:旧全局对象和脉冲上报时调用 Decode 的行为。

[S3] 新 FRAMEWORK 公开 API、帧格式与生命周期

[S4] 输入/输出硬件后端及架构说明

  • 类型:master 源码和随仓库文档。
  • 定位:架构与资源所有权、接收路径、发送路径;framework/src/backends/input/infrared_pin.c、infrared_capture.c、framework/src/backends/output/infrared_pwm.c。
  • 使用位置:原理、硬件驱动职责与收发边界。
  • 支撑内容:MARK/SPACE、物理资源独占、PWM/HWTIMER 发送及 Input Capture 限制。

[S5] NEC Codec 与共享 Pulse-Distance 编解码

  • 类型:master 提交源码。
  • 定位:NEC Codec、共享 Pulse-Distance 实现;nec_decode()、nec_encode() 和 infrared_pd_step()。
  • 使用位置:NEC 帧结构和 pulse-distance 辅助层。
  • 支撑内容:源码常量中的 NEC 脉宽、地址/命令反码、重发次数与完整帧编码;不泛化为所有红外协议。

[S6] Kconfig 设备示例与 MSH 接口

  • 类型:master 提交的配置及示例实现。
  • 定位:配置与移植说明、框架示例、MSH 命令。
  • 使用位置:上手配置、应用示例与调试命令。
  • 支撑内容:示例线程、注册入口、MSH 命令与可选内存容量。

[S7] RT-Thread 官方软件包索引的当前配置

  • 类型:外部开源仓库配置核对,2026-11-15。
  • 定位:RT-Thread/packages 的 infrared/Kconfig。
  • 使用位置:软件包安装与 menuconfig 提示。
  • 支撑内容:官方索引当前可见配置仍属于旧结构,集成新分支需保持 Kconfig 与源码版本一致。