1. 项目缘起与整体设计思路STM32 项目开源这件事我前前后后做过好几轮从最早只丢一个 Keil 工程压缩包到后来把代码、原理图、仿真文件打包成一套完整可复现的资料中间踩的坑真不少。这次要聊的这套开源项目核心就是三个东西代码、原理图、仿真。听起来简单但真正做过的人都知道能把这三样东西对齐、让别人拿到就能跑起来比写代码本身难得多。先说清楚这套东西是什么。它是一个基于 STM32F103C8T6 的最小系统级项目外设包含 DHT11 温湿度采集、超声波测距、串口通信以及一个可选的 OTA 升级框架。代码用标准库和 HAL 库双版本提供原理图用嘉立创 EDA 绘制仿真部分同时给了 Proteus 和 Wokwi 两套方案。适合谁看嵌入式入门到中级的朋友尤其是正在做毕业设计、课程设计或者想找一个能直接抄作业的完整工程参考的人。为什么我要强调“三件套对齐”因为绝大多数开源 STM32 项目只给代码原理图是截图仿真根本没有。你拿到代码引脚对不上想改硬件不知道原来怎么接的想验证逻辑还得自己搭板子。这套项目的设计初衷就是解决这个断层——代码里的每一个引脚定义都能在原理图上找到对应的网络标号原理图上的每一个器件都能在仿真里找到模型。这是我在实际带人做项目时总结出来的硬需求不是拍脑袋定的。整体设计上我遵循了几个原则。第一硬件最小化。能用软件模拟的绝不多加器件比如 DHT11 的数据线只加一个 4.7k 上拉电阻超声波模块直接用现成的 HC-SR04不自己搭发射接收电路。第二代码分层。驱动层、中间件层、应用层分开换芯片型号时只改驱动层。第三仿真优先。在打板之前所有逻辑必须能在仿真里跑通这样能省掉至少两轮打板费用。第四文档即代码。原理图的网络标号命名和代码里的宏定义完全一致比如DHT11_DATA_PIN对应原理图上的DHT11_DATA不搞两套命名。这套思路的好处是什么我举个例子。之前有个朋友拿我的工程去改想把 DHT11 换成 SHT30他只改了驱动层的三个函数应用层一行没动半天就调通了。如果代码和硬件是耦合的他得从头翻原理图、查数据手册、改引脚定义至少两天。这就是分层和命名对齐的价值。注意开源项目最怕的就是“我这边能跑你那边报错”。所以我在设计阶段就强制要求所有外设的初始化顺序、时钟配置、中断优先级都在文档里写清楚不靠口头传承。2. 核心细节解析与实操要点2.1 代码结构拆解与关键配置代码部分我分了五个目录Core、Drivers、Middlewares、App、Utils。Core里放main.c和中断服务函数Drivers里放 STM32 HAL 库和自定义外设驱动Middlewares放 OTA 和环形缓冲区App放业务逻辑Utils放延时、日志、CRC 校验这些工具。为什么要这么分因为很多人写 STM32 项目所有代码堆在main.c里超过两千行之后自己都找不到变量定义。分层之后每个文件不超过三百行改起来心里有数。关键配置有几个地方容易出错。第一时钟树。STM32F103C8T6 外部晶振是 8MHz经过 PLL 倍频到 72MHz。我在SystemClock_Config里把 AHB 分频设为 1APB1 设为 2APB2 设为 1。这样 APB1 是 36MHzAPB2 是 72MHz。DHT11 和超声波都用微秒级延时如果 APB1 时钟不对HAL_Delay会偏。第二中断优先级。串口接收中断设为抢占优先级 1定时器中断设为 2SysTick 设为 15。这样串口数据不会因为定时器而丢失。第三GPIO 模式。DHT11 的数据线要配置为开漏输出加外部上拉或者推挽输出加内部上拉我实测开漏加外部 4.7k 上拉最稳因为 DHT11 是单总线协议需要释放总线时靠上拉电阻拉高。// DHT11 引脚配置示例 GPIO_InitTypeDef GPIO_InitStruct {0}; GPIO_InitStruct.Pin DHT11_DATA_PIN; GPIO_InitStruct.Mode GPIO_MODE_OUTPUT_OD; // 开漏输出 GPIO_InitStruct.Pull GPIO_PULLUP; // 内部上拉 GPIO_InitStruct.Speed GPIO_SPEED_FREQ_HIGH; HAL_GPIO_Init(DHT11_DATA_PORT, GPIO_InitStruct);超声波模块 HC-SR04 的 Trig 引脚用推挽输出Echo 引脚用浮空输入或上拉输入。我选上拉输入因为 Echo 输出高电平时是 5VSTM32 的 IO 是 3.3V 容忍但为了安全还是串一个 1k 电阻分压。这个细节很多教程不讲但实际接 5V 模块时容易烧 IO。2.2 原理图绘制要点与网络标号规范原理图我用嘉立创 EDA 画的因为免费、元件库全、可以直接导出 BOM 和 PCB。画原理图有几个硬性要求。第一电源网络必须标注清楚。3.3V 和 5V 用不同颜色GND 用统一符号。第二网络标号命名规则。所有连接到 STM32 引脚的信号命名格式是功能_引脚比如DHT11_DATA_PA5、TRIG_PB0、ECHO_PB1。这样在 PCB 布线时一眼就能看出这个网络是干什么的。第三去耦电容不能省。每个电源引脚旁边放一个 100nF 电容整体再放一个 10uF 钽电容。我见过太多人画原理图时省去耦电容结果板子跑起来偶尔复位查半天查不出来。原理图里还有一个关键点晶振电路。8MHz 晶振两端各接一个 22pF 电容到地再并一个 1M 电阻。这个 1M 电阻是反馈电阻有些教程不画但实际打板时如果不加晶振可能不起振。我实测过不加反馈电阻时大概有 10% 的板子起振慢或者不起振。加上之后一百块板子全部一次起振。提示嘉立创 EDA 里画原理图时建议开启“栅格对齐”栅格设为 10mil。这样连线不会歪导出网表时不会出现悬空节点。2.3 仿真方案选型与配置差异仿真我给了两套Proteus 和 Wokwi。为什么给两套因为 Proteus 适合模拟完整电路包括模拟器件但 STM32 模型有时候不准Wokwi 是网页版适合快速验证逻辑但不支持模拟信号。我的建议是逻辑验证用 Wokwi硬件时序验证用 Proteus。Proteus 里需要加载 STM32F103C8T6 的模型然后按照原理图连接 DHT11、HC-SR04、串口终端。DHT11 在 Proteus 里有现成模型但它的时序和真实器件有差异所以仿真通过不代表实物一定通过。HC-SR04 需要自己搭一个信号发生器来模拟 Echo 返回或者用 Proteus 的激励源。我一般用激励源产生一个 200us 的高电平脉冲代表距离 3.4cm 左右。Wokwi 里直接用wokwi-dht11和wokwi-hc-sr04元件连线用代码里的引脚定义。Wokwi 的好处是可以在浏览器里直接跑不用装软件分享链接就能让别人看到效果。但 Wokwi 的 STM32 仿真速度比真实芯片慢定时器精度也有偏差所以只适合验证逻辑流程不适合验证微秒级延时。仿真平台优点缺点适用场景Proteus支持模拟器件可看波形STM32 模型慢DHT11 时序不准硬件时序验证Wokwi网页版免安装分享方便不支持模拟信号定时器有偏差逻辑流程验证3. 实操过程与核心环节实现3.1 从零搭建工程环境准备与代码导入第一步装 Keil MDK5 和 STM32F1 的芯片包。芯片包去官网下载安装时注意路径不要有中文。我试过把 Keil 装在D:\嵌入式\Keil下面结果编译时报错找不到头文件改成D:\Embedded\Keil就好了。这个坑我踩过两次现在所有开发工具的安装路径一律用纯英文。第二步导入工程。工程文件是.uvprojx双击打开后在Options for Target里检查三个地方Target页的晶振频率设为 8MHzOutput页勾选Create HEX FileDebug页选ST-Link Debugger。如果你用的是 DAP 下载器就选CMSIS-DAP Debugger。第三步编译。如果报错cannot open source input file stm32f1xx_hal.h说明 HAL 库路径没加对。在C/C页的Include Paths里把Drivers/STM32F1xx_HAL_Driver/Inc和Drivers/CMSIS/Device/ST/STM32F1xx/Include加进去。# 如果你用命令行编译可以用 Makefile make clean make all # 输出在 build/ 目录下第四步烧录。用 ST-Link Utility 或者 STM32CubeProgrammer 都行。我习惯用 STM32CubeProgrammer因为它支持命令行可以写脚本批量烧录。烧录时注意 BOOT0 跳线要接 GND否则芯片从系统存储器启动不跑你的代码。3.2 DHT11 温湿度采集的完整实现DHT11 是单总线协议时序要求比较严。完整流程是主机拉低数据线至少 18ms然后释放等待 DHT11 响应。DHT11 会拉低 80us再拉高 80us然后开始传 40 位数据。每一位数据以 50us 低电平开始高电平持续时间决定是 0 还是 126-28us 是 070us 是 1。代码实现上我用了一个微秒级延时函数基于 SysTick 或者定时器。HAL 库的HAL_Delay是毫秒级不够用。我一般用 TIM4 做一个 1us 的计数器或者用__NOP()循环做粗略延时。实测下来用 TIM4 更稳因为__NOP()循环受编译器优化影响。// 微秒延时函数基于 TIM4 void delay_us(uint16_t us) { __HAL_TIM_SET_COUNTER(htim4, 0); while (__HAL_TIM_GET_COUNTER(htim4) us); }读取数据的函数里关键是要在正确的时间点采样。我试过用中断方式读 DHT11结果因为中断响应延迟数据老是错。后来改成阻塞式读取关掉全局中断读完再开就稳了。但关中断时间不能太长DHT11 一次完整读取大概 4ms关 4ms 中断对大多数应用没问题但如果你有串口接收可能会丢数据。所以我的建议是DHT11 读取放在主循环里不要放在中断里读取时关中断读完立刻开。注意DHT11 上电后需要 1 秒稳定时间不要一上电就读。我见过有人上电立刻读结果第一次总是失败以为是代码问题其实是传感器没稳定。3.3 超声波测距与串口通信的配合HC-SR04 的测距流程Trig 拉高至少 10us然后拉低模块自动发 8 个 40kHz 脉冲Echo 变高高电平持续时间就是距离的两倍声速时间。距离计算公式是距离 高电平时间 * 340 / 2 / 10000单位是厘米。340 是声速单位 m/s除以 2 是因为声音来回。我用 TIM2 的输入捕获功能测 Echo 高电平时间。配置 TIM2 为上升沿捕获捕获到上升沿时记录计数器值然后改成下降沿捕获捕获到下降沿时再记录两个值相减就是高电平时间。这里有个细节计数器溢出。如果距离超过 4 米高电平时间超过 23msTIM2 的 16 位计数器在 72MHz 下大概 0.9ms 就溢出了。所以要么用预分频器把计数频率降到 1MHz要么在溢出中断里累加。我选预分频到 1MHz这样计数器 65ms 才溢出足够测 10 米。串口通信我用 USART1波特率 1152008 数据位1 停止位无校验。发送数据时用printf重定向接收数据用中断。接收中断里把数据存到环形缓冲区主循环里解析。为什么要环形缓冲区因为串口数据来得快主循环处理慢没有缓冲区就会丢数据。环形缓冲区的大小我设 256 字节够存一帧 OTA 数据包。// 串口重定向 int fputc(int ch, FILE *f) { HAL_UART_Transmit(huart1, (uint8_t *)ch, 1, 0xFFFF); return ch; }3.4 OTA 升级框架的简化实现OTA 这部分我做了简化版没有用复杂的差分升级就是整包升级。流程是上位机通过串口发送固件包STM32 收到后先存到外部 Flash 或者内部 Flash 的备份区然后校验 CRC校验通过后跳转到 Bootloader 擦写主程序区。Bootloader 和 App 分开编译Bootloader 放在 0x08000000App 放在 0x08004000。关键点是中断向量表偏移。App 里要设置SCB-VTOR 0x08004000否则中断会跳到 Bootloader 的向量表。这个坑我踩过App 跑起来后串口中断不响应查了一天才发现是向量表没偏移。// App 里设置向量表偏移 SCB-VTOR 0x08004000;CRC 校验我用的是硬件 CRCSTM32F103 有 CRC 外设配置好之后直接喂数据就行。比软件 CRC 快很多而且不占 CPU。4. 常见问题与排查技巧实录4.1 代码编译与下载问题速查问题现象可能原因解决方法编译报错找不到头文件Include 路径没加在 Keil 的 C/C 页添加 HAL 库和 CMSIS 路径下载时提示“No target connected”下载器驱动没装或接线错装 ST-Link 驱动检查 SWDIO、SWCLK、GND、3.3V程序下载后不运行BOOT0 跳线不对BOOT0 接 GND按复位键串口无输出波特率不对或 TX/RX 接反检查波特率 115200TX 接 RXRX 接 TXDHT11 读数一直为 0上拉电阻没接或延时不准加 4.7k 上拉检查微秒延时4.2 仿真与实物差异的排查思路仿真通过但实物不通过这是最让人头疼的。我的排查顺序是先查电源再查时钟最后查时序。电源用万用表量3.3V 和 5V 都要量纹波大的话加电容。时钟用示波器看晶振引脚有没有 8MHz 正弦波。时序用逻辑分析仪抓 DHT11 和超声波的波形对比数据手册。我遇到过仿真里 DHT11 正常实物读出来湿度总是 0。后来用逻辑分析仪抓波形发现 DHT11 响应后数据线释放时被拉低太久导致第一位数据被误判。原因是我的上拉电阻是 10k太大换成 4.7k 就好了。这个细节仿真里看不出来因为 Proteus 的 DHT11 模型内部上拉很强。提示逻辑分析仪是调嵌入式的神器几十块钱的 24MHz 采样率就够用。抓 DHT11、超声波、串口波形一目了然比盲猜快十倍。4.3 开源项目管理的经验教训开源项目最怕的是“代码和文档不一致”。我早期开源的一个项目代码里引脚是 PA5文档里写的是 PA6结果十几个人下载后跑不起来评论区全是骂声。后来我定了个规矩文档里的所有引脚、参数、命令必须从代码里复制不能手打。原理图的网络标号也一样从代码的宏定义里复制过去。另一个教训是版本管理。我用 Git 管理代码每个版本打 TagTag 名字格式是v1.0.0-20240101。原理图和仿真文件也放在仓库里用 Git LFS 管理大文件。这样别人下载的时候代码、原理图、仿真文件是同一个版本不会出现代码是 v1.0 原理图是 v1.1 的情况。还有一点Issue 模板。我在仓库里放了 Issue 模板要求提问的人填清楚芯片型号、下载器型号、Keil 版本、报错截图、已经尝试过的操作。这样我回复的时候不用来回问效率高很多。我见过很多开源项目Issue 里就一句“跑不起来”作者根本没法帮。4.4 独家避坑技巧汇总第一个技巧Keil 和 C51 共存。很多人电脑上同时装了 Keil MDK 和 Keil C51结果装 STM32 芯片包时提示冲突。解决办法是装在不同目录然后用TOOLS.INI分别配置。具体操作是MDK 装在C:\Keil_v5C51 装在C:\Keil_C51然后修改环境变量KEIL_PATH指向当前要用的版本。这个技巧网上教程不多但实际很实用。第二个技巧ST-Link 无法识别 USB 设备。有时候 ST-Link 插上电脑设备管理器里显示未知设备。原因是 ST-Link 的固件版本太老或者 USB 驱动没装好。解决办法是去官网下载 ST-Link 固件升级工具升级固件然后重新插拔。如果还不行换一根 USB 线有些线只有充电功能没有数据功能。第三个技巧Wokwi 仿真 STM32 时串口无输出。Wokwi 的串口终端需要手动添加在diagram.json里加一个wokwi-serial-monitor然后把 STM32 的 TX 引脚连到串口终端的 RX。很多人忘了加串口终端以为代码有问题。第四个技巧Proteus 仿真 STM32 时程序跑飞。Proteus 的 STM32 模型对时钟配置很敏感如果SystemClock_Config里用了 HSE但 Proteus 里没接晶振程序就会卡在HAL_RCC_OscConfig里。解决办法是在 Proteus 里接上 8MHz 晶振或者把代码改成用 HSI。我一般建议仿真时用 HSI实物用 HSE这样仿真和实物都能跑。第五个技巧DHT11 读取间隔。DHT11 的数据手册说采样周期不低于 1 秒但实际测试下来低于 2 秒读取数据会漂。我现在的做法是 2 秒读一次读之前先延时 1 秒这样数据很稳。如果你要做快速采集DHT11 不合适换 SHT30 或者 DHT22。5. 项目扩展与个人体会这套项目后续还可以这样扩展加一个 OLED 屏幕显示温湿度和距离用 I2C 接口代码里加一个OLED驱动就行。或者加一个 ESP8266 模块把数据传到手机 App这个需要写 AT 指令解析。再或者把 OTA 升级改成差分升级用 BSDiff 算法这样固件包小很多适合窄带传输。我个人在实际操作中的体会是开源项目最难的不是写代码而是让别人能复现。你觉得自己写得很清楚别人拿到就是一头雾水。所以我现在开源任何东西都会找一个完全没参与过的人让他按照文档从头做一遍他卡在哪里我就改哪里。这个“小白测试”环节比我自己检查十遍都管用。最后再分享一个小技巧原理图导出 PDF 时把网络标号字体调大颜色调深。很多人导出的 PDF 网络标号看不清别人想对照代码查引脚都费劲。嘉立创 EDA 里可以设置导出选项把字体设为 12pt颜色设为黑色这样打印出来也清楚。这个细节很小但能极大提升开源项目的可用性。