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 分频设为 1，APB1 设为 2，APB2 设为 1。这样 APB1 是 36MHz，APB2 是 72MHz。DHT11 和超声波都用微秒级延时，如果 APB1 时钟不对，HAL_Delay会偏。第二，中断优先级。串口接收中断设为抢占优先级 1，定时器中断设为 2，SysTick 设为 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 输出高电平时是 5V，STM32 的 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页的晶振频率设为 8MHz，Output页勾选Create HEX File，Debug页选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 还是 1：26-28us 是 0，70us 是 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 米，高电平时间超过 23ms，TIM2 的 16 位计数器在 72MHz 下大概 0.9ms 就溢出了。所以要么用预分频器把计数频率降到 1MHz，要么在溢出中断里累加。我选预分频到 1MHz，这样计数器 65ms 才溢出，足够测 10 米。
串口通信我用 USART1，波特率 115200，8 数据位，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 放在 0x08000000，App 放在 0x08004000。
关键点是中断向量表偏移。App 里要设置SCB->VTOR = 0x08004000，否则中断会跳到 Bootloader 的向量表。这个坑我踩过，App 跑起来后串口中断不响应，查了一天才发现是向量表没偏移。
// App 里设置向量表偏移 SCB->VTOR = 0x08004000;CRC 校验我用的是硬件 CRC，STM32F103 有 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 接反 | 检查波特率 115200，TX 接 RX，RX 接 TX |
| DHT11 读数一直为 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 管理代码，每个版本打 Tag，Tag 名字格式是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_v5，C51 装在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，颜色设为黑色，这样打印出来也清楚。这个细节很小，但能极大提升开源项目的可用性。
