STM32超声波测距实战：HC-SR04模块从接线到代码调试全流程（避坑指南）

如果你正准备用STM32驱动那个经典的HC-SR04超声波模块，却发现网上教程要么语焉不详，要么代码一跑就出各种“灵异”问题——比如测距值乱跳、偶尔卡死、或者干脆没反应——那么你来对地方了。这篇文章不会给你一堆冰冷的代码让你自己琢磨，而是会像一位有经验的伙伴，带你从零开始，亲手把模块接好、代码调通，并且把那些新手最容易踩的坑一个个指出来，告诉你为什么会出现以及怎么解决。无论是实验室的课程设计，还是创客空间里的个人项目，这份结合了硬件实操与软件调试细节的指南，目标就是让你一次成功，少走弯路。

1. 硬件连接：别小看这几根线

很多人觉得硬件连接就是照着引脚图插上线而已，但恰恰是这一步，埋下了后续绝大多数问题的种子。HC-SR04模块看似简单，只有四个引脚，但每个引脚的处理都关乎系统的稳定。

1.1 引脚功能与电源的讲究

HC-SR04模块的四个引脚分别是VCC、Trig（触发）、Echo（回响）和GND。其中，VCC的供电电压是第一个关键点。模块上通常标注工作电压为5V。虽然有些3.3V系统也能勉强驱动，但为了确保发射功率和接收灵敏度，强烈建议使用稳定的5V电源。如果你的STM32开发板（如常见的STM32F103C8T6最小系统板）有独立的5V输出引脚，就从那里取电。如果只有3.3V，则需要考虑外部5V电源或电平转换电路。

注意：切勿将模块的VCC直接接到STM32的3.3V引脚上并期望它正常工作，这很可能导致测距极不稳定或干脆失效。

Echo引脚输出的是5V电平的高脉冲，而绝大多数STM32的GPIO引脚可承受的最高电压是3.3V。直接将5V信号接入会损坏单片机！因此，电平转换是必须的。最简单可靠的方法是使用一个电阻分压电路：

STM32 GPIO (输入) ---/\/\/\--- 1kΩ --- Echo (5V)
                         |
                        \|/
                       GND
                         |
                        \|/
                      2kΩ

这样，5V信号经过分压后，到达STM32引脚的电平大约是 5V * (2k/(1k+2k)) ≈ 3.33V，处于安全范围。你也可以使用专用的电平转换芯片（如TXS0108E）或光耦，但对于这个应用，电阻分压足够且成本极低。

1.2 接线布局与抗干扰

在面包板或杜邦线连接时，混乱的走线会引入噪声，尤其是对于Echo这种测量微妙时间间隔的信号线。以下是一些立竿见影的改善措施：

• 缩短走线：尽量让模块靠近STM32，特别是Echo信号线。
• 电源去耦：在HC-SR04的VCC和GND引脚之间，就近焊接一个10uF的电解电容和一个0.1uF的陶瓷电容，可以有效滤除电源噪声。
• 分开信号与电源地：如果可能，将数字地（单片机地）和模块电源地在一点连接，形成“星型接地”，减少地线环路噪声。

一个清晰的接线示意表如下：

STM32引脚	连接至HC-SR04	备注与关键点
5V 电源输出	VCC	确保是5V，电流能力>100mA
GND	GND	共地，连接点尽量短而粗
任一GPIO (如PA1)	Trig	推挽输出模式，直接连接
任一GPIO (如PA0)	Echo	必须经过分压电路，配置为上拉输入模式

2. 软件驱动原理：理解时序与捕获

硬件连接妥当后，我们来深入理解软件如何与模块“对话”。很多代码之所以不稳定，是因为对模块的时序要求和STM32的定时器机制理解不透彻。

2.1 HC-SR04的精确时序要求

模块的驱动逻辑非常清晰：

1. 触发：给Trig引脚一个至少10微秒的高电平脉冲。
2. 发射与回波：模块自动发射8个40kHz超声波，并检测回波。
3. 回响：Echo引脚输出一个高电平，其持续时间正比于超声波往返时间。

这里有两个极易被忽略的细节：

• 触发脉冲宽度：10us是最小值。在实际编程中，我通常会给出15-20us的脉冲，留有一定余量。脉冲太短可能导致触发失败。
• 测量间隔：两次触发测量之间需要至少60ms的间隔。这是模块内部处理所需的时间。如果在上一次回波未完全结束前就再次触发，会导致模块工作紊乱。所以主循环中的延时HAL_Delay(300)是合理的，但如果你追求更快刷新率，需要精确判断一次测量是否完全结束。

距离计算公式为：距离 = (高电平时间 * 声速) / 2。声速在常温下取340m/s或0.034cm/us。因此，在代码中，如果测得高电平时间为t（单位微秒），则距离（厘米）为 (t * 0.034) / 2。

