STM32 HAL 函数大全 · 第 3 卷
TIM 定时器模块（基础定时 / PWM / 输入捕获 / 输出比较）
版本：v1.1|适用系列：STM32F0 / F1 / F3 / F4 / F7 / L0 / L4 / H7
1. TIM 模块简介与分类
定时器（Timer）是 STM32 中功能最复杂、应用最广泛的外设。它不仅能提供精确的时基（Timebase），还能生成 PWM 波形、测量脉冲宽度、驱动电机编码器等。
STM32 定时器分类
| 类型 | 典型定时器 | 功能特点 | 典型应用 |
|---|---|---|---|
| 基本定时器 | TIM6, TIM7 | 仅支持累加计数，无 IO 引脚 | 产生时基中断、驱动 DAC |
| 通用定时器 | TIM2 ~ TIM5 | 支持输入捕获、PWM 输出、编码器 | 测量频率、电机控制、LED 调光 |
| 高级定时器 | TIM1, TIM8 | 带死区控制、互补输出、刹车输入 | 三相电机驱动、数字电源 |
2. 核心参数与时间计算公式
在 CubeMX 配置或代码初始化时，以下三个核心寄存器决定了定时器的时间特性。
2.1 核心寄存器
PSC (Prescaler)：预分频器。将定时器总线时钟 (
TIM_CLK) 进行分频。ARR (Auto-Reload Register)：自动重装载寄存器。决定计数的周期（即从 0 计数到多少后溢出）。
CNT (Counter)：当前计数值（实时变化）。
CCR (Capture/Compare Register)：捕获/比较寄存器。用于 PWM 占空比控制或输入捕获存储。
2.2 时间计算公式
假设定时器总线时钟源为TIM_Clk(如 72MHz)，配置值计算如下：
1. 溢出时间（中断周期）
溢出频率 = TIM_Clk / ((PSC + 1) * (ARR + 1)) 溢出时间 = 1 / 溢出频率
2. PWM 频率
PWM_Freq = TIM_Clk / ((PSC + 1) * (ARR + 1))
3. PWM 占空比
Duty_Cycle (%) = (CCRx / (ARR + 1)) * 100
注意：由于硬件计数器是从 0 开始计数的，所以在计算配置值时，PSC 和 ARR 的值通常需要减 1。
案例：时钟 72MHz，要产生 1kHz 频率（1ms 周期）。
配置：
PSC = 71(72分频 -> 1MHz),ARR = 999(计数1000次 -> 1ms)。
3. 四大工作模式详解
3.1 基础定时模式 (Base)
原理：计数器从 0 计数到 ARR，产生“更新事件” (Update Event) 并触发中断，然后清零重新计数。
场景：系统滴答、任务调度、软件延时。
3.2 PWM 输出模式 (PWM Generation)
原理：比较 CNT 与 CCRx 的值。
CNT < CCRx：输出有效电平（如高电平）。CNT > CCRx：输出无效电平（如低电平）。
场景：LED 亮度调节、电机速度控制、舵机角度控制。
3.3 输入捕获模式 (Input Capture)
原理：当引脚检测到信号跳变（如上升沿）时，硬件立即锁存当前的 CNT 值到 CCRx 寄存器。
场景：测量外部信号的频率、脉冲宽度（高电平时间）。
3.4 输出比较模式 (Output Compare)
原理：当 CNT 等于 CCRx 时，自动翻转引脚电平或触发中断，而不重置计数器。
场景：生成特定相位的波形、在特定时间点触发 ADC 采样。
4. HAL TIM API 函数全集
HAL 库按功能模式对 API 进行了分类。
4.1 基础定时 (Base)
| 功能 | 轮询模式 | 中断模式 | DMA 模式 |
|---|---|---|---|
| 启动 | HAL_TIM_Base_Start | HAL_TIM_Base_Start_IT | HAL_TIM_Base_Start_DMA |
| 停止 | HAL_TIM_Base_Stop | HAL_TIM_Base_Stop_IT | HAL_TIM_Base_Stop_DMA |
4.2 PWM 输出 (PWM)
| 功能 | 轮询模式 | 中断模式 | DMA 模式 |
|---|---|---|---|
| 启动 | HAL_TIM_PWM_Start | HAL_TIM_PWM_Start_IT | HAL_TIM_PWM_Start_DMA |
| 停止 | HAL_TIM_PWM_Stop | HAL_TIM_PWM_Stop_IT | HAL_TIM_PWM_Stop_DMA |
| 占空比 | 宏：__HAL_TIM_SET_COMPARE | - | - |
4.3 输入捕获 (IC)
| 功能 | 轮询模式 | 中断模式 | DMA 模式 |
|---|---|---|---|
| 启动 | HAL_TIM_IC_Start | HAL_TIM_IC_Start_IT | HAL_TIM_IC_Start_DMA |
| 读取 | HAL_TIM_ReadCapturedValue | - | - |
4.4 常用宏定义
// 动态修改 PWM 占空比 (修改 CCR 寄存器) __HAL_TIM_SET_COMPARE(__HANDLE__, __CHANNEL__, __COMPARE__); // 动态修改自动重装载值 (修改 ARR 寄存器，即修改频率) __HAL_TIM_SET_AUTORELOAD(__HANDLE__, __AUTORELOAD__); // 获取计数器当前值 __HAL_TIM_GET_COUNTER(__HANDLE__);
5. 中断与回调机制
STM32 的定时器共用一个中断入口（如TIM3_IRQHandler），用户只需重写这些__weak回调函数。
| 回调函数名 | 触发时机 | 典型用途 |
|---|---|---|
HAL_TIM_PeriodElapsedCallback | 更新事件（计数溢出） | 基础定时任务、软件看门狗喂狗 |
HAL_TIM_PWM_PulseFinishedHAL_TIM_PWM_PulseFinishedCallback` | PWM 脉冲结束 | 在 PWM 周期末端触发 ADC、DMA 更新占空比 |
HAL_TIM_IC_CaptureCallback | 输入捕获成功 | 读取捕获值、计算频率 |
HAL_TIM_OC_DelayElapsedCallback | 输出比较匹配输出比较匹配** | 精确控制 GPIO 翻转 |
6. 实战工程示例
示例 1：基础定时中断 (1ms Tick)
目标：使用 TIM2 每 1ms 进入一次中断翻转 LED。配置：Clock=72MHz, PSC=71, ARR=999。
// 1. 初始化开启 (在 main.c 初始化部分) HAL_TIM_Base_Start_IT(&htim2); // 2. 回调函数 (在 main.c 末尾) void HAL_TIM_PeriodElapsedCallback(TIM_HandleTypeDef *htim) { if (htim->Instance == TIM2) { HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin); } }示例 2：PWM 呼吸灯
目标：使用 TIM3_CH1 (PA6) 驱动 LED，实现亮度渐变。
// 1. 开启 PWM HAL_TIM_PWM_Start(&htim3, TIM_CHANNEL_1); // 2. 修改占空比 (在 while 循环中) uint16_t pwmVal = 0; int8_t step = 10; while (1) { HAL_Delay(20); pwmVal += step; if (pwmVal >= 1000 || pwmVal <= 0) step = -step; // 修改 CCR1 寄存器值 __HAL_TIM_SET_COMPARE(&htim3, TIM_CHANNEL_1, pwmVal); }示例 3：输入捕获测频率
目标：测量 TIM2_CH1 引脚输入的 PWM 频率。
uint32_t val1 = 0, val2 = 0; uint8_t isFirstCapture = 1; uint32_t frequency = 0; void HAL_TIM_IC_CaptureCallback(TIM_HandleTypeDef *htim) { if (htim->Channel == HAL_TIM_ACTIVE_CHANNEL_1) { if (isFirstCapture) { val1 = HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1); isFirstCapture = 0; } else { val2 = HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1); uint32_t diff; // 计算差值 (处理溢出) if (val2 > val1) diff = val2 - val1; else diff = (0xFFFF - val1) + val2 + 1; if(diff != 0) frequency = 1000000 / diff; // 假设 1MHz 计数时钟 isFirstCapture = 1; } } }7. 调试技巧与常见避坑
PWM 不输出：
检查是否调用了
HAL_TIM_PWM_StartHAL_TIM_PWM_Start`。高级定时器 (TIM1/TIM8)：必须确认是否开启了 MOE (Main Output Enable)** 位。可能需要调用
HAL_TIMEx_PWMN_Start或设置__HAL_TIM_MOE_ENABLE。
定时器频率不对： * * 检查APB1/APB2 总线时钟频率。在 STM32F4 等系列中，如果 APB1 分频系数不为 1，则提供给定时器的时钟会x2x2**。
中断进不去：
检查 NVIC 中是否使能了对应定时器的中断。
检查是否使用了
_IT后缀的启动函数。
影子寄存器 (Preload) 坑：
修改
ARR或PSCPSC时，如果开启了Auto-Reload Preload，新值会在下一个更新事件才生效。如需立即生效，请手动产生更新事件__HAL_TIM_URG(htim)`。