STM32F103C8T6驱动HC-SR04超声波测距：PlatformIO与AI辅助实战-平芜编程栈

最近在做一个智能小车项目，需要用到超声波测距模块来避障。手头正好有经典的“蓝桥杯”开发板——STM32F103C8T6最小系统板，以及最常见的HC-SR04超声波模块。整个过程从环境搭建、代码编写到烧录调试，踩了不少坑，也积累了一些高效的方法。本文将分享一个完整的实战流程，特别引入了AI辅助代码生成和PlatformIO+VSCode的开发环境，让你即使不熟悉底层寄存器，也能快速上手实现测距功能。无论你是嵌入式新手，还是想体验现代化开发工具的老手，都能从这篇“保姆级”教程中找到清晰的路径。

1. 项目背景与核心硬件介绍

在开始动手之前，我们先明确一下这个项目要做什么，以及用到的核心硬件是什么。这对于理解后续的代码和配置至关重要。

1.1 项目目标：STM32驱动HC-SR04测距

我们的目标是使用STM32F103C8T6单片机，通过GPIO口控制HC-SR04超声波模块，测量前方障碍物的距离，并将结果通过串口打印到电脑上显示。这是一个非常经典的嵌入式入门实验，涵盖了GPIO输入输出、定时器计时、串口通信等核心知识点。

1.2 核心硬件详解

1. STM32F103C8T6最小系统板这是ST公司基于ARM Cortex-M3内核的经典微控制器，因其性价比极高，常被称为“单片机界的Hello World”。它拥有64KB Flash、20KB RAM，主频最高72MHz，完全能满足我们测距项目的需求。最小系统板意味着它已经集成了复位电路、晶振和基本的电源电路，我们只需要连接下载器和外围传感器即可工作。

2. HC-SR04超声波测距模块这是最普及的超声波测距传感器。其工作原理很简单：

触发：单片机向模块的Trig引脚发送一个至少10us的高电平脉冲。
发射与接收：模块自动发出8个40kHz的超声波脉冲，并开始检测回波。
回响：当模块接收到返回的回波后，Echo引脚会输出一个高电平，其持续时间与超声波往返时间成正比。
计算距离：距离 = (高电平时间 * 声速) / 2。声速在常温下可取340m/s。

模块工作电压为5V，但Echo引脚输出的是5V TTL电平。而STM32的GPIO引脚通常耐受3.3V电压，因此直接连接有损坏MCU的风险，这是第一个需要注意的坑点。

3. ST-Link V2调试/下载器这是ST官方推出的调试编程器，支持SWD接口，比传统的JTAG占用引脚更少。我们将使用它来给STM32烧录程序。市面上常见的“山寨”ST-Link也基本兼容，是性价比之选。

1.3 为什么选择PlatformIO + AI辅助？

传统的STM32开发往往依赖于Keil MDK或STM32CubeIDE，它们功能强大但略显笨重，且Keil的代码编辑体验一般。PlatformIO是一个开源的嵌入式开发平台，可以完美集成在VSCode中，提供代码补全、库管理、一键编译下载等现代化功能，极大提升了开发效率。

而AI辅助编程（如基于大语言模型的代码生成工具）在嵌入式开发中，尤其适合生成那些有固定模式的初始化代码、驱动函数或处理繁琐的配置。我们可以用自然语言描述需求，让AI生成基础框架，然后我们再进行调试和优化，这能帮助初学者快速跨越“从零开始”的恐惧，将精力集中在理解原理和解决问题上。

2. 开发环境搭建与准备

工欲善其事，必先利其器。这一节我们将完成所有软件工具的安装和配置。

2.1 安装Visual Studio Code与PlatformIO插件

安装VSCode：从官网下载并安装最新版的Visual Studio Code。
安装PlatformIO插件：打开VSCode，点击左侧活动栏的“扩展”图标，搜索“PlatformIO IDE”，找到由PlatformIO官方发布的插件并安装。安装过程会自动下载PlatformIO Core，可能需要一些时间，请保持网络通畅。

2.2 安装ST-Link驱动

要让电脑识别ST-Link下载器，必须安装驱动。

将ST-Link通过USB线连接到电脑。
访问ST官网或通过可靠渠道搜索“STSW-LINK009”下载ST-Link驱动包。
解压并运行安装程序。安装成功后，在Windows设备管理器的“通用串行总线设备”或“调试接口”下应能看到“STMicroelectronics STLink USB communications”等设备。

常见问题：如果驱动安装失败或设备显示黄色感叹号，可以尝试：

