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 | flowchart LR |
用 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 | flowchart LR |
发送缓冲由 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 | ir help |
其中 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 |
|
对于已经打开并配置 PWM 发射的实例,发送一个 NEC 帧的应用写法可以简化为:
1 | struct infrared_frame tx = {0}; |
上面的 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、帧格式与生命周期
- 类型:
master提交源码。 - 定位:framework/inc/infrared_device.h、framework/inc/infrared_codec.h、framework/src/infrared_device.c。
- 使用位置:多实例、Codec、完整帧读写、Poll、帧回调、发送返回值及资源生命周期。
- 支撑内容:
infrared_device_register()、infrared_device_poll()和infrared_device_write_frames()等语义。
[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 接口
[S7] RT-Thread 官方软件包索引的当前配置
- 类型:外部开源仓库配置核对,2026-11-15。
- 定位:RT-Thread/packages 的 infrared/Kconfig。
- 使用位置:软件包安装与 menuconfig 提示。
- 支撑内容:官方索引当前可见配置仍属于旧结构,集成新分支需保持 Kconfig 与源码版本一致。











