1. 项目概述与核心价值最近在做一个智能小车避障的项目核心的测距传感器选用了经典的HC-SR04超声波模块。这个模块成本低、原理简单但要想在STM32上稳定、精准地驱动它还是有不少细节需要琢磨。直接操作寄存器固然可以但对于快速原型开发或者项目维护来说使用ST官方力推的HAL库配合CubeMX图形化配置工具无疑是更高效、更规范的选择。这次我就来详细拆解一下如何从零开始用CubeMX配置一个STM32工程并编写代码驱动HC-SR04最终实现可靠的距离测量。整个过程不仅适用于避障小车对于任何需要非接触式测距的场景比如液位检测、物体存在性判断等都很有参考价值。HC-SR04的工作原理大家应该不陌生触发引脚Trig给一个至少10us的高电平脉冲模块会自动发射8个40kHz的超声波脉冲然后回声引脚Echo会输出一个高电平其持续时间与超声波往返时间成正比。所以核心任务就变成了STM32如何精准产生这个触发信号以及如何高精度地测量Echo引脚高电平的持续时间。我们将使用通用定时器TIM的PWM输出模式来产生触发脉冲用输入捕获功能来测量高电平脉宽这是最经典且稳定的方案。下面我就结合CubeMX的配置和HAL库的编程把每一步的要点和踩过的坑都分享出来。2. 硬件连接与CubeMX工程创建2.1 硬件接口定义首先明确硬件连接。HC-SR04模块通常有四个引脚VCC、Trig、Echo、GND。VCC 接3.3V或5V。虽然STM32的IO是3.3V电平但HC-SR04的Echo引脚输出高电平是5V。这是一个关键点不能直接将5V的Echo引脚接到STM32的GPIO上否则可能损坏芯片。稳妥的做法是使用一个简单的电平转换电路比如两个电阻分压例如1kΩ和2kΩ或者使用电平转换芯片。在要求不严、距离较短的测试中也有人直接连接但长期使用有风险不推荐。GND 共地。Trig 触发引脚连接STM32的一个GPIO配置为推挽输出模式。Echo 回声引脚连接STM32的一个GPIO配置为浮空输入或上拉输入模式用于捕获高电平。在我的设计中我选择Trig- PA8 (后续配置为TIM1的CH1输出PWM)Echo- PA0 (后续配置为TIM2的CH1输入捕获) 使用不同的定时器是为了避免资源冲突和逻辑耦合。2.2 CubeMX基础工程配置打开CubeMX新建工程选择你的STM32型号例如STM32F103C8T6。系统核心SYS 在SYS选项卡中将Debug设置为Serial Wire。如果你的调试器是ST-Link这是必须的否则可能无法下载和调试。时钟RCC 在RCC选项卡中将High Speed Clock (HSE)设置为Crystal/Ceramic Resonator。这样我们才能使用外部高速晶振为定时器提供精准的时钟源。时钟树配置 点击Clock Configuration标签。这是CubeMX的核心之一。我们的目标是为定时器提供较高的计数频率以提高测量精度。以STM32F103为例通常先设置HSE为8MHz然后通过PLL倍频到72MHz作为系统时钟SYSCLK。接着将APB1定时器时钟和APB2定时器时钟都设置为72MHz注意APB1总线时钟最高36MHz但连接到定时器的时钟经过了一个倍频器如果APB1预分频系数不为1则定时器时钟是APB1时钟的2倍。确保你使用的定时器如TIM1在APB2 TIM2在APB1的时钟源是72MHz。清晰的时钟树是精准定时的基础。项目管理 在Project Manager选项卡中设置项目名称、路径将Toolchain / IDE选为MDK-ARM如果你用Keil。关键一步是在Code Generator部分勾选Generate peripheral initialization as a pair of ‘.c/.h’ files per peripheral。这会将每个外设的初始化代码生成独立的文件让工程结构更清晰方便管理。3. 定时器配置PWM触发与输入捕获这是本次配置的核心我们分两个定时器进行。3.1 TIM1配置产生触发脉冲PWM模式我们的目标是用TIM1的一个通道输出一个精确的、宽度大于10us的单次脉冲。引脚分配 在芯片引脚图上找到PA8其复用功能是TIM1_CH1。点击PA8引脚选择TIM1_CH1。定时器参数设置 左侧切换到Timers-TIM1。Clock Source 选择Internal Clock。Parameter SettingsPrescaler(预分频器) 设置为71。定时器时钟是72MHz分频后计数频率为 72MHz / (711) 1MHz。即计数器每1us递增1。Counter ModeUp向上计数。Counter Period 设置为19。我们希望产生一个20us的脉冲满足HC-SR04的10us最小要求并留有余量。因为计数器从0开始计数到19总共是20个时钟周期即20us。auto-reload preloadEnable。使能自动重装载预装载寄存器可以避免更新参数时的毛刺。PWM生成通道配置 切换到Channel 1。Mode 选择PWM Generation CH1。Pulse 设置为18。这个参数决定了PWM高电平的宽度。我们希望高电平宽度是20us但这里设置的是比较寄存器的值。在向上计数模式下当计数器值小于Pulse时输出有效电平可配置。我们设置Pulse为18结合下面的CH Polarity配置可以输出一个20us的高脉冲。CH Polarity 设置为High。这意味着PWM的有效电平Active Level为高。关键理解 计数器从0开始向上计数。当计数值 Pulse(18)时输出有效电平高当计数值 Pulse(18)时输出无效电平低。计数器计数到Period(19)后溢出产生更新事件并清零重新开始。因此会输出一个从计数开始到18为止的高电平持续19个计数周期这里需要校准。实际上为了得到一个精确的20us高脉冲我们需要仔细计算。更直观的做法是设置Period为1920个计数周期设置Pulse为19。这样在计数器从0计数到18期间19个周期输出高电平当计数器等于19时仅持续一个周期就溢出通常这个周期输出低。但这样高电平是19us。为了得到20us我们可以设置Period为20-119Pulse为20-119不对。让我们重新思考我们需要一个单次脉冲不是连续的PWM。更好的方法是利用One Pulse Mode单脉冲模式。启用单脉冲模式 回到Parameter Settings将One Pulse Mode设置为Enable。在该模式下定时器在收到触发事件后输出一个指定宽度的脉冲然后停止。这完美符合我们的需求。重新调整参数Prescaler71Period1920个计数周期20us。此时Pulse值就代表高电平的宽度。我们想要20us高电平那么Pulse应该设置为19在单脉冲模式下Pulse是捕获比较寄存器的值。当计数器值小于Pulse时输出有效电平。如果我们想要计数器从0到19计数期间都输出高电平20us那么Pulse应该设置为19但计数器等于19时下一个周期就溢出了。实际上在单脉冲模式下通常Pulse的值决定了高电平的持续时间。设置Pulse 19Period 19 则高电平时间为 (Pulse1) * 时钟周期 20 * 1us 20us。可以这样理解。经过实测和查阅资料一个可靠的配置是Prescaler71Period199Pulse19。这样定时器时钟1MHz周期200us高电平宽度20us。我们通过软件启动一次定时器它输出一个20us高脉冲后停止。这个Period值只要大于Pulse即可设置大一些没关系因为输出脉冲宽度只由Pulse决定。但为了节能和快速响应可以设小一点比如Period 3940us周期Pulse 1920us高电平。生成触发信号 配置好后在代码中我们只需要在需要测距时启动一次TIM1即可。// 启动一次单脉冲输出 HAL_TIM_OnePulse_Start(htim1, TIM_CHANNEL_1);这句代码会启动定时器输出一个设定好宽度的脉冲后自动停止。3.2 TIM2配置测量回波脉宽输入捕获模式Echo引脚的高电平持续时间就是超声波往返时间。我们用TIM2的输入捕获功能来测量它。引脚分配 找到PA0其复用功能是TIM2_CH1。点击PA0选择TIM2_CH1。定时器参数设置 左侧切换到Timers-TIM2。Clock Source 选择Internal Clock。Parameter SettingsPrescaler 设置为71。同样得到1MHz的计数频率1us的计数分辨率。对于测量几毫秒的脉宽对应几米的距离这个分辨率足够了。如果想更高精度可以减小分频值比如设置为35得到2MHz计数频率0.5us分辨率。Counter ModeUp。Counter Period 设置为最大值65535因为TIM2是16位定时器。超声波在空气中传播速度约340m/s测量1米的往返时间约为5.88ms即5880us。1MHz下计数值约为5880远小于65535所以溢出风险很低。但如果测量距离超过5米往返时间可能超过29ms计数值会超过30000仍然小于65535。为了保险我们可以开启定时器溢出中断或者在捕获回调函数中处理溢出情况。auto-reload preloadEnable。输入捕获通道配置 切换到Channel 1。Mode 选择Input Capture direct mode。IC SelectionDirect。表示捕获直接连接到通道的输入。IC Polarity 选择Rising Edge。我们首先在上升沿Echo变高捕获一次计数器值。IC Selection 保持Direct。IC PrescalerNo division。每个有效边沿都捕获。IC Filter 可以设置为一个较小的值如4用于滤除可能的高频毛刺。HC-SR04输出信号比较干净可以不滤波。开启中断 在NVIC Settings选项卡中勾选TIM2 global interrupt。这样在捕获事件发生时才能进入中断服务函数进行处理。注意 这里有一个非常重要的细节。我们只设置了上升沿捕获。为了测量高电平的宽度我们需要在上升沿记录一个时间戳t1然后在下降沿记录另一个时间戳t2。宽度就是t2 - t1。如何捕获下降沿呢我们可以在上升沿捕获的中断里动态改变捕获极性为下降沿。HAL库提供了相应的函数。4. 代码编写与驱动逻辑实现CubeMX生成代码后我们打开工程主要在main.c和stm32f1xx_it.c中断文件中添加业务逻辑。4.1 宏定义与全局变量在main.c的顶部用户变量区添加/* Private variables ---------------------------------------------------------*/ // 超声波测量相关变量 volatile uint32_t g_ultrasound_capture_start 0; // 上升沿捕获值 volatile uint32_t g_ultrasound_capture_width 0; // 高电平脉宽计数值 volatile uint8_t g_ultrasound_measure_done 0; // 测量完成标志 volatile uint8_t g_ultrasound_overflow_count 0; // 定时器溢出次数用于长距离测量volatile关键字告诉编译器这些变量可能被中断修改避免优化错误。4.2 输入捕获中断回调函数这是核心逻辑所在。HAL库采用了回调函数机制。我们需要重写输入捕获的回调函数HAL_TIM_IC_CaptureCallback。在main.c中找到/* USER CODE BEGIN 4 */和/* USER CODE END 4 */之间或者新建一个用户文件添加以下函数/** * brief 输入捕获中断回调函数 * param htim: 定时器句柄 * retval None */ void HAL_TIM_IC_CaptureCallback(TIM_HandleTypeDef *htim) { // 判断是否是TIM2的通道1发生捕获中断 if (htim-Instance TIM2) { if (htim-Channel HAL_TIM_ACTIVE_CHANNEL_1) { // 第一次捕获上升沿 if (g_ultrasound_capture_start 0) { // 记录上升沿时刻的计数器值 g_ultrasound_capture_start HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1); // 改变捕获极性为下降沿 __HAL_TIM_SET_CAPTUREPOLARITY(htim, TIM_CHANNEL_1, TIM_INPUTCHANNELPOLARITY_FALLING); // 清零溢出计数开始计算可能的中断溢出 g_ultrasound_overflow_count 0; } // 第二次捕获下降沿 else { // 记录下降沿时刻的计数器值 uint32_t capture_end HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1); // 计算高电平期间的计数值考虑溢出 // 公式脉宽 (溢出次数 * 定时器周期) (下降沿值 - 上升沿值) // 由于我们Period设置很大65535且测量距离有限通常不会溢出这里简化处理 g_ultrasound_capture_width capture_end - g_ultrasound_capture_start; // 标志测量完成 g_ultrasound_measure_done 1; // 停止捕获并重置状态准备下一次测量 HAL_TIM_IC_Stop_IT(htim, TIM_CHANNEL_1); // 重置捕获极性为上升沿 __HAL_TIM_SET_CAPTUREPOLARITY(htim, TIM_CHANNEL_1, TIM_INPUTCHANNELPOLARITY_RISING); // 清零起始值 g_ultrasound_capture_start 0; } } } }同时我们还需要处理定时器溢出中断以应对长距离测量计数值超过65535。重写定时器溢出回调函数/** * brief 定时器溢出中断回调函数 * param htim: 定时器句柄 * retval None */ void HAL_TIM_PeriodElapsedCallback(TIM_HandleTypeDef *htim) { if (htim-Instance TIM2) { // 如果已经捕获到上升沿即正在测量高电平期间则溢出计数加1 if (g_ultrasound_capture_start ! 0) { g_ultrasound_overflow_count; // 如果溢出次数太多可以认为超时强制结束测量可选 if (g_ultrasound_overflow_count 10) // 例如超过10次溢出约655ms { g_ultrasound_measure_done 2; // 超时标志 HAL_TIM_IC_Stop_IT(htim2, TIM_CHANNEL_1); __HAL_TIM_SET_CAPTUREPOLARITY(htim2, TIM_CHANNEL_1, TIM_INPUTCHANNELPOLARITY_RISING); g_ultrasound_capture_start 0; } } } }4.3 超声波测距函数我们封装一个函数用于触发一次测量并等待结果。/** * brief 执行一次超声波测距 * param p_distance_cm: 用于存储距离值单位厘米的指针 * retval 状态0-成功1-超时2-测量错误脉宽太短 */ uint8_t Ultrasound_Measure(uint32_t *p_distance_cm) { // 1. 清零标志和变量 g_ultrasound_measure_done 0; g_ultrasound_capture_width 0; g_ultrasound_capture_start 0; g_ultrasound_overflow_count 0; // 2. 启动输入捕获上升沿 HAL_TIM_IC_Start_IT(htim2, TIM_CHANNEL_1); // 3. 发送触发脉冲启动TIM1的单脉冲输出 HAL_TIM_OnePulse_Start(htim1, TIM_CHANNEL_1); // 4. 等待测量完成或超时 uint32_t timeout HAL_GetTick() 100; // 设置100ms超时 while (g_ultrasound_measure_done 0) { if (HAL_GetTick() timeout) { HAL_TIM_IC_Stop_IT(htim2, TIM_CHANNEL_1); // 停止捕获 return 1; // 超时 } } // 5. 判断测量结果 if (g_ultrasound_measure_done 2) { return 1; // 超时在溢出回调中标记 } // 6. 计算距离 // 高电平时间 t_us g_ultrasound_capture_width * (1 / 计数频率) // 计数频率 72MHz / (Prescaler1) 1MHz, 所以每个计数代表1us。 uint32_t time_us g_ultrasound_capture_width; // 单位微秒 // 超声波在空气中速度约340m/s即0.034cm/us。距离 (时间 * 速度) / 2 // 距离厘米 (time_us * 0.034) / 2 time_us * 0.017 // 为了免去浮点数运算可以近似为距离厘米 time_us / 58 // 因为 1 / 58 ≈ 0.01724误差很小。或者使用更精确的距离 time_us * 17 / 1000 *p_distance_cm time_us * 17 / 1000; // 使用整数运算 // 7. 有效性检查可选HC-SR04最小测量距离约2cm对应脉宽约116us。 // 最大测量距离约4m对应脉宽约23200us。可以在此范围内判断。 if (*p_distance_cm 2 || *p_distance_cm 400) { return 2; // 测量结果超出有效范围 } return 0; // 成功 }4.4 主循环逻辑在main函数的while (1)循环中我们可以周期性地进行测距。while (1) { uint32_t distance_cm 0; uint8_t status Ultrasound_Measure(distance_cm); if (status 0) { // 测量成功使用distance_cm printf(Distance: %lu cm\r\n, distance_cm); } else if (status 1) { printf(Measurement timeout!\r\n); } else { printf(Measurement error!\r\n); } HAL_Delay(100); // 每次测量间隔至少60ms给模块留出处理时间 }记得在main函数初始化部分启动TIM2的基计数但不启动捕获/* USER CODE BEGIN 2 */ // 启动TIM2的基计数器用于输入捕获的时基 HAL_TIM_Base_Start(htim2); /* USER CODE END 2 */5. 调试技巧与常见问题排查即使按照上述步骤配置在实际调试中也可能遇到各种问题。下面分享一些我踩过的坑和解决方法。5.1 完全没有捕获到信号现象 程序一直卡在Ultrasound_Measure函数的等待循环中超时返回。排查步骤检查硬件连接 确保VCC、GND连接正确且牢固。用万用表测量Echo引脚在触发后是否有电压变化从0V跳变到5V左右。如果没有可能是模块损坏或触发信号问题。检查触发信号 使用示波器或逻辑分析仪查看Trig引脚PA8是否有20us左右的高电平脉冲。如果没有检查TIM1的配置和启动代码HAL_TIM_OnePulse_Start是否执行。检查Echo信号 用示波器看Echo引脚。正常触发后应该会先有一段低电平模块内部处理时间然后产生一个高电平脉冲。如果根本没有高电平可能是模块前方有障碍物太近2cm或太远4m或者模块本身有问题。检查输入捕获配置 确认TIM2的通道1正确映射到PA0且配置为输入捕获模式。检查NVIC中断是否使能。检查代码逻辑 确保在发送触发脉冲之前已经启动了输入捕获中断HAL_TIM_IC_Start_IT。顺序很重要。5.2 测量值不稳定或误差大现象 距离值跳动很大或者与实际距离有固定偏差。排查与解决电源噪声 HC-SR04对电源比较敏感。确保电源能提供足够的电流峰值可达15mA并在VCC和GND之间并联一个10uF和0.1uF的电容进行滤波。环境干扰 超声波易受温度和气流影响。公式中的声速340m/s是在15°C下的值。温度变化时声速会变v 331.4 0.6 * T T为摄氏度。对于精度要求高的场合可以加入温度传感器进行补偿。测量原理误差 我们用的公式距离 时间 * 声速 / 2。声速本身随温度变化同时模块的发射和接收探头有一定距离约1-2cm对于极近的物体这会带来三角测量误差。一般模块的标称盲区是2cm就是这个原因。定时器分辨率 我们设置的分频是71得到1MHz计数频率理论分辨率是1us对应距离分辨率约0.017cm这已经足够。如果误差是固定倍数检查定时器时钟配置是否正确Prescaler和Period计算是否有误。多次测量取平均 在代码中连续进行5-10次测量去掉最大最小值后取平均可以显著平滑数据减少随机误差。#define MEASURE_TIMES 7 uint32_t sum 0; uint32_t buf[MEASURE_TIMES]; for(int i0; iMEASURE_TIMES; i) { Ultrasound_Measure(buf[i]); HAL_Delay(30); } // 简单的排序和去极值后求平均 // ... (排序算法) for(int i1; iMEASURE_TIMES-1; i) { // 去掉一个最高一个最低 sum buf[i]; } distance_cm sum / (MEASURE_TIMES-2);5.3 输入捕获中断只进入一次现象 第一次测量正常后续测量无法进入捕获回调函数。原因与解决 这通常是因为在回调函数中停止了定时器通道HAL_TIM_IC_Stop_IT但下一次测量前没有重新启动它。仔细检查Ultrasound_Measure函数在每次测量开始时都调用了HAL_TIM_IC_Start_IT。同时确保在测量结束或超时处理中没有错误地关闭了定时器基计数器HAL_TIM_Base_Stop。基计数器在整个程序运行期间应该只启动一次。5.4 长距离测量不准或溢出现象 测量距离超过1-2米后数据混乱。解决 我们的代码中简化处理了溢出。如果测量距离可能超过4-5米对应计数值29000就需要完善溢出处理逻辑。在HAL_TIM_IC_CaptureCallback中计算脉宽时公式应为g_ultrasound_capture_width (g_ultrasound_overflow_count * (htim-Instance-ARR 1)) (capture_end - g_ultrasound_capture_start);其中ARR是自动重装载值即Period。同时要确保g_ultrasound_overflow_count在每次测量开始时被清零并在定时器溢出回调函数HAL_TIM_PeriodElapsedCallback中正确递增。5.5 使用DMA提升效率进阶上述方法需要CPU介入中断处理。如果系统繁忙可能会丢失捕获边沿。对于更高要求可以使用定时器的PWM输入模式一个通道测量周期和占空比或者使用两个通道一个上升沿一个下降沿配合DMA将捕获值直接存储到内存完全无需中断。但这需要更复杂的配置且HC-SR04的回波是单次脉冲而非周期信号PWM输入模式可能不直接适用。一个可行的方案是使用一个定时器通道的输入捕获并开启DMA到循环缓冲区在下降沿触发DMA传输完成中断再去缓冲区计算脉冲宽度。这属于更高级的用法可以极大减轻CPU负担。6. 项目优化与扩展思路基础功能实现后可以考虑以下优化让项目更健壮、更实用。6.1 添加温度补偿如前所述声速受温度影响大。可以连接一个DS18B20之类的温度传感器实时获取环境温度修正声速公式。float temperature Read_Temperature(); // 读取温度单位摄氏度 float sound_speed_cm_per_us (331.4f 0.6f * temperature) / 10000.0f; // 转换为 cm/us float distance_cm (time_us * sound_speed_cm_per_us) / 2.0f;6.2 多传感器管理在自动导航小车中往往需要多个超声波传感器比如左、前、右。可以为每个传感器分配一对定时器通道一个触发PWM一个输入捕获或者使用一个定时器的多个通道。需要注意的是HC-SR04模块之间如果同时触发声波可能会互相干扰。通常采用分时复用的策略依次触发各个模块并留出足够的间隔时间60ms。6.3 与上层应用整合将超声波驱动封装成一个独立的.c/.h文件提供简洁的API如Ultrasound_Init(),Ultrasound_GetDistanceCM()。这样在主业务逻辑中只需调用接口即可实现驱动与应用的解耦。6.4 探索其他测距方案HC-SR04性价比高但也有一些缺点测量周期长60ms、易受环境干扰、角度大导致精度一般。对于更高速、更精准的应用可以考虑ToF传感器 如VL53L0X使用激光飞行时间原理精度高、响应快、抗干扰强但价格稍贵测量距离较短通常2米以内。毫米波雷达 如AWR1642可以测距、测速穿透性强不受光线和天气影响但成本高开发复杂。 选择哪种方案需要根据项目的具体需求成本、精度、速度、环境来权衡。