以管理员身份运行安装程序。
使用第三方驱动管理工具（如“驱动精灵”的离线版）进行安装。
更换USB口或数据线。

2.3 创建PlatformIO项目

在VSCode中，点击左侧的PlatformIO图标（蚂蚁头）。
点击“PIO Home”中的“New Project”。
在弹出的窗口中配置项目：
- Name: 输入项目名，如stm32_hc-sr04。
- Board: 在搜索框输入stm32f103c8t6，选择“BluePill F103C8”（这是该芯片最小系统板的通用别名）。
- Framework: 选择“HAL”（硬件抽象层）。HAL库比标准库更上层，可移植性更好，适合新手快速开发。
- Location: 选择你的项目存放路径。
点击“Finish”。PlatformIO会自动创建项目骨架，并下载对应的芯片支持包和HAL库，这可能需要几分钟。

注意：PlatformIO创建工程慢是常见问题，主要原因是需要从国外服务器下载资源。解决方法有：使用网络工具、配置国内镜像源，或者提前下载好离线包。

3. 硬件连接与电平转换方案

正确的硬件连接是项目成功的第一步，特别是电平问题必须解决。

3.1 连接示意图与引脚定义

我们需要连接STM32、HC-SR04和ST-Link。以下是连接关系表：

设备	引脚	连接到STM32引脚	说明
HC-SR04	VCC	5V	接开发板的5V引脚
HC-SR04	GND	GND	共地
HC-SR04	Trig	PA1	触发信号输出（STM32输出）
HC-SR04	Echo	PA0	回响信号输入（STM32输入）需电平转换
ST-Link	SWDIO	PA13	数据线
ST-Link	SWCLK	PA14	时钟线
ST-Link	3.3V	3.3V	给MCU供电（可选，如果板子有独立供电）
ST-Link	GND	GND	共地

STM32F103C8T6引脚图是必备参考资料，务必确认你板子的具体引脚排列。PA0和PA1是普通的GPIO口，我们这里随意选用，你可以根据实际情况更换。

3.2 5V转3.3V电平转换方案

由于Echo引脚输出5V，而STM32的PA0只能承受3.3V，直接连接可能烧毁引脚。这里有几种安全方案：

方案一：电阻分压（最经济）在Echo信号线上串联两个电阻进行分压。例如，使用一个1kΩ电阻和一個2kΩ电阻串联。Echo信号经过分压后，输入到PA0的电压约为 5V * (2k/(1k+2k)) ≈ 3.33V，在安全范围内。

HC-SR04 Echo --- 1kΩ电阻 --- PA0 (STM32) | 2kΩ电阻 | GND

方案二：使用电平转换模块（最省心）购买专用的双向或单向电平转换模块（如TXS0108E、74HC244等），将5V信号安全地转换为3.3V。

方案三：使用开发板上的5V耐受引脚（需查手册）有些STM32型号的特定引脚（标注为“FT”的引脚）可以耐受5V。但STM32F103C8T6的大部分GPIO并非5V耐受，不推荐冒险尝试。

本项目后续代码基于方案一（电阻分压）或方案二（已转换）进行，即默认Echo输入已是3.3V电平。

4. AI辅助生成代码框架

现在进入核心环节——编写代码。我们将分步骤利用AI工具（你可以使用任何你熟悉的、合规的AI编程助手）来生成主体代码，然后进行人工调整和解释。

4.1 向AI描述需求

我们可以向AI输入如下提示词（Prompt）：

请为STM32F103C8T6（使用HAL库）编写一个驱动HC-SR04超声波模块的代码。 要求： 1. 使用PA1引脚作为Trig输出，PA0引脚作为Echo输入。 2. 实现一个函数`float Get_Distance(void)`，返回以厘米为单位的距离值。 3. 使用定时器来精确测量Echo高电平的持续时间。 4. 在main函数中初始化后，循环调用测距函数，并通过串口1（USART1， PA9-TX, PA10-RX）将距离值打印输出。 5. 添加必要的错误处理，比如测量超时（超过一定时间未收到回波）。 请提供完整的`main.c`文件代码，并附上关键步骤的注释。

4.2 AI生成的代码分析与调整

AI可能会生成类似下面的代码。我们来分段解读并指出需要手动修改的关键点。

