简介本资源是一套基于STM32F10x系列的超声波测距嵌入式项目工程面向嵌入式初学者与课程设计实践者解决距离实时感知、多模态反馈OLED可视化蜂鸣器报警及传感器驱动整合等典型开发问题。压缩包含103个文件以42个.h头文件和40个.c源文件为主体涵盖STM32标准外设库核心模块如usart、tim、i2c、rcc、adc等辅以.uvprojx工程配置、.hex烧录文件、.bat一键清理脚本及调试配置文件整体体积仅418KB结构完整、即开即用。已有5908人学习下载资源由实战经验开发者整理代码逻辑清晰、注释充分特别适合理解超声波时序控制、I²C/OLED驱动移植、中断式测距算法实现及低功耗蜂鸣器触发机制等关键技能点可直接用于课程实验、毕业设计或竞赛原型开发。1. 项目概述与核心需求解析1.1 这个项目到底要做什么STM32 超声波 OLED 蜂鸣器这组合听起来像是一堆矿卡玩家的攒机清单但实际上是嵌入式入门里非常经典的“传感器采集—数据处理—显示交互—输出告警”四段式闭环练习。你给的这个标题我拆一下其实暗含了三个明确需求用 STM32 作为主控芯片完成超声波测距的数据读取把测得的距离实时显示到 0.96 寸 OLED 屏幕上当距离低于设定阈值时触发蜂鸣器短响警告实现“近距离报警”的作用。这个项目的典型应用场景非常广最常见的比如倒车雷达、盲区监测演示、智能垃圾桶满溢提醒、机器人避障、或者纯粹作为电赛/嵌入式课程设计的入门练手项目。可以说只要你以后走嵌入式这个方向这套“传感器主控外设”的搭配逻辑几乎贯穿着每一个阶段。我第一次做这个项目的时候是用面包板加杜邦线搭的OLED 装上 I2C 屏幕、超声波的 Trig 和 Echo 各接一根线、蜂鸣器用一个三极管驱动整个过程不算复杂但调试过程中踩的坑却是扎扎实实的收获。这篇就围绕整个项目的完整开发流程来写从原理、接线、代码到排查思路把每一步为什么这么做都说清楚。1.2 为什么值得碰这个项目很多人学完 STM32 点灯、按键、定时器、串口之后会进入一个比较迷茫的阶段学了这么多外设怎么组合成一个有实际价值的系统这个项目就是最好的中间过渡。它覆盖了 STM32 的三大基础外设状态GPIO控制 Trig 输出、读取 Echo 电平、驱动蜂鸣器定时器用于测量高电平持续时间通信接口I2C 驱动 OLED 屏再加上“软件滤波”“阈值判断”“显示刷新”“报警逻辑”这些系统设计思路几乎把嵌入式开发的基础流程都揉进去了。而且每个模块都是独立可拆的你可以在不改变整体结构的情况下把超声波换成红外传感器或者把 OLED 换成 LCD实现项目升级。这也是我非常推荐新手去碰它的原因成本低逻辑清晰反馈直观有空间扩展。2. 核心硬件选型与工作原理2.1 超声波模块HC-SR04 的时序和参数目前市面上最普及的超声波模块就是 HC-SR04价格几块钱性能稳定资料海量。它的原理其实特别简单模块上有两个换能器探头一个是发射端T一个是接收端R工作时由 STM32 给 Trig 脚一个 10us 以上的高电平脉冲模块内部就会自动发射 8 个 40kHz 的方波脉冲同时 Echo 引脚会输出一个高电平当接收端检测到回波后Echo 输出才变低。也就是说Echo 的高电平持续时长 超声波从发射到返回的总时间。因此距离公式就是距离cm 高电平时间us / 58更严谨的换算距离 时间 × 声速340m/s ÷ 2声速在空气中大约 340m/s但实际受温度影响摄氏 20 度时是 343m/s严苛一点的话可以做温度补偿。不过对于课程设计级别的应用直接用 58 除法已经足够。HC-SR04 的几个关键参数你要记牢工作电压 5V注意逻辑电平也是 5VSTM32 容忍度没问题测量范围 2cm~400cm精度约 0.3cmTrig 输入低电平复位高电平触发Echo 输出高电平时间对应距离这里要特别提醒Echo 输出的是 5V 高电平如果接到一部分 3.3V 供电的板子比如 ESP32、STM32 部分引脚建议接一个分压电阻将 Echo 电压降到 3.3V 再送入 MCU。不过 STM32F103 的大部分引脚标注是 5V 容忍实际应用里直接接也没有大问题但我个人建议还是稳妥为主串 1k 电阻或者加个二极管钳位都可以。还有一个很多人忽略的点HC-SR04 的 Trig 和 Echo 分开引脚不要在初始化时把两者配置为同一种模式。Trig 必须推挽输出Echo 必须浮空输入。如果输出模式设置错了Echo 永远读不到有效电平。2.2 OLED 屏0.96 寸 I2C 驱动OLED 我用的是 0.96 寸、128x64 分辨率、I2C 接口的版本SSD1306 控制芯片。选它的原因有三个省引脚只需要 SCL 和 SDA 两根数据线、功耗低、显示效果好。项目实时性要求不高I2C 刷屏完全够用。关于 OLED 屏要注意的硬件细节模块电压一般是 3.3V~5V但最好接 3.3V因为逻辑电平是 3.3V 更安全I2C 地址默认是 0x787 位地址 0x3C有些厂家的模块是 0x7A驱动代码里把地址改一下即可屏幕背面有电阻可以配置地址一般在模块背面丝印上标了 SA0、SA1改动比较麻烦多数情况不需要动如果不显示优先怀疑接线顺序SCL、SDA 接反是最常见的低级错误。SSD1306 驱动本身比较简单初始化序列 显存1KB 写显存函数 绘制字符函数基本就构成了 OLED 的全部用法。后面代码部分我会直接给出移植思路重点说清楚 SSD1306 的显存组织方式你理解了再看任何版本的 OLED 驱动都不会懵。2.3 蜂鸣器有源 vs 无源别搞混了蜂鸣器分成“有源”和“无源”两类其实跟供电没关系核心区别是内部有没有振荡源有源蜂鸣器内部自带振荡电路只要给直流电平就会发出固定频率的声音最适合做报警提示无源蜂鸣器需要外部输入一定频率的方波才能发声适合做音乐播放但因为频率可控所以音色变化多。这个项目做“短距报警”我们直接用有源蜂鸣器最省事给高电平就响给低电平就停。如果选无源蜂鸣器你需要用定时器产生 2kHz 或者 4kHz 的 PWM 方波来控制音调代码复杂度会高不少但也不是不行。驱动电路方面STM32 的 GPIO 输出能力只有几毫安直接驱动蜂鸣器顶多发出蚊子样的响声而且长时间过流还可能烧引脚。所以必须加一个驱动管通常用 NPN 三极管S8050或者 N-MOS 管。我是这么接的GPIO 接三极管基极串一个 1k 限流电阻蜂鸣器正极接 VCC3.3V 或 5V负极接三极管集电极三极管发射极接地蜂鸣器两端并联一个续流二极管1N4148防止断电瞬间的反向电动势打坏管子。这套电路是教科书级的低边驱动电路你以后驱动继电器、小马达、电磁阀都能复用值得背下来。3. 软件架构与代码设计思路3.1 全局流程一个超级循环的日常整个系统的软件逻辑并不复杂本质上是一个持续不断的循环初始化GPIO、定时器、I2C、OLED、系统时钟主循环触发一次超声波测量等待 Echo 高电平结束记录时长换算成距离做简单滤波多次采样取平均或去极值判断距离是否小于阈值根据结果决定蜂鸣器状态刷新 OLED 显示延时防抖进入下一轮。这里有个最重要的设计问题怎么测量 Echo 高电平的时间有四种常见方案我列个对比表方案原理优点缺点适用场景轮询延时循环等待电平跳变用延时函数计时简单直观占用 CPU无法做多任务入门教学定时器输入捕获用定时器捕获上升沿/下降沿精确不阻塞配置复杂工业级外部中断定时器Echo 触发中断读 CNT比较精确中断处理频繁进阶项目内部定时器查询计数开启定时器后轮询 CNT 值简单且精度足够仍占用 CPU本项目推荐我最终选用的是“定时器查询计数”方案因为代码写起来简洁精度也完全满足厘米级要求。具体做法是Echo 从低变高后启动定时器计数频率 1MHz这样每个计数单位是 1us然后循环等待 Echo 变低读到定时器 CNT 值就是高电平持续了多少微秒。为什么不直接用输入捕获因为输入捕获需要监听两个边沿配合中断写起来代码量更大而且容易在中断里做除法和浮点运算拖慢主循环。对于这种非高频、非实时性要求极高的场景查询式完全够用。3.2 代码分层让这个项目能“长大”写代码不要一棵树上吊死。STM32 项目如果所有逻辑都堆在 main.c 里初期觉得爽后期改一个功能就头晕。我推荐按功能模块拆文件bsp_ultrasonic.c / .h —— 超声波模块的驱动bsp_oled.c / .h —— OLED 显示驱动基于 SSD1306bsp_beep.c / .h —— 蜂鸣器控制app_main.c —— 业务逻辑测距、判断、显示刷新这样拆的好处很明显你以后想换一个传感器只需要改 bsp_ultrasonic.c 对应的接口上层逻辑完全不动OLED 换成 LCD 同理业务逻辑段也不需要重写。嵌入式开发的工程管理能力就是“高内聚、低耦合”最好的练手场。接口方面我给超声波模块定义这样的 APIvoid Ultra_Init(void); float Ultra_GetDistance_cm(void);而蜂鸣器模块则是void Beep_Init(void); void Beep_On(uint16_t duration_ms); void Beep_Off(void);OLED 则是void OLED_Init(void); void OLED_Clear(void); void OLED_ShowDistance(float dist_cm);上层 main 循环里调用这些接口就够了看起来像拼积木但实际上这种模块化思维在你以后接触 FreeRTOS、RT-Thread、甚至做大型嵌入式项目时都非常重要。3.3 延时与防抖你不知道的小坑超声波模块的标准触发流程是Trig 低电平至少 2us再拉高至少 10us最后拉低。这里用到的延时精度要求不高直接用delay_us()即可。但如果你的延时函数本身写得不靠谱Trig 的高电平时间不足 10us模块就是触发不了。这也是很多人写代码第一步就卡住的地方。延时函数的实现我建议直接用 DWTData Watchpoint and Trace或者 SysTick做法是写一个基于 sysTick 的微秒级延时函数然后触发逻辑里确保高电平时间至少有 20us留一点余量void Ultra_Trigger(void) { HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_RESET); delay_us(5); HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_SET); delay_us(20); // 至少 10us给足余量 HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_RESET); }关于防抖主循环里的延时非常重要。HC-SR04 的测量周期建议大于 60ms因为超声波在空中传播 模块内部处理需要时间如果触发的频率太高会导致回波混乱距离数据跳变。60ms 对应大概每秒 16 次测量人眼刷新 OLED 完全够用不会觉得卡。4. 关键代码实现与踩坑实录4.1 STM32CubeMX 初始化配置要点如果你用 STM32CubeMX 来生成工程配置很简单但有几个地方务必留意时钟树建议把系统时钟配置到 72MHzF103 系列最高频率因为后面定时器计数频率和延时函数的精度都依赖系统时钟GPIOTrig 配置为推挽输出、无上下拉、高速Echo 配置为浮空输入蜂鸣器引脚也是推挽输出定时器开启一个基本定时器比如 TIM2设置预分频为 71自动重载值给到 0xFFFF这样计数频率就是 72MHz / (711) 1MHz即 1us 计数一次I2C如果 OLED 用硬件 I2C选 I2C1速率默认 100kHz 或 400kHz 均可注意引脚不要和其他外设冲突。配置完生成代码后CubeMX 生成的初始化函数已经帮我们做好了 HAL_Init 和系统时钟配置你只需要在 main 里添加自己的模块初始化。4.2 超声波测距代码从触发到计算这是整个项目最核心的代码。我直接把我的实现贴出来加了详细注释/* bsp_ultrasonic.c */ #include bsp_ultrasonic.h #include main.h extern TIM_HandleTypeDef htim2; void Ultra_Init(void) { // GPIO 初始化在 CubeMX 中已完成 } void Ultra_Trigger(void) { HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_RESET); delay_us(5); HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_SET); delay_us(20); HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_RESET); } float Ultra_GetDistance_cm(void) { uint32_t timeout 0; uint32_t count 0; float distance_cm 0.0f; Ultra_Trigger(); // 等待 Echo 变为高电平 timeout 0; while (HAL_GPIO_ReadPin(ECHO_GPIO_Port, ECHO_Pin) GPIO_PIN_RESET) { if (timeout 50000) // 约 50ms 超时保护 return -1.0f; // 超时返回-1表示测量失败 } // Echo 为高启动定时器计数 __HAL_TIM_SET_COUNTER(htim2, 0); while (HAL_GPIO_ReadPin(ECHO_GPIO_Port, ECHO_Pin) GPIO_PIN_SET) { if (timeout 50000) // 再次超时保护防止长时间卡住 return -1.0f; count __HAL_TIM_GET_COUNTER(htim2); } // 距离cm 时间(us) / 58 distance_cm count / 58.0f; return distance_cm; }有几个关键细节我要单独说超时保护是必须写的。如果前方没有障碍物或者探头朝天花板Echo 可能永远不拉低代码会卡死在 while 里整个系统就假死了。加了超时判断后最多 50ms 就会返回错误值返回 -1 表示测量失败上层就要做容错处理比如这次直接用上一次的有效距离或者蜂鸣器长鸣提示除以 58 还是 58.2 的问题网上有人用 58有人用 58.2这取决于模块的晶振和声速修正。实测下来标准 HC-SR04 用 58 在 20~100cm 内误差在 ±0.5cm 左右能够满足绝大多数场景。想要更精确就用 58.2差别不大如果测量距离跳动厉害可以考虑“滑动平均滤波”例如保留最近 5 次数据去掉最大最小值后取平均。4.3 OLED 显示地址与刷新要注意的细节SSD1306 的 OLED 驱动如果不是用现成的库自己移植也不难。最核心的是理解它的显存组织方式128x64 的屏幕分成 8 页Page每页 8 像素高共 128 列。你向某一页的某一列写入一个字节时这个字节的每一位就对应了该列在该页内垂直方向的 8 个像素点低位在上面高位在下面。这个“页寻址”方式直接决定了显示字符的函数怎么写。我用的字体是 6x8 和 8x16 两种前者一页能显示 21 个字符128/6后者能显示 16 个字符128/8。实际驱动代码里你需要实现这几个函数void OLED_WriteCmd(uint8_t cmd); // 发送命令字节 void OLED_WriteData(uint8_t data); // 发送数据字节 void OLED_SetCursor(uint8_t page, uint8_t column); // 设置显示位置 void OLED_Clear(void); // 清屏 void OLED_ShowChar(uint8_t page, uint8_t col, uint8_t ch); void OLED_ShowString(uint8_t page, uint8_t col, char *str);如果使用硬件 I2C 发送每个字节前面要加 0x00命令或 0x40数据前缀这是由 SSD1306 的 I2C 协议规定的。很多新手在这里犯错直接把裸数据发过去屏幕没反应。我在代码里习惯这样封装void OLED_WriteCmd(uint8_t cmd) { uint8_t buffer[2] {0x00, cmd}; HAL_I2C_Master_Transmit(hi2c1, OLED_ADDR, buffer, 2, 100); } void OLED_WriteData(uint8_t data) { uint8_t buffer[2] {0x40, data}; HAL_I2C_Master_Transmit(hi2c1, OLED_ADDR, buffer, 2, 100); }OLED 初始化的序列一般可以直接用厂家提供的但有几个命令要说一下0xAF是开启显示千万别漏0x8D, 0x14是开启电荷泵漏了屏幕就是黑的0x20, 0x00设置为水平寻址模式这样操作显存更方便0xA1设置段重映射如果你的屏幕显示镜像了调这个命令。如果你不想自己写底层也可以用满大街都是的中景园 OLED 驱动源码直接移植到 HAL 库也很简单核心就是替换I2C_WriteByte函数。4.4 蜂鸣器报警短响策略与逻辑设计蜂鸣器报警不是“低于阈值就一直响”那太粗暴了。更好的设计是“短响提醒”当距离小于 30cm 时每 500ms 响一次每次 100ms距离小于 20cm 时每 250ms 响一次小于 10cm 时持续短促蜂鸣。这样用户就能通过声音频率判断距离变化有点像汽车倒车雷达的“滴-滴-滴-”急促感。拿非阻塞思路实现这个逻辑不要用HAL_Delay去卡否则整个系统延时会很糟糕。我用的是状态机 系统 tick 的方法typedef struct { uint16_t beep_on_ms; uint16_t beep_off_ms; } BeepPattern; BeepPattern pattern_30cm {100, 400}; BeepPattern pattern_20cm {100, 150}; BeepPattern pattern_10cm {100, 50}; void Beep_Update(float dist_cm) { static uint32_t last_tick 0; static uint8_t beep_state 0; BeepPattern *p; uint32_t now HAL_GetTick(); if (dist_cm 10.0f) p pattern_10cm; else if (dist_cm 20.0f) p pattern_20cm; else if (dist_cm 30.0f) p pattern_30cm; else { Beep_Off(); beep_state 0; return; } if (beep_state 0 now - last_tick p-beep_off_ms) { Beep_On(); beep_state 1; last_tick now; } else if (beep_state 1 now - last_tick p-beep_on_ms) { Beep_Off(); beep_state 0; last_tick now; } }这种定时器驱动的“事件驱动”写法主循环不需要停下来等蜂鸣器极大提升系统响应能力。说实话很多做过 1~2 年嵌入式的人还习惯用HAL_Delay做延时报警看到这种思路会眼前一亮。5. 应用场景扩展与进阶方向5.1 倒车雷达与避障机器人这个项目最直接的应用就是倒车雷达。把超声波探头的安装朝向换成车尾方向OLED 屏幕放到驾驶位显示距离蜂鸣器放到车内做声音提示一个简单的倒车雷达原型就出来了。实际倒车雷达有多个探头、声音分级提示、障碍物方位判断等但核心原理和本项目一模一样。避障机器人也是热门方向超声波测距 舵机转向 电机驱动无非是把“蜂鸣器短响”替换成“电机转向决策”。5.2 加入温度补偿提高精度前面提到声速受温度影响如果你的应用场景温差变化大比如室外设备可以加一个 DS18B20 温度传感器公式变为声速 c 331.4 0.6 × TT 为摄氏度距离 时间 × c / 2这样在 0°C 到 40°C 之间误差可以从 ±3% 降到 ±0.5%对于精密测距场景很有价值。5.3 用 FreeRTOS 重构任务调度当项目功能增加后比如同时接多个传感器、OLED 要显示多个页面、蜂鸣器要发声同时还要处理串口指令这时候用裸机循环写就会显得手忙脚乱。改用 FreeRTOS把测距、显示、报警分别作为独立任务配合队列传递距离数据代码结构会更清晰。STM32CubeMX 直接支持 FreeRTOS 中间件创建任务、信号量、消息队列都是图形化配置值得尝试。6. 我踩过的坑与最终调试经验做这个项目的过程中我先后遇到过几个很典型的问题这里拿出来给大家参考问题 1OLED 屏幕不亮排查思路先量 OLED 模块的 VCC 和 GND看供电是否正常再用逻辑分析仪抓 I2C 波形看 SCL 和 SDA 有没有数据在跑最后检查初始化序列里有没有开启电荷泵命令 0x8D, 0x14。我遇到的最蠢的一次是 SCL 和 SDA 接反了屏幕死都不亮换回来就好了。问题 2超声波测距值恒定不变且都是 0 或最大值大概率是 Echo 引脚模式配置错了或者 Trig 的高电平时间不够。用示波器/逻辑分析仪同时看 Trig 和 Echo 两个脚如果 Trig 有脉冲但 Echo 一直是低说明模块压根没被触发去查 Trig 代码如果 Echo 有脉冲但读不到去查 Echo 引脚是否配置成输入。问题 3距离数据上下乱跳常见原因是超声波探头前方有斜面障碍物或者测距周期太短。HC-SR04 的波束角大约 15 度遇到倾斜表面会多次反射回波时间不稳定。解决方法是在代码里做滑动平均滤波或者把超声波模块安装固定好确保测量面尽量垂直。问题 4蜂鸣器声音很小或者不响先检查是不是把有源/无源搞混了。有源蜂鸣器直接给电平就响如果接成了无源蜂鸣器给直流电平不会响。再看驱动管是否焊反三极管的引脚顺序EBC别插错。我曾经就把 S8050 的基极和发射极插反了蜂鸣器一点声音都没有。问题 5程序跑一段时间后 OLED 显示花屏这是 I2C 通信受干扰的典型表现。排查方法缩短 I2C 引脚的杜邦线长度最好小于 10cm、给 OLED 模块和主控共地、把 SCL/SDA 加上拉电阻到 3.3V模块上一般自带、降低 I2C 速率到 100kHz。在电机类设备附近做项目还要注意避免把 I2C 线和电机电源线绑在一起走线。这些坑都不算复杂但每一个都能卡住新手半天甚至一天。排错的过程其实比写代码更有价值它逼着你去理解硬件、协议和芯片底层的行为。7. 最后的个人体会与建议如果你是从零开始做这个项目我建议不要急着一步到位而是分成四个阶段来走先点亮 OLED跑通“Hello World”单独调通超声波模块用串口打印距离值再结合 OLED 显示距离最后加入蜂鸣器报警逻辑。每一步都验证通过再往下走出了问题也能快速定位。这种方法在项目开发中叫“分层验证”本质上就是把大问题拆成小问题逐个击破效率远高于一口气写完再调试。硬件选择上主控用 STM32F103C8T6 蓝板或者 F103RCT6 都可以OLED 选 0.96 寸 I2C 版本最省事超声波模块 HC-SR04 就够蜂鸣器务必选有源且加三极管驱动。如果你想方便一点可以直接买一个超声波OLED 的组合模块有些厂家已经把它们做在一起了但那样学不到底层的东西我还是建议分开做。最后说一句真心话作为嵌入式入门必经之路超声波测距这个“集大成”的小项目无论对打基础还是应对课程设计、面试项目经历都非常能打。只要把这里面的原理吃透后面遇到任何传感器都只是换个驱动的问题那你就真正入门了。本文还有配套的精品资源点击获取 STM32超声波测距OLED显示蜂鸣器报警系统实战开发详解
简介本资源是一套基于STM32F10x系列的超声波测距嵌入式项目工程面向嵌入式初学者与课程设计实践者解决距离实时感知、多模态反馈OLED可视化蜂鸣器报警及传感器驱动整合等典型开发问题。压缩包含103个文件以42个.h头文件和40个.c源文件为主体涵盖STM32标准外设库核心模块如usart、tim、i2c、rcc、adc等辅以.uvprojx工程配置、.hex烧录文件、.bat一键清理脚本及调试配置文件整体体积仅418KB结构完整、即开即用。已有5908人学习下载资源由实战经验开发者整理代码逻辑清晰、注释充分特别适合理解超声波时序控制、I²C/OLED驱动移植、中断式测距算法实现及低功耗蜂鸣器触发机制等关键技能点可直接用于课程实验、毕业设计或竞赛原型开发。1. 项目概述与核心需求解析1.1 这个项目到底要做什么STM32 超声波 OLED 蜂鸣器这组合听起来像是一堆矿卡玩家的攒机清单但实际上是嵌入式入门里非常经典的“传感器采集—数据处理—显示交互—输出告警”四段式闭环练习。你给的这个标题我拆一下其实暗含了三个明确需求用 STM32 作为主控芯片完成超声波测距的数据读取把测得的距离实时显示到 0.96 寸 OLED 屏幕上当距离低于设定阈值时触发蜂鸣器短响警告实现“近距离报警”的作用。这个项目的典型应用场景非常广最常见的比如倒车雷达、盲区监测演示、智能垃圾桶满溢提醒、机器人避障、或者纯粹作为电赛/嵌入式课程设计的入门练手项目。可以说只要你以后走嵌入式这个方向这套“传感器主控外设”的搭配逻辑几乎贯穿着每一个阶段。我第一次做这个项目的时候是用面包板加杜邦线搭的OLED 装上 I2C 屏幕、超声波的 Trig 和 Echo 各接一根线、蜂鸣器用一个三极管驱动整个过程不算复杂但调试过程中踩的坑却是扎扎实实的收获。这篇就围绕整个项目的完整开发流程来写从原理、接线、代码到排查思路把每一步为什么这么做都说清楚。1.2 为什么值得碰这个项目很多人学完 STM32 点灯、按键、定时器、串口之后会进入一个比较迷茫的阶段学了这么多外设怎么组合成一个有实际价值的系统这个项目就是最好的中间过渡。它覆盖了 STM32 的三大基础外设状态GPIO控制 Trig 输出、读取 Echo 电平、驱动蜂鸣器定时器用于测量高电平持续时间通信接口I2C 驱动 OLED 屏再加上“软件滤波”“阈值判断”“显示刷新”“报警逻辑”这些系统设计思路几乎把嵌入式开发的基础流程都揉进去了。而且每个模块都是独立可拆的你可以在不改变整体结构的情况下把超声波换成红外传感器或者把 OLED 换成 LCD实现项目升级。这也是我非常推荐新手去碰它的原因成本低逻辑清晰反馈直观有空间扩展。2. 核心硬件选型与工作原理2.1 超声波模块HC-SR04 的时序和参数目前市面上最普及的超声波模块就是 HC-SR04价格几块钱性能稳定资料海量。它的原理其实特别简单模块上有两个换能器探头一个是发射端T一个是接收端R工作时由 STM32 给 Trig 脚一个 10us 以上的高电平脉冲模块内部就会自动发射 8 个 40kHz 的方波脉冲同时 Echo 引脚会输出一个高电平当接收端检测到回波后Echo 输出才变低。也就是说Echo 的高电平持续时长 超声波从发射到返回的总时间。因此距离公式就是距离cm 高电平时间us / 58更严谨的换算距离 时间 × 声速340m/s ÷ 2声速在空气中大约 340m/s但实际受温度影响摄氏 20 度时是 343m/s严苛一点的话可以做温度补偿。不过对于课程设计级别的应用直接用 58 除法已经足够。HC-SR04 的几个关键参数你要记牢工作电压 5V注意逻辑电平也是 5VSTM32 容忍度没问题测量范围 2cm~400cm精度约 0.3cmTrig 输入低电平复位高电平触发Echo 输出高电平时间对应距离这里要特别提醒Echo 输出的是 5V 高电平如果接到一部分 3.3V 供电的板子比如 ESP32、STM32 部分引脚建议接一个分压电阻将 Echo 电压降到 3.3V 再送入 MCU。不过 STM32F103 的大部分引脚标注是 5V 容忍实际应用里直接接也没有大问题但我个人建议还是稳妥为主串 1k 电阻或者加个二极管钳位都可以。还有一个很多人忽略的点HC-SR04 的 Trig 和 Echo 分开引脚不要在初始化时把两者配置为同一种模式。Trig 必须推挽输出Echo 必须浮空输入。如果输出模式设置错了Echo 永远读不到有效电平。2.2 OLED 屏0.96 寸 I2C 驱动OLED 我用的是 0.96 寸、128x64 分辨率、I2C 接口的版本SSD1306 控制芯片。选它的原因有三个省引脚只需要 SCL 和 SDA 两根数据线、功耗低、显示效果好。项目实时性要求不高I2C 刷屏完全够用。关于 OLED 屏要注意的硬件细节模块电压一般是 3.3V~5V但最好接 3.3V因为逻辑电平是 3.3V 更安全I2C 地址默认是 0x787 位地址 0x3C有些厂家的模块是 0x7A驱动代码里把地址改一下即可屏幕背面有电阻可以配置地址一般在模块背面丝印上标了 SA0、SA1改动比较麻烦多数情况不需要动如果不显示优先怀疑接线顺序SCL、SDA 接反是最常见的低级错误。SSD1306 驱动本身比较简单初始化序列 显存1KB 写显存函数 绘制字符函数基本就构成了 OLED 的全部用法。后面代码部分我会直接给出移植思路重点说清楚 SSD1306 的显存组织方式你理解了再看任何版本的 OLED 驱动都不会懵。2.3 蜂鸣器有源 vs 无源别搞混了蜂鸣器分成“有源”和“无源”两类其实跟供电没关系核心区别是内部有没有振荡源有源蜂鸣器内部自带振荡电路只要给直流电平就会发出固定频率的声音最适合做报警提示无源蜂鸣器需要外部输入一定频率的方波才能发声适合做音乐播放但因为频率可控所以音色变化多。这个项目做“短距报警”我们直接用有源蜂鸣器最省事给高电平就响给低电平就停。如果选无源蜂鸣器你需要用定时器产生 2kHz 或者 4kHz 的 PWM 方波来控制音调代码复杂度会高不少但也不是不行。驱动电路方面STM32 的 GPIO 输出能力只有几毫安直接驱动蜂鸣器顶多发出蚊子样的响声而且长时间过流还可能烧引脚。所以必须加一个驱动管通常用 NPN 三极管S8050或者 N-MOS 管。我是这么接的GPIO 接三极管基极串一个 1k 限流电阻蜂鸣器正极接 VCC3.3V 或 5V负极接三极管集电极三极管发射极接地蜂鸣器两端并联一个续流二极管1N4148防止断电瞬间的反向电动势打坏管子。这套电路是教科书级的低边驱动电路你以后驱动继电器、小马达、电磁阀都能复用值得背下来。3. 软件架构与代码设计思路3.1 全局流程一个超级循环的日常整个系统的软件逻辑并不复杂本质上是一个持续不断的循环初始化GPIO、定时器、I2C、OLED、系统时钟主循环触发一次超声波测量等待 Echo 高电平结束记录时长换算成距离做简单滤波多次采样取平均或去极值判断距离是否小于阈值根据结果决定蜂鸣器状态刷新 OLED 显示延时防抖进入下一轮。这里有个最重要的设计问题怎么测量 Echo 高电平的时间有四种常见方案我列个对比表方案原理优点缺点适用场景轮询延时循环等待电平跳变用延时函数计时简单直观占用 CPU无法做多任务入门教学定时器输入捕获用定时器捕获上升沿/下降沿精确不阻塞配置复杂工业级外部中断定时器Echo 触发中断读 CNT比较精确中断处理频繁进阶项目内部定时器查询计数开启定时器后轮询 CNT 值简单且精度足够仍占用 CPU本项目推荐我最终选用的是“定时器查询计数”方案因为代码写起来简洁精度也完全满足厘米级要求。具体做法是Echo 从低变高后启动定时器计数频率 1MHz这样每个计数单位是 1us然后循环等待 Echo 变低读到定时器 CNT 值就是高电平持续了多少微秒。为什么不直接用输入捕获因为输入捕获需要监听两个边沿配合中断写起来代码量更大而且容易在中断里做除法和浮点运算拖慢主循环。对于这种非高频、非实时性要求极高的场景查询式完全够用。3.2 代码分层让这个项目能“长大”写代码不要一棵树上吊死。STM32 项目如果所有逻辑都堆在 main.c 里初期觉得爽后期改一个功能就头晕。我推荐按功能模块拆文件bsp_ultrasonic.c / .h —— 超声波模块的驱动bsp_oled.c / .h —— OLED 显示驱动基于 SSD1306bsp_beep.c / .h —— 蜂鸣器控制app_main.c —— 业务逻辑测距、判断、显示刷新这样拆的好处很明显你以后想换一个传感器只需要改 bsp_ultrasonic.c 对应的接口上层逻辑完全不动OLED 换成 LCD 同理业务逻辑段也不需要重写。嵌入式开发的工程管理能力就是“高内聚、低耦合”最好的练手场。接口方面我给超声波模块定义这样的 APIvoid Ultra_Init(void); float Ultra_GetDistance_cm(void);而蜂鸣器模块则是void Beep_Init(void); void Beep_On(uint16_t duration_ms); void Beep_Off(void);OLED 则是void OLED_Init(void); void OLED_Clear(void); void OLED_ShowDistance(float dist_cm);上层 main 循环里调用这些接口就够了看起来像拼积木但实际上这种模块化思维在你以后接触 FreeRTOS、RT-Thread、甚至做大型嵌入式项目时都非常重要。3.3 延时与防抖你不知道的小坑超声波模块的标准触发流程是Trig 低电平至少 2us再拉高至少 10us最后拉低。这里用到的延时精度要求不高直接用delay_us()即可。但如果你的延时函数本身写得不靠谱Trig 的高电平时间不足 10us模块就是触发不了。这也是很多人写代码第一步就卡住的地方。延时函数的实现我建议直接用 DWTData Watchpoint and Trace或者 SysTick做法是写一个基于 sysTick 的微秒级延时函数然后触发逻辑里确保高电平时间至少有 20us留一点余量void Ultra_Trigger(void) { HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_RESET); delay_us(5); HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_SET); delay_us(20); // 至少 10us给足余量 HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_RESET); }关于防抖主循环里的延时非常重要。HC-SR04 的测量周期建议大于 60ms因为超声波在空中传播 模块内部处理需要时间如果触发的频率太高会导致回波混乱距离数据跳变。60ms 对应大概每秒 16 次测量人眼刷新 OLED 完全够用不会觉得卡。4. 关键代码实现与踩坑实录4.1 STM32CubeMX 初始化配置要点如果你用 STM32CubeMX 来生成工程配置很简单但有几个地方务必留意时钟树建议把系统时钟配置到 72MHzF103 系列最高频率因为后面定时器计数频率和延时函数的精度都依赖系统时钟GPIOTrig 配置为推挽输出、无上下拉、高速Echo 配置为浮空输入蜂鸣器引脚也是推挽输出定时器开启一个基本定时器比如 TIM2设置预分频为 71自动重载值给到 0xFFFF这样计数频率就是 72MHz / (711) 1MHz即 1us 计数一次I2C如果 OLED 用硬件 I2C选 I2C1速率默认 100kHz 或 400kHz 均可注意引脚不要和其他外设冲突。配置完生成代码后CubeMX 生成的初始化函数已经帮我们做好了 HAL_Init 和系统时钟配置你只需要在 main 里添加自己的模块初始化。4.2 超声波测距代码从触发到计算这是整个项目最核心的代码。我直接把我的实现贴出来加了详细注释/* bsp_ultrasonic.c */ #include bsp_ultrasonic.h #include main.h extern TIM_HandleTypeDef htim2; void Ultra_Init(void) { // GPIO 初始化在 CubeMX 中已完成 } void Ultra_Trigger(void) { HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_RESET); delay_us(5); HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_SET); delay_us(20); HAL_GPIO_WritePin(TRIG_GPIO_Port, TRIG_Pin, GPIO_PIN_RESET); } float Ultra_GetDistance_cm(void) { uint32_t timeout 0; uint32_t count 0; float distance_cm 0.0f; Ultra_Trigger(); // 等待 Echo 变为高电平 timeout 0; while (HAL_GPIO_ReadPin(ECHO_GPIO_Port, ECHO_Pin) GPIO_PIN_RESET) { if (timeout 50000) // 约 50ms 超时保护 return -1.0f; // 超时返回-1表示测量失败 } // Echo 为高启动定时器计数 __HAL_TIM_SET_COUNTER(htim2, 0); while (HAL_GPIO_ReadPin(ECHO_GPIO_Port, ECHO_Pin) GPIO_PIN_SET) { if (timeout 50000) // 再次超时保护防止长时间卡住 return -1.0f; count __HAL_TIM_GET_COUNTER(htim2); } // 距离cm 时间(us) / 58 distance_cm count / 58.0f; return distance_cm; }有几个关键细节我要单独说超时保护是必须写的。如果前方没有障碍物或者探头朝天花板Echo 可能永远不拉低代码会卡死在 while 里整个系统就假死了。加了超时判断后最多 50ms 就会返回错误值返回 -1 表示测量失败上层就要做容错处理比如这次直接用上一次的有效距离或者蜂鸣器长鸣提示除以 58 还是 58.2 的问题网上有人用 58有人用 58.2这取决于模块的晶振和声速修正。实测下来标准 HC-SR04 用 58 在 20~100cm 内误差在 ±0.5cm 左右能够满足绝大多数场景。想要更精确就用 58.2差别不大如果测量距离跳动厉害可以考虑“滑动平均滤波”例如保留最近 5 次数据去掉最大最小值后取平均。4.3 OLED 显示地址与刷新要注意的细节SSD1306 的 OLED 驱动如果不是用现成的库自己移植也不难。最核心的是理解它的显存组织方式128x64 的屏幕分成 8 页Page每页 8 像素高共 128 列。你向某一页的某一列写入一个字节时这个字节的每一位就对应了该列在该页内垂直方向的 8 个像素点低位在上面高位在下面。这个“页寻址”方式直接决定了显示字符的函数怎么写。我用的字体是 6x8 和 8x16 两种前者一页能显示 21 个字符128/6后者能显示 16 个字符128/8。实际驱动代码里你需要实现这几个函数void OLED_WriteCmd(uint8_t cmd); // 发送命令字节 void OLED_WriteData(uint8_t data); // 发送数据字节 void OLED_SetCursor(uint8_t page, uint8_t column); // 设置显示位置 void OLED_Clear(void); // 清屏 void OLED_ShowChar(uint8_t page, uint8_t col, uint8_t ch); void OLED_ShowString(uint8_t page, uint8_t col, char *str);如果使用硬件 I2C 发送每个字节前面要加 0x00命令或 0x40数据前缀这是由 SSD1306 的 I2C 协议规定的。很多新手在这里犯错直接把裸数据发过去屏幕没反应。我在代码里习惯这样封装void OLED_WriteCmd(uint8_t cmd) { uint8_t buffer[2] {0x00, cmd}; HAL_I2C_Master_Transmit(hi2c1, OLED_ADDR, buffer, 2, 100); } void OLED_WriteData(uint8_t data) { uint8_t buffer[2] {0x40, data}; HAL_I2C_Master_Transmit(hi2c1, OLED_ADDR, buffer, 2, 100); }OLED 初始化的序列一般可以直接用厂家提供的但有几个命令要说一下0xAF是开启显示千万别漏0x8D, 0x14是开启电荷泵漏了屏幕就是黑的0x20, 0x00设置为水平寻址模式这样操作显存更方便0xA1设置段重映射如果你的屏幕显示镜像了调这个命令。如果你不想自己写底层也可以用满大街都是的中景园 OLED 驱动源码直接移植到 HAL 库也很简单核心就是替换I2C_WriteByte函数。4.4 蜂鸣器报警短响策略与逻辑设计蜂鸣器报警不是“低于阈值就一直响”那太粗暴了。更好的设计是“短响提醒”当距离小于 30cm 时每 500ms 响一次每次 100ms距离小于 20cm 时每 250ms 响一次小于 10cm 时持续短促蜂鸣。这样用户就能通过声音频率判断距离变化有点像汽车倒车雷达的“滴-滴-滴-”急促感。拿非阻塞思路实现这个逻辑不要用HAL_Delay去卡否则整个系统延时会很糟糕。我用的是状态机 系统 tick 的方法typedef struct { uint16_t beep_on_ms; uint16_t beep_off_ms; } BeepPattern; BeepPattern pattern_30cm {100, 400}; BeepPattern pattern_20cm {100, 150}; BeepPattern pattern_10cm {100, 50}; void Beep_Update(float dist_cm) { static uint32_t last_tick 0; static uint8_t beep_state 0; BeepPattern *p; uint32_t now HAL_GetTick(); if (dist_cm 10.0f) p pattern_10cm; else if (dist_cm 20.0f) p pattern_20cm; else if (dist_cm 30.0f) p pattern_30cm; else { Beep_Off(); beep_state 0; return; } if (beep_state 0 now - last_tick p-beep_off_ms) { Beep_On(); beep_state 1; last_tick now; } else if (beep_state 1 now - last_tick p-beep_on_ms) { Beep_Off(); beep_state 0; last_tick now; } }这种定时器驱动的“事件驱动”写法主循环不需要停下来等蜂鸣器极大提升系统响应能力。说实话很多做过 1~2 年嵌入式的人还习惯用HAL_Delay做延时报警看到这种思路会眼前一亮。5. 应用场景扩展与进阶方向5.1 倒车雷达与避障机器人这个项目最直接的应用就是倒车雷达。把超声波探头的安装朝向换成车尾方向OLED 屏幕放到驾驶位显示距离蜂鸣器放到车内做声音提示一个简单的倒车雷达原型就出来了。实际倒车雷达有多个探头、声音分级提示、障碍物方位判断等但核心原理和本项目一模一样。避障机器人也是热门方向超声波测距 舵机转向 电机驱动无非是把“蜂鸣器短响”替换成“电机转向决策”。5.2 加入温度补偿提高精度前面提到声速受温度影响如果你的应用场景温差变化大比如室外设备可以加一个 DS18B20 温度传感器公式变为声速 c 331.4 0.6 × TT 为摄氏度距离 时间 × c / 2这样在 0°C 到 40°C 之间误差可以从 ±3% 降到 ±0.5%对于精密测距场景很有价值。5.3 用 FreeRTOS 重构任务调度当项目功能增加后比如同时接多个传感器、OLED 要显示多个页面、蜂鸣器要发声同时还要处理串口指令这时候用裸机循环写就会显得手忙脚乱。改用 FreeRTOS把测距、显示、报警分别作为独立任务配合队列传递距离数据代码结构会更清晰。STM32CubeMX 直接支持 FreeRTOS 中间件创建任务、信号量、消息队列都是图形化配置值得尝试。6. 我踩过的坑与最终调试经验做这个项目的过程中我先后遇到过几个很典型的问题这里拿出来给大家参考问题 1OLED 屏幕不亮排查思路先量 OLED 模块的 VCC 和 GND看供电是否正常再用逻辑分析仪抓 I2C 波形看 SCL 和 SDA 有没有数据在跑最后检查初始化序列里有没有开启电荷泵命令 0x8D, 0x14。我遇到的最蠢的一次是 SCL 和 SDA 接反了屏幕死都不亮换回来就好了。问题 2超声波测距值恒定不变且都是 0 或最大值大概率是 Echo 引脚模式配置错了或者 Trig 的高电平时间不够。用示波器/逻辑分析仪同时看 Trig 和 Echo 两个脚如果 Trig 有脉冲但 Echo 一直是低说明模块压根没被触发去查 Trig 代码如果 Echo 有脉冲但读不到去查 Echo 引脚是否配置成输入。问题 3距离数据上下乱跳常见原因是超声波探头前方有斜面障碍物或者测距周期太短。HC-SR04 的波束角大约 15 度遇到倾斜表面会多次反射回波时间不稳定。解决方法是在代码里做滑动平均滤波或者把超声波模块安装固定好确保测量面尽量垂直。问题 4蜂鸣器声音很小或者不响先检查是不是把有源/无源搞混了。有源蜂鸣器直接给电平就响如果接成了无源蜂鸣器给直流电平不会响。再看驱动管是否焊反三极管的引脚顺序EBC别插错。我曾经就把 S8050 的基极和发射极插反了蜂鸣器一点声音都没有。问题 5程序跑一段时间后 OLED 显示花屏这是 I2C 通信受干扰的典型表现。排查方法缩短 I2C 引脚的杜邦线长度最好小于 10cm、给 OLED 模块和主控共地、把 SCL/SDA 加上拉电阻到 3.3V模块上一般自带、降低 I2C 速率到 100kHz。在电机类设备附近做项目还要注意避免把 I2C 线和电机电源线绑在一起走线。这些坑都不算复杂但每一个都能卡住新手半天甚至一天。排错的过程其实比写代码更有价值它逼着你去理解硬件、协议和芯片底层的行为。7. 最后的个人体会与建议如果你是从零开始做这个项目我建议不要急着一步到位而是分成四个阶段来走先点亮 OLED跑通“Hello World”单独调通超声波模块用串口打印距离值再结合 OLED 显示距离最后加入蜂鸣器报警逻辑。每一步都验证通过再往下走出了问题也能快速定位。这种方法在项目开发中叫“分层验证”本质上就是把大问题拆成小问题逐个击破效率远高于一口气写完再调试。硬件选择上主控用 STM32F103C8T6 蓝板或者 F103RCT6 都可以OLED 选 0.96 寸 I2C 版本最省事超声波模块 HC-SR04 就够蜂鸣器务必选有源且加三极管驱动。如果你想方便一点可以直接买一个超声波OLED 的组合模块有些厂家已经把它们做在一起了但那样学不到底层的东西我还是建议分开做。最后说一句真心话作为嵌入式入门必经之路超声波测距这个“集大成”的小项目无论对打基础还是应对课程设计、面试项目经历都非常能打。只要把这里面的原理吃透后面遇到任何传感器都只是换个驱动的问题那你就真正入门了。本文还有配套的精品资源点击获取