2.2 STM32定时器输入捕获模式详解

测量Echo高电平的时间，是核心任务。使用普通的delay函数循环等待是极不准确且低效的。正确的方法是使用STM32定时器的输入捕获功能。

其工作原理是：定时器在后台自由运行计数，当捕获引脚（连接Echo）发生预设的边沿事件（如上升沿）时，硬件会自动将当前定时器的计数值锁存到专门的寄存器中，并可以产生中断。我们只需要在上升沿和下降沿的中断里读取这两个时刻的计数值，其差值就是高电平持续的计时器周期数，再乘以每个计数周期的时间，就得到了高电平时间。

以STM32F1的通用定时器TIM2为例，配置步骤的要点如下：

1. 时钟配置：在CubeMX中，确保TIM2的时钟源已使能，并且时钟频率是你所期望的。例如，如果APB1总线时钟为72MHz，TIM2的计数时钟通常也是72MHz。
2. 通道配置：将连接Echo的GPIO引脚（如PA0）配置为TIM2的Channel 1。
3. 参数设置：
   • Prescaler (分频器)：设置为71。这样，计数器时钟 = 72MHz / (71+1) = 1MHz，即每个计数代表1微秒，非常方便计算。
   • Counter Period (自动重装载值)：设置为最大值0xFFFF (65535)。因为一次测距最大对应约23.5ms的高电平时间（4米距离），1MHz时钟下对应23500个计数，远小于65535。
   • Capture/Compare Channel：选择Input Capture direct mode。
   • ICPolarity：初始设置为Rising Edge（上升沿捕获）。
   • IC Selection: 设置为Direct。
   • IC Filter：可以适当设置（如4），以滤除可能的高频毛刺。

配置完成后，生成的代码会初始化好定时器。我们只需要在合适的时候启动捕获，并在中断回调函数中处理即可。

3. 代码实战：健壮且可读的驱动实现

现在，我们将原理转化为实际代码。我将提供一个比常见示例更健壮、更具可读性的版本，并附上详细的注释。

3.1 头文件与宏定义 (sr04.h)

头文件清晰定义了接口和必要的宏。

#ifndef __SR04_H
#define __SR04_H

#include "main.h"
#include "tim.h"
#include <stdio.h>

// 硬件引脚宏定义，根据你的实际接线修改
#define TRIG_PORT        GPIOA
#define TRIG_PIN         GPIO_PIN_1

// 触发引脚操作宏，提高可读性
#define TRIG_HIGH()      HAL_GPIO_WritePin(TRIG_PORT, TRIG_PIN, GPIO_PIN_SET)
#define TRIG_LOW()       HAL_GPIO_WritePin(TRIG_PORT, TRIG_PIN, GPIO_PIN_RESET)

// 模块测量状态机
typedef enum {
    SR04_STATE_IDLE = 0,      // 空闲，等待触发
    SR04_STATE_WAIT_RISING,   // 已触发，等待上升沿
    SR04_STATE_WAIT_FALLING,  // 已捕获上升沿，等待下降沿
    SR04_STATE_CALCULATING    // 已捕获下降沿，计算距离
} SR04_State_t;

// 用户接口函数
void SR04_Init(void);
void SR04_StartMeasurement(void);
float SR04_GetLastDistance(void);
uint8_t SR04_IsMeasurementDone(void);

#endif

3.2 源文件实现 (sr04.c)

源文件包含了状态机、中断处理和简单的滤波。

#include "sr04.h"

// 模块内部状态变量
static SR04_State_t measure_state = SR04_STATE_IDLE;
static uint32_t rise_tick = 0;    // 上升沿捕获的定时器计数值
static uint32_t fall_tick = 0;     // 下降沿捕获的定时器计数值
static float last_distance_cm = 0.0; // 最后一次有效测量结果
static float distance_buffer[5] = {0}; // 滑动滤波缓冲区
static uint8_t buffer_index = 0;

// 简单的微秒级延时，用于产生Trig脉冲
static void delay_us(uint16_t us) {
    __HAL_TIM_SET_COUNTER(&htim2, 0); // 假设htim2已配置为1MHz时钟
    while (__HAL_TIM_GET_COUNTER(&htim2) < us);
}

/**
  * @brief  初始化超声波模块
  * @note   主要确保触发引脚为输出模式，并设置初始状态为低电平
  */