/* 文件：src/main.c */ #include "stm32f1xx_hal.h" /* 定义引脚 */ #define TRIG_PIN GPIO_PIN_1 #define TRIG_PORT GPIOA #define ECHO_PIN GPIO_PIN_0 #define ECHO_PORT GPIOA /* 定义定时器句柄 */ TIM_HandleTypeDef htim2; /* 定义超时时间（单位：ms）和最大测量距离 */ #define MEASURE_TIMEOUT 60 // 对应约10米超时 (34000cm/s * 0.06s / 2 ≈ 1020cm) #define MAX_DISTANCE 400 // 最大有效距离，单位cm /* 函数声明 */ void SystemClock_Config(void); static void MX_GPIO_Init(void); static void MX_USART1_UART_Init(void); static void MX_TIM2_Init(void); float Get_Distance(void); int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_USART1_UART_Init(); MX_TIM2_Init(); printf("HC-SR04 Test Start!\r\n"); while (1) { float distance = Get_Distance(); if (distance > 0 && distance <= MAX_DISTANCE) { printf("Distance: %.2f cm\r\n", distance); } else if (distance > MAX_DISTANCE) { printf("Out of range (> %d cm)\r\n", MAX_DISTANCE); } else { printf("Measurement error or timeout.\r\n"); } HAL_Delay(500); // 每500ms测量一次 } } float Get_Distance(void) { uint32_t start_time = 0, end_time = 0; float distance_cm = 0; // 1. 发送至少10us的Trig高脉冲 HAL_GPIO_WritePin(TRIG_PORT, TRIG_PIN, GPIO_PIN_SET); HAL_Delay(0.01); // 延迟10微秒， HAL_Delay最小单位是1ms，这里不精确！ HAL_GPIO_WritePin(TRIG_PORT, TRIG_PIN, GPIO_PIN_RESET); // 2. 等待Echo变为高电平（开始计时） while (HAL_GPIO_ReadPin(ECHO_PORT, ECHO_PIN) == GPIO_PIN_RESET); HAL_TIM_Base_Start(&htim2); // 启动定时器2 start_time = __HAL_TIM_GET_COUNTER(&htim2); // 3. 等待Echo变为低电平（停止计时） while (HAL_GPIO_ReadPin(ECHO_PORT, ECHO_PIN) == GPIO_PIN_SET) { // 添加超时检测 if (__HAL_TIM_GET_COUNTER(&htim2) - start_time > MEASURE_TIMEOUT * 1000) { // 假设定时器频率1MHz，1us计数一次 HAL_TIM_Base_Stop(&htim2); return -1; // 超时返回错误 } } end_time = __HAL_TIM_GET_COUNTER(&htim2); HAL_TIM_Base_Stop(&htim2); // 4. 计算时间差和距离 uint32_t pulse_time = end_time - start_time; // 单位：us (微秒) // 距离 = (时间 * 声速) / 2 // 声速 340m/s = 34000 cm/s = 0.034 cm/us // 所以 距离(cm) = 脉冲时间(us) * 0.034 / 2 = 脉冲时间 * 0.017 distance_cm = pulse_time * 0.017f; return distance_cm; } /* 以下初始化函数通常由STM32CubeMX生成，这里给出关键部分 */ static void MX_TIM2_Init(void) { TIM_ClockConfigTypeDef sClockSourceConfig = {0}; TIM_MasterConfigTypeDef sMasterConfig = {0}; htim2.Instance = TIM2; htim2.Init.Prescaler = 72 - 1; // 系统时钟72MHz， 分频后为1MHz (1us计数一次) htim2.Init.CounterMode = TIM_COUNTERMODE_UP; htim2.Init.Period = 0xFFFFFFFF; // 最大周期 htim2.Init.ClockDivision = TIM_CLOCKDIVISION_DIV1; if (HAL_TIM_Base_Init(&htim2) != HAL_OK) { Error_Handler(); } // ... 更多配置 } static void MX_GPIO_Init(void) { GPIO_InitTypeDef GPIO_InitStruct = {0}; __HAL_RCC_GPIOA_CLK_ENABLE(); /* 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); HAL_GPIO_WritePin(TRIG_PORT, TRIG_PIN, GPIO_PIN_RESET); // 初始化为低电平 /* Echo引脚配置为输入 */ GPIO_InitStruct.Pin = ECHO_PIN; GPIO_InitStruct.Mode = GPIO_MODE_INPUT; GPIO_InitStruct.Pull = GPIO_PULLDOWN; // 下拉，避免悬空时误触发 HAL_GPIO_Init(ECHO_PORT, &GPIO_InitStruct); } static void MX_USART1_UART_Init(void) { // USART1初始化代码，波特率设置为115200 // 注意：需要重定向printf到串口，下文会说明 }

