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
2
3
4
5
struct rt_inputcapture_data
{
rt_uint32_t pulsewidth_us;
rt_bool_t is_high;
};

pulsewidth_us 表示本次已完成的电平区间持续了多少微秒;is_high 指该区间属于高电平还是低电平。对于普通连续脉冲,驱动在获得前后两个有效边沿后才产生完整区间记录,首次边沿本身无法形成脉宽。框架不会直接返回 PWM 频率或占空比,计算这两个量需要应用根据高、低电平记录组合完成。[S2][S3]

从 HAL 中断到 RT-Thread 设备:数据走哪条路?

STM32 仍然利用硬件定时器和 HAL 完成输入捕获,不过驱动将底层结果转换为 RT-Thread 认识的脉宽数据,应用不再直接依赖 TIM_HandleTypeDef、CCR 或 HAL 捕获回调。[S2][S3]

1
2
3
4
5
6
flowchart LR
A["外部脉冲"] --> B["STM32 TIM 捕获 CCR"]
B --> C["TIM IRQ / HAL 回调"]
C --> D["STM32 drv_inputcapture.c"]
D --> E["rt_hw_inputcapture_isr() / 环形缓冲区"]
E --> F["rt_device_read() / rx_indicate"]

驱动在 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
2
3
4
5
6
7
BSP_USING_INPUT_CAPTURE=y
BSP_USING_INPUT_CAPTURE_TIM3=y
BSP_INPUT_CAPTURE_TIM3_NAME="ic3"
BSP_INPUT_CAPTURE_TIM3_CHANNEL=1
BSP_INPUT_CAPTURE_TIM3_FILTER=0
BSP_INPUT_CAPTURE_TIM3_INITIAL_RISING=1
BSP_INPUT_CAPTURE_COUNTER_HZ=1000000

上述是 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
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
38
39
40
#include <rtthread.h>
#include <rtdevice.h>
#include <drivers/rt_inputcapture.h>

int inputcapture_demo(void)
{
rt_device_t dev = rt_device_find("ic3");
struct rt_inputcapture_data data;
rt_size_t received = 0;

if (dev == RT_NULL)
{
rt_kprintf("input capture device not found\n");
return -RT_ERROR;
}

if (rt_device_open(dev, RT_DEVICE_OFLAG_RDONLY) != RT_EOK)
{
rt_kprintf("input capture open failed\n");
return -RT_ERROR;
}

while (received < 20)
{
if (rt_device_read(dev, 0, &data, 1) == 1)
{
rt_kprintf("%s: %u us\n",
data.is_high ? "HIGH" : "LOW",
(unsigned int)data.pulsewidth_us);
received++;
}
else
{
rt_thread_mdelay(2);
}
}

rt_device_close(dev);
return RT_EOK;
}

这段代码只是展示接口的最小读取方式,不等同于已完成板上测试。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/H7 inputcapture_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、输入边沿/数字滤波,以及输入捕获测周期和脉宽的原理。