void SR04_Init(void) {
    GPIO_InitTypeDef GPIO_InitStruct = {0};
    // 初始化Trig引脚为推挽输出
    GPIO_InitStruct.Pin = TRIG_PIN;
    GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
    GPIO_InitStruct.Pull = GPIO_NOPULL;
    GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
    HAL_GPIO_Init(TRIG_PORT, &GPIO_InitStruct);
    TRIG_LOW(); // 初始化为低电平

    // 确保定时器中断已使能（CubeMX通常已配置好）
    // 清空状态
    measure_state = SR04_STATE_IDLE;
    last_distance_cm = 0.0;
    buffer_index = 0;
    for(int i=0; i<5; i++) distance_buffer[i] = 0.0;
}

/**
  * @brief  启动一次测量
  * @note   发送Trig脉冲，并启动定时器输入捕获。必须在模块空闲时调用。
  */
void SR04_StartMeasurement(void) {
    if(measure_state != SR04_STATE_IDLE) {
        // 上一次测量未完成，忽略本次请求或可在此处做错误处理
        return;
    }

    // 1. 发送10-20us的高电平Trig脉冲
    TRIG_HIGH();
    delay_us(20); // 使用定时器实现的精确延时
    TRIG_LOW();

    // 2. 配置定时器为上升沿捕获，并启动捕获
    __HAL_TIM_SET_CAPTUREPOLARITY(&htim2, TIM_CHANNEL_1, TIM_INPUTCHANNELPOLARITY_RISING);
    __HAL_TIM_SET_COUNTER(&htim2, 0); // 清零计数器，开始计时
    HAL_TIM_IC_Start_IT(&htim2, TIM_CHANNEL_1); // 启动输入捕获中断

    // 3. 更新状态
    measure_state = SR04_STATE_WAIT_RISING;
}

/**
  * @brief  定时器输入捕获中断回调函数
  * @note   由HAL库的HAL_TIM_IC_CaptureCallback调用，处理上升沿和下降沿
  */
void HAL_TIM_IC_CaptureCallback(TIM_HandleTypeDef *htim) {
    if(htim->Instance == TIM2) { // 确保是TIM2的中断
        switch(measure_state) {
            case SR04_STATE_WAIT_RISING:
                // 捕获到上升沿，记录时刻
                rise_tick = HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1);
                // 切换为下降沿捕获
                __HAL_TIM_SET_CAPTUREPOLARITY(&htim2, TIM_CHANNEL_1, TIM_INPUTCHANNELPOLARITY_FALLING);
                measure_state = SR04_STATE_WAIT_FALLING;
                break;

            case SR04_STATE_WAIT_FALLING:
                // 捕获到下降沿，记录时刻并停止捕获
                fall_tick = HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1);
                HAL_TIM_IC_Stop_IT(htim, TIM_CHANNEL_1);
                measure_state = SR04_STATE_CALCULATING;
                break;

            default:
                // 不应进入的状态，进行错误恢复
                HAL_TIM_IC_Stop_IT(htim, TIM_CHANNEL_1);
                measure_state = SR04_STATE_IDLE;
                break;
        }
    }
}

/**
  * @brief  检查测量是否完成并处理数据
  * @note   需要在主循环中周期性调用，非阻塞式处理计算结果
  */
void SR04_Process(void) {
    if(measure_state == SR04_STATE_CALCULATING) {
        uint32_t pulse_width_us;

        // 处理计数器溢出：如果下降沿计数值小于上升沿，说明计数器溢出了
        if(fall_tick >= rise_tick) {
            pulse_width_us = fall_tick - rise_tick;
        } else {
            // 65535是16位定时器的最大值，假设分频后1MHz
            pulse_width_us = (0xFFFF - rise_tick) + fall_tick + 1;
        }

        // 计算单次距离（厘米）
        float single_distance = (pulse_width_us * 0.0343) / 2.0; // 0.0343是更精确的声速值

        // 简单的滑动平均滤波
        distance_buffer[buffer_index] = single_distance;
        buffer_index = (buffer_index + 1) % 5;

        float sum = 0;
        uint8_t valid_count = 0;
        for(int i = 0; i < 5; i++) {
            // 过滤掉明显异常的值（例如小于2cm或大于400cm）
            if(distance_buffer[i] > 2.0 && distance_buffer[i] < 400.0) {
                sum += distance_buffer[i];
                valid_count++;
            }
        }
        if(valid_count > 0) {
            last_distance_cm = sum / valid_count;
        }

        // 状态恢复为空闲，准备下一次测量
        measure_state = SR04_STATE_IDLE;
    }
}

// 获取最后一次有效测量结果
float SR04_GetLastDistance(void) {
    return last_distance_cm;
}

// 检查模块是否空闲（可以开始新的测量）
uint8_t SR04_IsMeasurementDone(void) {
    return (measure_state == SR04_STATE_IDLE);
}

3.3 主函数集成 (main.c)

主循环的逻辑变得非常清晰和健壮。

#include "main.h"
#include "sr04.h"
#include <stdio.h>

// ... 其他外设初始化代码（由CubeMX生成）