AI代码的问题与我们的修改：

Trig脉冲不精确：AI使用了HAL_Delay(0.01)，但HAL_Delay的单位是毫秒(ms)，无法实现10微秒(us)的精确延时。我们需要用定时器或简单的空循环for语句替代。
定时器配置可能不完整：AI生成的MX_TIM2_Init函数可能缺少关键步骤，我们需要一个能精确到微秒的定时器。
printf重定向未实现：代码中使用了printf，但未将其输出重定向到串口，这会导致程序卡死或无输出。
超时判断逻辑有瑕疵：超时计算依赖于定时器频率，需要确保一致。

5. 手动优化与关键代码实现

接下来，我们针对AI代码的不足，进行手动修改和优化，形成最终可用的代码。

5.1 精确的Trig脉冲生成

去掉不精确的HAL_Delay，改用简单的空循环来产生10us高电平。虽然空循环受编译器优化影响，但在72MHz主频下，经过简单校准后足以满足HC-SR04的要求。

// 替换Get_Distance函数中发送Trig脉冲的部分 // 发送至少10us的Trig高脉冲 HAL_GPIO_WritePin(TRIG_PORT, TRIG_PIN, GPIO_PIN_SET); for(int i=0; i<80; i++){ __NOP(); } // 大约10us的延迟，需要根据实际时钟校准 HAL_GPIO_WritePin(TRIG_PORT, TRIG_PIN, GPIO_PIN_RESET);

5.2 完善定时器2初始化

定时器2需要配置为以1MHz的频率向上计数，即每1微秒计数一次。这样我们读取的计数器差值就是微秒数。

