STM32 输入捕获终于接入 RT-Thread:测量脉冲,不必再从 HAL 回调写起
摘要:RT-Thread 主线已合并 STM32F1/H7 输入捕获驱动,应用可通过统一设备接口读取高、低电平脉宽。本文介绍输入捕获原理、BSP 接入方法,以及正在扩展的多通道、PWM Input 和双边沿模式。
[TOC]
STM32 输入捕获有了统一的 RT-Thread 设备接口
测量 PWM 占空比、风扇转速、编码脉冲或超声波回波时,STM32 的定时器输入捕获(Input Capture)是常用外设功能。它在输入信号出现指定边沿时,把定时器计数值锁存到捕获/比较寄存器(CCR),由相邻捕获值的差计算时间间隔。与 GPIO 中断中读取软件时间戳相比,硬件捕获能减少中断响应延迟对边沿时间戳的直接影响。[S5]
过去在 STM32 BSP 中使用这项功能,应用往往需要自行组织 HAL_TIM_IC_ConfigChannel()、HAL_TIM_IC_Start_IT()、HAL_TIM_IC_CaptureCallback(),再处理边沿切换、计数器回绕和脉宽换算。现在,这些与硬件相关的共性工作可以由 STM32 Input Capture 设备驱动承担,应用通过 RT-Thread 设备接口获取捕获结果。 这里的变化不是“STM32 不再使用 HAL”,而是 HAL 被收敛到 BSP 驱动层,业务代码不必重复实现。[S1][S2][S3]
截至 2026 年 11 月 15 日,有两项需要分开看待的进展:
| 进展 | 上游状态 | 实际能力 |
|---|---|---|
| PR #11975:STM32F1/H7 Input Capture 驱动 | 2026-11-06 已合并 | STM32F1/H7 HAL BSP 可以选用 TIM1~TIM4;每个已启用的物理 TIM 配置一个输入捕获通道,向框架提供脉宽数据 |
| PR #12052:多通道和配对边沿模式 | 尚未合并(本文核对时) | 计划在同一 TIM 上支持多个独立 EDGE 设备,并提供独占式 PWM Input、DUAL_EDGE 两种配对模式 |
因此,已经合并的是 STM32F1/H7 的基础输入捕获能力;后文提到的多通道独立采集、PWM Input 和 DUAL_EDGE 属于 #12052 的待合并增强,不能直接当作当前 master 已有功能。其他 STM32 系列是否可以使用,还需要对应 HAL 系列适配及板级验证,不能据此推断所有 STM32 BSP 均已开箱即用。[S1][S4]
输入捕获到底测量了什么?
输入捕获不是 PWM 输出。PWM 输出由定时器主动产生波形;输入捕获则观察外部波形,在上升沿、下降沿等事件发生时记录计数器数值。定时器以 f_CNT 递增计数,捕获瞬间的 CNT 值写入对应 CCR;两次捕获间的计数差 ΔCNT 可以换算为时间:[S5]
[
\Delta t=\frac{\Delta CNT}{f_{CNT}}
]
例如计数频率设为 1 MHz,计数器每计数一次对应 1 μs。若相邻边沿相差 400 个计数,则对应 400 μs。若测得某周期的高电平持续 400 μs、低电平持续 600 μs,则可进一步计算:
[
T = T_{high}+T_{low}=1000\ \mu s,\qquad
f=\frac{1}{T}=1000\ Hz
]
[
Duty=\frac{T_{high}}{T_{high}+T_{low}}\times100%=40%
]
其中 T_high、T_low 是持续时间,不是“上升沿、下降沿各发生了一次”的事件标志。RT-Thread 框架给应用的记录结构为:[S3]
1 | struct rt_inputcapture_data |
pulsewidth_us 表示本次已完成的电平区间持续了多少微秒;is_high 指该区间属于高电平还是低电平。对于普通连续脉冲,驱动在获得前后两个有效边沿后才产生完整区间记录,首次边沿本身无法形成脉宽。框架不会直接返回 PWM 频率或占空比,计算这两个量需要应用根据高、低电平记录组合完成。[S2][S3]
从 HAL 中断到 RT-Thread 设备:数据走哪条路?
STM32 仍然利用硬件定时器和 HAL 完成输入捕获,不过驱动将底层结果转换为 RT-Thread 认识的脉宽数据,应用不再直接依赖 TIM_HandleTypeDef、CCR 或 HAL 捕获回调。[S2][S3]
1 | flowchart LR |
驱动在 rt_hw_inputcapture_init() 中通过 rt_device_inputcapture_register() 注册设备;设备打开时配置并启动对应定时器输入捕获。捕获中断到达后,STM32 驱动计算脉宽并调用 rt_hw_inputcapture_isr(),框架把 rt_inputcapture_data 放入环形缓冲区,应用再通过 rt_device_read() 获取记录。[S2][S3]
框架还提供 INPUTCAPTURE_CMD_CLEAR_BUF(清空缓冲)和 INPUTCAPTURE_CMD_SET_WATERMARK(设置接收通知阈值),以及 rx_indicate 接收通知机制。rt_device_read() 的 size 参数在此类设备中表示要读取多少条 rt_inputcapture_data 记录,返回值也是实际取得的记录条数,不是字节数。[S3]
在 STM32 BSP 中如何启用?
已合并驱动的配置入口位于 bsp/stm32/libraries/HAL_Drivers/drivers/Kconfig。在支持的 STM32F1/H7 BSP 中启用 BSP_USING_INPUT_CAPTURE 后,会自动选择 RT_USING_INPUT_CAPTURE;再为相应 TIM 选择捕获通道。下面以 TIM3 为例说明基础版本的关键选项:[S1][S2]
1 | BSP_USING_INPUT_CAPTURE=y |
上述是 Kconfig 配置符号示意;
.config文件中通常带CONFIG_前缀,应通过menuconfig设置并由构建系统生成,不能把这段原样当成可直接复制的.config文件。
这些参数各自控制不同的内容:NAME 是应用打开设备时使用的名称,CHANNEL 是 TIM 的物理通道,FILTER 是硬件输入数字滤波设置,INITIAL_RISING 指定首次等待的边沿,COUNTER_HZ 指定用于脉宽换算的计数频率。当前基础 Kconfig 对计数频率提供 100 kHz~1 MHz 的范围,默认 1 MHz;驱动还要求定时器输入时钟能被所选计数频率整除。[S2]
Kconfig 启用不等于板级电路已经接通。 对应引脚必须正确配置为 TIM 输入复用功能,外设时钟、GPIO 和 NVIC 由目标板的 HAL MSP/CubeMX 配置承担;同一个物理 TIM 及其 IRQ 还应避免同时被 PWM、HWTIMER 或另一份 TIM 驱动占用。如果工程采用 HAL 的回调注册机制,还需要按该工程实际机制绑定输入捕获回调。[S1][S2]
完成板级配置后,应用只需按注册名称查找设备,读取框架提供的数据。以下示例适用于已合并的基础输入捕获驱动,在普通线程上下文调用;ic3 是上述 TIM3 示例名称,具体应与板级实际注册名称一致:
1 |
|
这段代码只是展示接口的最小读取方式,不等同于已完成板上测试。rt_device_read() 在当前框架中从环形缓冲区取数据,缓冲区为空时本例通过延时重试;高边沿速率场景不宜照搬这种轮询方式。更合适的方案是利用 rx_indicate 通知工作线程及时批量读取,并根据缓冲区深度、过捕获及应用处理速率设计丢样策略。[S3]
多通道、PWM Input、DUAL_EDGE:三个名字有什么区别?
PR #12052 主要是在既有设备接口保持不变的前提下,扩展 STM32 定时器底层如何采样、如何组织逻辑设备。其重点不是新增一套应用 API,而是解决基础版“一个物理 TIM 只能选一个通道”的限制,并提供两种 CH1/CH2 配对采集方式。[S4]
| 模式 | 捕获通道如何使用 | 定时器如何计数 | 对外设备与资源关系 | 状态 |
|---|---|---|---|---|
| 基础单通道 EDGE | 一个 TIM 选择 CH1~CH4 中的一个通道,必要时软件切换捕获极性 | 自由运行,按相邻 CCR 差值求脉宽 | 每个 TIM 注册一个设备 | 已合并 #11975 |
| 多通道独立 EDGE | 同一个 TIM 可分别选择 CH1~CH4,各通道采集各自的输入 | 同一 TIM 的通道共享 CNT、PSC、ARR | 不同通道注册为不同设备;共享物理 HAL 句柄 | #12052 待合并 |
| PWM Input | 同一输入信号使用 CH1/CH2 的直接/间接捕获配对,分别锁存相反边沿 | 使用 Slave Reset,在选定基准边沿复位计数器 | 单个逻辑设备,独占整个 TIM;一个有效周期可产生高、低电平两条记录 | #12052 待合并 |
| DUAL_EDGE | 同一输入信号使用 CH1/CH2 配对,分别锁存不同极性的边沿 | 不使用 Slave Reset,保持自由运行计数器 | 单个逻辑设备,独占整个 TIM;按时间戳先后形成电平间隔 | #12052 待合并 |
多通道 EDGE:一个 TIM 对应多个独立输入
基础版本按物理定时器注册设备,即使 TIM 有多个通道,配置时也只选一个。增强版则可以把同一 TIM 的不同 CHx 映射成多个 Input Capture 设备,分别管理各通道捕获状态,但所有通道仍共享该 TIM 的计数频率、计数器和自动重装值,不能把它们理解成多组彼此独立的定时器。[S2][S4]
例如一个 TIM 的 CH1、CH2 分别接入两路低频脉冲时,应用可以按各自的设备名称读取记录。此时两个通道是不同输入源,不是 PWM Input 中“同一根输入经两个捕获通道采集两种边沿”的配对关系。
PWM Input:让硬件完成周期与占空比采样的配对
PWM Input 将 CH1/CH2 配成直接输入(Direct TI)与间接输入(Indirect TI)。两路捕获检测同一输入信号的相反边沿,定时器在基准边沿触发 Slave Reset,因此 CCR 可分别反映周期和周期内的某一段电平持续时间。#12052 的当前实现由直接通道捕获中断一次性读取配对通道的捕获结果,再写入高、低电平两条框架记录,应用仍按 pulsewidth_us 和 is_high 消费数据。[S4]
这种模式适合稳定、连续的 PWM 波形,能减少“每个边沿都要软件切换极性”的依赖;代价是该 TIM 的计数器复位方式已被模式占用,不能与同一 TIM 的独立 EDGE 设备混用。[S4]
DUAL_EDGE:两个硬件捕获通道,但不复位计数器
DUAL_EDGE 同样把 CH1/CH2 配对到同一输入,只是两种边沿各自锁存时间戳,CNT 持续自由运行。驱动根据捕获时间戳计算相邻边沿的间隔;当两个通道的捕获标志同时待处理时,还要判定先后顺序,避免机械地按 IRQ 通道号把时间顺序读反。[S4]
DUAL_EDGE 与 PWM Input 的关键差异是是否依靠硬件 Slave Reset。DUAL_EDGE 也不同于某些 STM32 定时器提供的“单通道硬件双边沿极性”选项:前者明确占用 CH1/CH2 配对,后者是否可用取决于具体 TIM、通道和 HAL 能力,不能因为 HAL 头文件定义了双边沿常量就假定所有定时器都支持。[S2][S4]
在 #12052 当前 Kconfig 方案中,TIM1~TIM4 各自选择独立 EDGE、PWM Input 或 DUAL_EDGE:前者可以勾选 CH1~CH4 的独立设备,后两者为独占式二选一。设备名称、滤波、捕获极性和 ARR 等板级设置放在 F1/H7 的 inputcapture_config.h 中,与已合并基础版把名称、单通道及滤波选项放在 Kconfig 的方式不同;因此以后切换到增强版时,不宜机械复用旧 .config 的所有参数。[S2][S4]
哪些场景值得使用输入捕获?
输入捕获适用于外部信号的时间特征比瞬时电平值更重要的场景:
- PWM 输入测量:读取控制信号的高、低电平时间,计算频率、周期、占空比,例如外部 PWM 控制信号识别。
- 转速或频率检测:对风扇测速脉冲、转速传感器等信号求相邻脉冲周期,再按“每转脉冲数”换算实际转速。
- 脉宽测量:测量超声波测距模块的 ECHO 高电平时长,或其他脉冲持续时间编码信号。
- 边沿间隔分析:监测脉冲列中的高低电平间隔,供上层进行脉冲编码解析或异常脉宽判断。
模式选取不应只看名字,而要看输入信号数量、是否需要同时采集两种边沿、能否独占 TIM、信号频率及最大持续时间。普通 EDGE 足以覆盖许多低频脉宽任务;稳定 PWM 测量可关注待合并的 PWM Input;要求保留自由运行时间戳的单路双边沿采集,可关注 DUAL_EDGE;多个独立引脚共享 TIM 时则需要多通道 EDGE。[S2][S4]
实际使用时仍要注意时间分辨率和计数范围。例如 1 MHz 计数、ARR=0xFFFF 的 16 位定时器,一个完整计数周期为 65.536 ms。当前驱动按相邻 CCR 差值处理至多一次模回绕,不维护跨越多个完整计数周期的溢出计数;若边沿间隔太长,结果可能不再唯一。基础 EDGE 的软件切换极性也可能漏掉过短的相邻边沿,而更高的输入频率又可能导致硬件过捕获或框架缓冲区积压。定时器位宽、可复用引脚、数字滤波和 NVIC 负载必须结合具体 STM32 型号及信号特征评估。[S2][S4][S5]
结语
STM32 Input Capture 驱动接入 RT-Thread 的价值,不只是少写几行 HAL_TIM_IC_CaptureCallback(),而是将板级捕获配置、硬件中断、脉宽换算、数据缓冲和应用读取纳入清晰的驱动框架边界。对已经支持的 STM32F1/H7 BSP,基础输入捕获可以优先采用主线驱动,不必再从零编写一份 HAL 捕获逻辑;需要多路输入、硬件 PWM Input 或配对双边沿采集的工程,则应关注 #12052 的合并进度和后续板级适配。[S1][S4]
资料来源
[S1] RT-Thread 已合并的 STM32 输入捕获适配
- 版本/状态:PR #11975,2026-11-06 合并;合并提交
7ac0b44a8d4fdf6b21641d3ecbedbe3ec4f263ca。 - 来源:STM32F1/H7 输入捕获支持 PR #11975。
- 使用位置:“STM32 输入捕获有了统一的 RT-Thread 设备接口”“在 STM32 BSP 中如何启用”。
- 支撑内容:F1/H7 系列适配范围、合并事实、HAL MSP/资源归属约束和板级验证状态。
[S2] STM32 基础驱动与 BSP 配置源码
- 版本:RT-Thread 主线(2026-11-15 核对),对应 #11975 已合并实现。
- 定位:
drv_inputcapture.c的stm32_capture_init()、stm32_capture_open()、HAL_TIM_IC_CaptureCallback()、rt_hw_inputcapture_init();Kconfig和 F1/H7 的inputcapture_config.h。 - 使用位置:“数据走哪条路”“在 STM32 BSP 中如何启用”“多通道、PWM Input、DUAL_EDGE”“哪些场景值得使用”。
- 支撑内容:计数频率、通道选择、软件极性切换、定时器回绕处理和实际注册方式。
[S3] RT-Thread Input Capture 公共设备框架
- 版本:RT-Thread 主线(2026-11-15 核对)。
- 定位:
rt_inputcapture.h的rt_inputcapture_data、rt_inputcapture_ops;rt_inputcapture.c的rt_device_inputcapture_register()、rt_hw_inputcapture_isr()和设备读接口。 - 使用位置:“输入捕获到底测量了什么?”“数据走哪条路”“在 STM32 BSP 中如何启用”。
- 支撑内容:脉宽数据语义、环形缓冲区、记录数读取、接收通知与设备控制命令。
[S4] STM32 多通道与配对边沿增强 PR
- 版本/状态:PR #12052,核对的 HEAD 为
45b8674e3c682c68478e238efcfee5e77931c693;截至 2026-11-15 尚未合并。 - 来源:STM32 多通道与配对边沿增强 PR #12052。
- 定位:PR 修改的
drv_inputcapture.c、drv_inputcapture.h、F1/H7inputcapture_config.h和Kconfig;关键符号stm32_capture_pwm_input_sample()、stm32_capture_dual_edge_handle_irq()、stm32_capture_find_device()。 - 使用位置:“进展状态”“多通道、PWM Input、DUAL_EDGE”“哪些场景值得使用”。
- 支撑内容:每个 TIM 的逻辑设备分配、共享 HAL 句柄、Slave Reset 与自由运行计数器的差异、互斥配置和模式边界。
[S5] ST 官方输入捕获技术说明
- 版本:2024-08-07,ST Community 技术文章。
- 来源:How to use the input capture feature。
- 使用位置:“STM32 输入捕获有了统一的 RT-Thread 设备接口”“输入捕获到底测量了什么?”“哪些场景值得使用”。
- 支撑内容:CCR 捕获时间戳、时钟预分频与 ARR、输入边沿/数字滤波,以及输入捕获测周期和脉宽的原理。