int main(void) {
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_TIM2_Init();
    MX_USART1_UART_Init();

    // 初始化超声波模块
    SR04_Init();

    // 启动第一次测量
    SR04_StartMeasurement();
    uint32_t last_measure_time = HAL_GetTick();

    while (1) {
        // 非阻塞式处理测量结果
        SR04_Process();

        // 每隔100ms尝试启动一次新的测量（确保大于模块的60ms周期）
        uint32_t current_time = HAL_GetTick();
        if((current_time - last_measure_time > 100) && SR04_IsMeasurementDone()) {
            SR04_StartMeasurement();
            last_measure_time = current_time;

            // 获取并打印距离
            float dist = SR04_GetLastDistance();
            if(dist > 2.0 && dist < 400.0) { // 输出有效范围内的值
                printf("Distance: %.2f cm\r\n", dist);
            } else {
                printf("Out of range or error.\r\n");
            }
        }

        // 其他任务...
        HAL_Delay(10);
    }
}

4. 调试与排坑：从现象到根源的解决方法

即使按照上述步骤操作，你可能还是会遇到一些问题。下面是一些常见故障现象及其排查思路。

4.1 现象一：读数始终为0或极小值

• 可能原因1：Echo引脚一直为低电平。

  • 检查接线：确认Echo线是否连接正确，分压电路电阻值是否准确，接触是否良好。
  • 检查模块：尝试更换一个HC-SR04模块，排除模块本身损坏的可能。
  • 逻辑分析仪/示波器观察：这是最直接的方法。观察Trig引脚是否有清晰的脉冲，Echo引脚是否有高电平脉冲输出。如果没有，问题在模块或触发端。

• 可能原因2：定时器输入捕获未正确触发。

  • 检查GPIO复用：确认用于Echo的GPIO引脚已正确配置为定时器输入捕获模式，而不是普通的输入模式。
  • 检查定时器配置：确认定时器的时钟已使能，分频器设置正确（确保计数周期为1us或你期望的单位）。
  • 检查中断：确认定时器捕获中断已使能，并且中断服务函数被正确调用。可以在HAL_TIM_IC_CaptureCallback函数开头加一个翻转LED的代码来测试。

4.2 现象二：读数乱跳，波动巨大

• 可能原因1：电源噪声。

  • 解决方案：如前所述，在模块VCC和GND之间增加滤波电容（10uF并联0.1uF），并确保电源线足够粗。
  • 检查共地：确保STM32和HC-SR04的GND是直接、可靠地连接在一起的。

• 可能原因2：环境声波干扰。

  • HC-SR04对40kHz的声波敏感。如果环境中存在类似频率的噪声（如某些开关电源、电机驱动器的啸叫），会导致误触发。
  • 解决方案：让模块远离噪声源。或者，在软件上增加连续多次测量取中值或均值的滤波算法，比简单的滑动平均更能抵抗突发干扰。可以修改SR04_Process函数，加入排序取中值的逻辑。

• 可能原因3：代码中的时序竞争或状态机错误。

  • 确保SR04_StartMeasurement函数不会被过于频繁地调用，必须等待上一次测量完成（SR04_IsMeasurementDone返回1）。
  • 检查状态机逻辑，确保不会因为中断嵌套或意外情况导致状态混乱。在状态切换的关键点可以添加一些条件判断或状态复位逻辑。

4.3 现象三：测量距离明显不准（偏大或偏小）

• 可能原因：声速值不准确。
  • 声速受温度影响较大。公式 V = 331.4 + 0.6 * T，其中T是摄氏温度。在20°C时，声速约为343m/s，即0.0343cm/us，这与我们代码中使用的值一致。但如果环境温度变化很大，可以尝试加入温度传感器（如DS18B20）进行动态补偿。
  • 校准：在实际已知距离（例如50.0cm）处测量，记录得到的pulse_width_us值，反推出声速常数，并替换代码中的0.0343。

4.4 现象四：程序偶尔卡死或无响应

• 可能原因：中断服务函数处理时间过长或存在死循环。
  • 确保HAL_TIM_IC_CaptureCallback中断回调函数执行速度非常快，只做最基本的记录值和切换状态的操作，复杂的计算（如滤波、打印）放到主循环的SR04_Process中。
  • 检查是否在中断中调用了类似HAL_Delay这样的阻塞函数，这绝对要避免。
  • 检查全局变量在中断和主循环之间的访问是否可能产生竞争。虽然本例中简单的赋值和读取在32位单片机上通常是原子的，但对于更复杂的结构，可以考虑暂时关闭中断进行保护。

调试时，善用printf通过串口打印内部状态变量（如rise_tick, fall_tick, measure_state）是非常有效的手段。它可以帮助你清晰地看到程序运行到了哪一步，数据是否正确。