static void MX_TIM2_Init(void) { TIM_ClockConfigTypeDef sClockSourceConfig = {0}; TIM_MasterConfigTypeDef sMasterConfig = {0}; htim2.Instance = TIM2; htim2.Init.Prescaler = 72 - 1; // 系统时钟72MHz， 72分频后得到1MHz (1us计数一次) htim2.Init.CounterMode = TIM_COUNTERMODE_UP; htim2.Init.Period = 0xFFFFFFFF; // 自动重装载值为最大值 htim2.Init.ClockDivision = TIM_CLOCKDIVISION_DIV1; htim2.Init.AutoReloadPreload = TIM_AUTORELOAD_PRELOAD_DISABLE; if (HAL_TIM_Base_Init(&htim2) != HAL_OK) { Error_Handler(); } sClockSourceConfig.ClockSource = TIM_CLOCKSOURCE_INTERNAL; if (HAL_TIM_ConfigClockSource(&htim2, &sClockSourceConfig) != HAL_OK) { Error_Handler(); } sMasterConfig.MasterOutputTrigger = TIM_TRGO_RESET; sMasterConfig.MasterSlaveMode = TIM_MASTERSLAVEMODE_DISABLE; if (HAL_TIMEx_MasterConfigSynchronization(&htim2, &sMasterConfig) != HAL_OK) { Error_Handler(); } }

5.3 实现printf串口重定向

为了让printf函数通过USART1输出，我们需要重写_write系统调用函数。

在main.c文件中添加以下代码：

/* 包含标准输入输出头文件 */ #include <stdio.h> /* 重定向printf到USART1 */ #ifdef __GNUC__ #define PUTCHAR_PROTOTYPE int __io_putchar(int ch) #else #define PUTCHAR_PROTOTYPE int fputc(int ch, FILE *f) #endif PUTCHAR_PROTOTYPE { HAL_UART_Transmit(&huart1, (uint8_t *)&ch, 1, HAL_MAX_DELAY); return ch; }

同时，确保MX_USART1_UART_Init函数正确初始化了huart1句柄，并且USART1的时钟和引脚（PA9, PA10）已使能。

5.4 优化后的Get_Distance函数

综合以上修改，这是优化后的测距函数：

float Get_Distance(void) { uint32_t start_time = 0, end_time = 0; float distance_cm = 0; uint32_t timeout_counter = 0; // 1. 发送至少10us的Trig高脉冲 HAL_GPIO_WritePin(TRIG_PORT, TRIG_PIN, GPIO_PIN_SET); for(int i=0; i<80; i++){ __NOP(); } // 粗略10us延时 HAL_GPIO_WritePin(TRIG_PORT, TRIG_PIN, GPIO_PIN_RESET); // 2. 等待Echo变为高电平（开始计时） while (HAL_GPIO_ReadPin(ECHO_PORT, ECHO_PIN) == GPIO_PIN_RESET); HAL_TIM_Base_Start(&htim2); start_time = __HAL_TIM_GET_COUNTER(&htim2); // 3. 等待Echo变为低电平（停止计时），并加入超时判断 while (HAL_GPIO_ReadPin(ECHO_PORT, ECHO_PIN) == GPIO_PIN_SET) { end_time = __HAL_TIM_GET_COUNTER(&htim2); // 超时判断：如果高电平持续时间超过60ms（对应约10米），则认为超时 if ((end_time - start_time) > 60000) { // 定时器1us计数一次，60000对应60ms HAL_TIM_Base_Stop(&htim2); return -1.0f; // 返回错误值 } } end_time = __HAL_TIM_GET_COUNTER(&htim2); HAL_TIM_Base_Stop(&htim2); // 4. 计算时间差和距离 uint32_t pulse_time = end_time - start_time; // 单位：微秒(us) // 距离 = (时间(us) * 声速(cm/us)) / 2 = 时间 * 0.034 / 2 = 时间 * 0.017 distance_cm = pulse_time * 0.017f; // 5. 过滤异常值（例如极短的脉冲） if(distance_cm < 2.0f) { return -2.0f; // 距离过近或测量错误 } return distance_cm; }

6. PlatformIO项目配置与编译

代码写好了，接下来需要配置PlatformIO来编译它。

6.1 配置platformio.ini文件

PlatformIO项目的核心配置文件是根目录下的platformio.ini。我们需要根据STM32F103C8T6和HAL库进行配置。

; platformio.ini [env:bluepill_f103c8] platform = ststm32 board = bluepill_f103c8 framework = stm32cube board_build.mcu = stm32f103c8t6 ; 使用HAL库 build_flags = -D USE_HAL_DRIVER -D STM32F103xB ; 芯片系列宏定义，必须与型号匹配 ; 配置调试和上传工具为stlink upload_protocol = stlink debug_tool = stlink ; 启用串口打印支持（为printf重定向） build_unflags = -fno-builtin-printf build_flags += -Wl,-u,_printf_float ; 允许printf打印浮点数

关键点说明：

board = bluepill_f103c8：指定了开发板类型。
framework = stm32cube：使用STM32Cube框架，包含了HAL库。
-D STM32F103xB：这个宏定义非常重要，它告诉编译器芯片的存储容量和寄存器映射，必须与stm32f103c8t6匹配（属于中等容量产品）。
-Wl,-u,_printf_float：链接器选项，允许printf输出浮点数，否则%.2f将无法工作。

6.2 编译项目

在VSCode中，点击底部状态栏的“√”图标（编译），或按快捷键Ctrl+Alt+B（Windows/Linux）进行编译。PlatformIO会自动调用编译器（GCC）进行编译。

如果编译成功，终端会显示SUCCESS，并在.pio/build目录下生成.elf、.bin、.hex等文件。
如果编译失败，请根据终端输出的错误信息排查。常见错误包括：
- 头文件找不到：检查platformio.ini中的framework和build_flags。
- 未定义的引用：检查函数是否正确定义，或是否缺少源文件。

7. 使用ST-Link烧录程序与调试

编译成功后，我们将生成的固件烧录到STM32芯片中。

7.1 硬件连接ST-Link

确保ST-Link与STM32开发板正确连接：

ST-Link SWDIO->STM32 PA13
ST-Link SWCLK->STM32 PA14
ST-Link GND->STM32 GND
ST-Link 3.3V->STM32 3.3V(如果开发板已通过USB独立供电，此线可不接)

7.2 一键烧录

在PlatformIO中，烧录非常简单：

点击底部状态栏的“→”图标（上传），或按快捷键Ctrl+Alt+U。
PlatformIO会自动调用stlink工具进行烧录。终端会显示擦除、编程、验证的进度。
看到SUCCESS提示，即表示烧录完成。

7.3 串口监视与结果查看

程序烧录后会自动运行。我们需要通过串口查看测距结果。

将STM32的USART1的TX（PA9）引脚通过USB转TTL模块连接到电脑的USB口。
在VSCode中，点击左侧PlatformIO图标，选择“Project Tasks” ->bluepill_f103c8-> “Monitor”。
或者点击底部状态栏的“插头”图标（串口监视器）。
在打开的终端中，设置波特率为115200（与代码中初始化的一致）。
你应该能看到类似以下的输出：
```
HC-SR04 Test Start! Distance: 15.32 cm Distance: 15.29 cm Distance: 15.35 cm ...
```
用手在传感器前移动，距离值应该会相应变化。

如果串口没有输出，请按顺序排查：

检查串口线连接是否正确（TX->RX, RX->TX, GND->GND）。
检查电脑设备管理器中是否正确识别了USB转TTL的COM口。
检查PlatformIO Monitor的波特率设置是否与代码（115200）一致。
检查代码中printf重定向和USART1初始化是否正确。
尝试按一下开发板的复位键。

8. 常见问题与深度优化

在实际操作中，你可能会遇到以下问题。这里提供排查思路和进阶优化方案。

8.1 编译与烧录常见问题

问题现象	可能原因	解决思路
编译错误：`stm32f1xx_hal.h: No such file`	框架或芯片包未正确安装	1. 检查`platformio.ini`中`framework`设置。 2. 在PIO Home的“Platforms”中重新安装`ststm32`平台。
上传失败：`ST-Link connection error`	ST-Link驱动未安装或连接问题	1. 确认设备管理器中ST-Link驱动正常。 2. 检查SWDIO、SWCLK、GND连线是否牢固。 3. 尝试给STM32板子重新上电。
程序运行一次后无法再次烧录	芯片进入睡眠、写保护或复位电路异常	1. 按住板子复位键，点击上传，在开始上传的瞬间松开复位键（复位法）。 2. 检查代码中是否禁用了SWD引脚（PA13, PA14）。 3. 使用STM32 ST-Link Utility工具进行芯片擦除。
串口监视器无任何输出	串口配置错误或硬件问题	1. 使用“串口助手”等独立软件测试USB转TTL模块本身是否正常。 2. 用万用表测量PA9（TX）引脚在程序运行时是否有电压变化。 3. 检查代码中`SystemClock_Config()`是否正确配置了系统时钟（特别是外部晶振HSE）。

8.2 测量不准与软件优化

测量值跳动大：

原因：超声波在空气中传播受温度、湿度影响；模块本身有±3mm的误差；环境中有多个反射面。
优化：软件滤波。例如，连续采样5次，去掉最大最小值后取平均。

#define SAMPLE_NUM 5 float Get_Average_Distance(void) { float sum = 0; float readings[SAMPLE_NUM]; int valid_count = 0; for(int i=0; i<SAMPLE_NUM; i++) { float d = Get_Distance(); if(d > 2.0 && d < 400.0) { // 有效值范围 readings[valid_count++] = d; } HAL_Delay(10); // 小延时避免干扰 } if(valid_count < 3) return -1.0f; // 有效数据太少 // 简单冒泡排序找最大最小值 (可优化) // ... 排序代码 ... // 去掉一个最高分和一个最低分 for(int i=1; i<valid_count-1; i++) { sum += readings[i]; } return sum / (valid_count-2); }

声速校准：
- 上述代码使用0.034cm/us的声速，对应25°C干燥空气。精度要求高时，可加入温度传感器（如DS18B20）进行实时声速补偿。公式：V = 331.4 + 0.6 * T，其中T为摄氏温度。
使用输入捕获功能：
- 当前代码使用查询方式等待Echo引脚变化，会占用CPU。更高效、更精确的方法是使用定时器的输入捕获功能。将Echo引脚连接到定时器的输入捕获通道（如TIM2_CH1），可以硬件自动记录高电平开始和结束的时刻，精度极高且不占用CPU。这是生产级项目推荐的做法。

8.3 工程结构与代码管理建议

模块化：将HC-SR04的驱动代码单独放在hc_sr04.c和hc_sr04.h文件中，使主程序更清晰。
宏定义配置：将Trig、Echo引脚、定时器、超时时间等参数通过宏定义在头文件中，方便移植到其他项目。
错误码枚举：定义清晰的错误码（如HC_SR04_OK,HC_SR04_TIMEOUT,HC_SR04_ERROR），代替简单的-1返回值，提高代码可读性。
版本控制：使用Git管理你的项目，特别是platformio.ini和关键源代码。

通过以上八个步骤，我们完成了从环境搭建、AI辅助编码、手动优化、编译烧录到调试排错的完整流程。这个项目不仅让你掌握了HC-SR04的驱动原理，更重要的是实践了基于PlatformIO的现代化STM32开发流程，并体验了AI作为编程助手的潜力与边界。下一步，你可以尝试将测距数据用OLED显示，或者结合舵机实现一个简单的超声波雷达扫描，让项目更加有趣。

STM32F103C8T6驱动HC-SR04超声波测距：PlatformIO与AI辅助实战