1. 一个STM32开源项目该有的样子
搞STM32开发的人多少都有过这种经历：从GitHub或者各种论坛扒下来一个项目，压缩包解压一看，代码是能编译，但引脚对不上自己的板子，原理图是截图糊得看不清，仿真文件压根没有。想改吧，不知道从哪下手；想复现吧，缺东少西。这种“半开源”的项目，说实话比不开源还折磨人。
我这次要聊的，是一个我自己从头到尾整理并开源的STM32项目。它不是什么高精尖的工业级产品，而是一个功能完整、资料齐全、可以直接复现的嵌入式小系统。核心交付物就三样：完整的工程代码、可编辑的原理图、能跑起来的仿真文件。这三样东西缺一不可，因为它们分别对应了嵌入式项目落地的三个关键环节——软件逻辑、硬件设计、前期验证。
这个项目适合谁？如果你是刚学完STM32基础外设、想找一个完整项目练手的学生，它很适合你；如果你是需要做毕业设计但不知道怎么把代码、原理图、仿真串起来的同学，它也能给你一套可参考的模板；甚至如果你是一个已经工作的嵌入式工程师，想看看别人是怎么组织一个开源项目的资料结构的，也可以拿来翻翻。
我先把话说在前头：这篇文章不会只给你甩一个网盘链接就完事。我要做的是把这个项目从设计思路到代码结构、从原理图绘制到仿真配置，一层一层拆开讲清楚。你看完之后，不仅能复现这个项目，更重要的是能掌握一套自己做开源项目的方法论。
2. 项目整体设计与方案选型
2.1 为什么选STM32F103C8T6作为主控
STM32的型号多如牛毛，从F0到H7，从C0到G4，选型的时候很容易挑花眼。这个项目我最终选了STM32F103C8T6，原因很实在：
第一，资料多、社区活跃。这颗芯片可以说是STM32入门的“国民芯片”，网上能找到的教程、例程、踩坑记录是最丰富的。对于开源项目来说，这一点极其重要——用户遇到问题能搜到答案，项目的维护成本就低。
第二，成本低、易获取。最小系统板十几块钱就能买到，自己打板的话芯片单价也就几块钱。开源项目如果门槛太高，参与的人就少。
第三，外设够用。这个项目用到了GPIO、USART、TIM、ADC、I2C这几个常用外设，F103C8T6完全覆盖，不需要上更高端的型号。
第四，仿真支持好。这一点经常被忽略。不是所有STM32型号都能在主流仿真软件里找到对应的模型，而F103系列在Proteus等仿真平台上的支持是最成熟的。
注意：如果你手头只有STM32F401或者别的型号，代码移植的工作量其实不大，主要是时钟配置和部分寄存器差异。但仿真部分可能需要换模型，这个后面会细说。
2.2 代码、原理图、仿真三件套的协同关系
很多人做项目是“先画板子再写代码”，或者“先写代码再补原理图”，最后仿真干脆不做。这种流程在个人练手时问题不大，但一旦要开源给别人用，就会暴露出一堆问题：代码里的引脚定义和原理图对不上、仿真模型的外围电路和实际板子不一致、别人拿到你的资料根本不知道怎么验证。
我的做法是三者同步设计，具体流程是这样的：
- 先确定功能需求和引脚分配。拿出一张纸（或者Excel），把所有外设列出来，分配好引脚，标注每个引脚的功能和电气特性。
- 根据引脚分配画原理图。原理图不是随便连的，每个引脚的外围电路都要有依据——上拉电阻要不要加、去耦电容放几个、晶振负载电容选多大，这些都要在原理图阶段确定。
- 代码按照引脚分配来写。所有引脚定义用宏定义集中管理，方便修改。
- 仿真验证核心逻辑。在打板之前，用仿真软件把关键功能跑一遍，确认逻辑没问题。
这套流程的好处是：任何一环出问题，都能快速定位到源头。比如仿真跑不通，先检查原理图连接对不对；原理图没问题，再看代码配置。而不是像无头苍蝇一样到处改。
2.3 开源项目资料结构的组织方式
一个合格的开源项目，目录结构应该是清晰的。我见过太多项目把所有文件往根目录一扔，找起来费劲。这个项目的目录结构是这样的：
STM32-Project/ ├── Docs/ # 文档目录 │ ├── 设计说明.md │ ├── 引脚分配表.md │ └── 常见问题.md ├── Hardware/ # 硬件资料 │ ├── Schematic/ # 原理图源文件 │ ├── PCB/ # PCB源文件 │ └── Datasheet/ # 关键器件手册 ├── Firmware/ # 固件代码 │ ├── Core/ │ ├── Drivers/ │ ├── Middlewares/ │ └── Projects/ ├── Simulation/ # 仿真文件 │ ├── Proteus/ │ └── 仿真说明.md └── README.md这个结构参考了ST官方CubeMX生成工程的思路，但做了简化。核心原则是：别人拿到你的项目，不看文档也能猜出每个文件夹是干什么的。
3. 核心细节解析与实操要点
3.1 代码架构：从裸机到模块化
很多STM32教程的代码是“一个main.c走天下”，所有逻辑堆在一起。这种写法用来点个灯、读个传感器没问题，但项目稍微复杂一点就维护不动了。这个项目采用的是模块化分层架构，具体分为三层：
硬件抽象层（HAL Layer）：直接操作寄存器和HAL库函数，封装成统一的接口。比如LED控制、按键读取、串口收发，都在这一层实现。上层不需要知道用的是哪个GPIO口，只需要调用LED_On()、LED_Off()这样的函数。
功能模块层（Module Layer）：实现具体的功能逻辑。比如温湿度采集模块、数据显示模块、通信协议解析模块。每个模块是一个独立的.c/.h文件对，对外只暴露必要的接口。
应用层（App Layer）：主循环和任务调度。这一层负责把各个功能模块串起来，实现完整的业务逻辑。
这样分层的好处是可移植性和可测试性。比如你要把温湿度传感器从DHT11换成SHT30，只需要改功能模块层的实现，应用层代码完全不用动。
代码里所有引脚定义都集中在board_config.h文件里，用宏定义管理：
// board_config.h #define LED1_PIN GPIO_PIN_13 #define LED1_PORT GPIOC #define KEY1_PIN GPIO_PIN_0 #define KEY1_PORT GPIOA #define USART1_TX_PIN GPIO_PIN_9 #define USART1_RX_PIN GPIO_PIN_10这样别人拿到代码，如果引脚不一样，只需要改这一个文件就行，不用满工程搜索。
3.2 原理图设计：那些容易踩坑的地方
原理图这部分，我想重点讲几个新手最容易出错的地方。这些坑我都踩过，有些甚至导致板子打回来直接不能用。
第一个坑：去耦电容的放置。STM32的每个电源引脚旁边都应该放一个100nF的去耦电容，而且这个电容要尽量靠近引脚。我见过有人把所有去耦电容集中放在板子一角，结果芯片工作不稳定，偶尔复位。原理图上看不出问题，但PCB布局的时候就暴露了。所以画原理图的时候就要有意识地把去耦电容和对应的电源引脚画在一起。
第二个坑：晶振负载电容的计算。STM32外部晶振的负载电容不是随便选一个20pF就完事。计算公式是：
CL = (C1 × C2) / (C1 + C2) + Cstray
其中CL是晶振手册上标注的负载电容，Cstray是PCB走线的寄生电容，一般取3~5pF。假设晶振的CL是12pF，Cstray取4pF，那么C1和C2应该选16pF左右。如果选错了，晶振可能起振困难或者频率偏移。
第三个坑：BOOT引脚的处理。STM32的BOOT0和BOOT1引脚决定了启动模式。如果你用串口下载程序，BOOT0需要拉高；正常运行的时候BOOT0要拉低。很多人在原理图上把BOOT0直接接地，结果想用串口下载的时候发现进不去。正确的做法是加一个跳线帽或者拨码开关，方便切换。
第四个坑：复位电路。STM32的NRST引脚内部有上拉电阻，但为了可靠复位，建议外部还是加一个10kΩ上拉电阻和一个100nF电容到地。有些开发板省掉了这个电容，结果按键复位的时候偶尔不灵。
原理图我用的是嘉立创EDA绘制的，原因很简单：免费、元件库全、可以直接导出BOM和PCB。当然你也可以用Altium Designer或者KiCad，原理是相通的。
3.3 仿真配置：Proteus还是其他
仿真工具的选择上，我主要用Proteus。原因有三个：一是它对STM32F103系列的支持比较成熟；二是可以直接加载.hex文件运行，和实际烧录的效果接近；三是元件库里有常用的外设模型，比如LCD1602、DHT11、按键、LED等。
不过Proteus也不是万能的。它的时序仿真精度有限，对于一些对时序要求严格的应用（比如高速SPI通信、精确的PWM输出），仿真结果只能作为参考，不能完全替代实际测试。另外，Proteus的STM32模型不支持某些高级外设，比如USB、CAN、以太网等。
如果你要做更精确的仿真，可以考虑用STM32CubeIDE自带的仿真功能，或者用Keil MDK的软件仿真。Keil的软件仿真可以模拟寄存器级别的行为，适合调试底层驱动代码。但它没有外围电路的模型，只能验证代码逻辑，不能验证硬件连接。
我的建议是：Proteus用来验证整体功能逻辑，Keil软件仿真用来调试底层驱动，两者结合使用。实际打板之前，再用示波器和逻辑分析仪验证关键信号。
4. 实操过程与核心环节实现
4.1 从零搭建工程：CubeMX配置要点
如果你是从零开始，第一步是用STM32CubeMX生成工程框架。这个工具虽然有人吐槽它生成的代码臃肿，但不可否认它大大降低了初始化配置的门槛。
具体配置步骤如下：
第一步：选择芯片型号。在CubeMX里搜索STM32F103C8T6，选中后开始配置。
第二步：配置时钟源。在RCC配置里，把HSE（高速外部时钟）设为Crystal/Ceramic Resonator。这样CubeMX会自动配置外部晶振相关的寄存器。
第三步：配置时钟树。F103C8T6的最高主频是72MHz。输入晶振频率一般填8MHz，然后通过PLL倍频到72MHz。具体路径是：HSE 8MHz → PLL ×9 → 72MHz → AHB Prescaler /1 → APB1 Prescaler /2 (36MHz) → APB2 Prescaler /1 (72MHz)。
第四步：配置外设。根据项目需求，依次配置GPIO、USART、TIM、ADC、I2C等。每个外设的配置界面里都有详细的参数设置，比如USART的波特率、数据位、停止位、校验位等。
第五步：配置中断优先级。如果用到中断，需要在NVIC配置里设置优先级。STM32F103的中断优先级分为抢占优先级和响应优先级，数值越小优先级越高。一般来说，对实时性要求高的中断（比如串口接收）设置更高的抢占优先级。
第六步：生成代码。在Project Manager里设置工程名称、路径、工具链（MDK-ARM或STM32CubeIDE），然后点击Generate Code。
实操心得：CubeMX生成的代码里，用户代码要写在
/* USER CODE BEGIN */和/* USER CODE END */之间，这样重新生成代码的时候不会被覆盖。这个习惯一定要养成，否则改一次配置就丢一次代码。
4.2 关键功能模块的代码实现
这个项目的核心功能包括：LED状态指示、按键输入检测、串口数据收发、定时器PWM输出、ADC电压采集、I2C温湿度读取。我挑几个有代表性的讲一下实现细节。
按键消抖是嵌入式开发里的经典问题。机械按键在按下和松开的瞬间会产生抖动，如果不处理，一次按下可能被识别成多次。常见的消抖方法有两种：硬件消抖（加RC电路）和软件消抖（延时采样）。这个项目用的是软件消抖，在定时器中断里每10ms采样一次按键状态，连续3次采样结果一致才认为是有效按键。
// 按键扫描函数，在10ms定时器中断里调用 void Key_Scan(void) { static uint8_t key_cnt = 0; uint8_t key_now = HAL_GPIO_ReadPin(KEY1_PORT, KEY1_PIN); if (key_now == GPIO_PIN_RESET) { if (key_cnt < 3) key_cnt++; if (key_cnt == 3) { key_pressed = 1; // 确认按下 } } else { key_cnt = 0; key_pressed = 0; } }串口数据收发用的是中断方式，而不是轮询。轮询方式会阻塞主循环，影响其他任务的执行。中断方式下，每收到一个字节就触发一次中断，把数据存到缓冲区里，主循环再慢慢处理。
// 串口接收中断回调函数 void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { if (huart->Instance == USART1) { // 把接收到的数据存入环形缓冲区 RingBuffer_Write(&rx_buffer, rx_byte); // 重新开启接收中断 HAL_UART_Receive_IT(&huart1, &rx_byte, 1); } }PWM输出用的是定时器TIM3的通道1和通道2。PWM频率计算公式是：
PWM频率 = 定时器时钟 / ((Prescaler + 1) × (Period + 1))
假设定时器时钟是72MHz，Prescaler设为71，Period设为999，那么PWM频率 = 72000000 / (72 × 1000) = 1000Hz。占空比通过修改比较寄存器CCR的值来调节，CCR从0到Period对应占空比从0%到100%。
4.3 原理图绘制实操：以最小系统为例
画原理图这件事，说难不难，说简单也不简单。关键是养成规范的习惯。我以最小系统部分为例，讲一下绘制流程。
第一步：放置主控芯片。在嘉立创EDA的元件库里搜索STM32F103C8T6，放置到画布上。注意检查引脚编号和封装是否对应，有些库里的符号引脚排列和实际芯片不一致。
第二步：连接电源和地。VDD引脚接3.3V，VSS接GND。每个VDD引脚旁边放一个100nF去耦电容。VDDA和VSSA是模拟电源，也要接3.3V和GND，并且额外加一个1μF的电容滤波。
第三步：连接晶振电路。8MHz晶振接在PD0和PD1（OSC_IN和OSC_OUT）之间，两端各接一个16pF电容到地。注意晶振的外壳要接地，减少干扰。
第四步：连接复位电路。NRST引脚接一个10kΩ上拉电阻到3.3V，同时接一个100nF电容到地，再并联一个复位按键。
第五步：连接BOOT引脚。BOOT0通过一个10kΩ电阻接地，同时引出一个跳线帽，需要串口下载时可以短接到3.3V。BOOT1直接接地。
第六步：引出调试接口。SWD接口需要连接SWDIO（PA13）和SWCLK（PA14），再加上3.3V和GND。建议用标准的4针排针，间距2.54mm。
画完之后，一定要用ERC（电气规则检查）功能检查一遍，看看有没有未连接的引脚、电源冲突等问题。
4.4 仿真文件配置与运行
Proteus仿真的配置流程如下：
第一步：新建工程。打开Proteus，新建一个原理图工程，选择不创建PCB布局。
第二步：放置元件。从元件库中搜索并放置以下元件：STM32F103C8T6、LED、电阻、按键、LCD1602、DHT11、虚拟终端等。
第三步：连接电路。按照原理图的连接方式，在Proteus里把元件连起来。注意Proteus里的STM32模型引脚编号可能和实际芯片不同，要以模型为准。
第四步：加载程序。双击STM32模型，在Program File一栏选择编译生成的.hex文件。Crystal Frequency填8MHz（和实际晶振一致）。
第五步：运行仿真。点击运行按钮，观察LED是否闪烁、LCD是否显示、虚拟终端是否有输出。
注意：Proteus仿真STM32时，时钟频率设置必须和代码里的配置一致。如果代码里用的是8MHz外部晶振，Proteus里也要设成8MHz。否则仿真速度会不对，甚至跑不起来。
仿真过程中如果发现功能不对，排查顺序是：先看电源和地有没有接、再看复位电路、然后看晶振有没有起振、最后看代码逻辑。这个顺序能帮你快速定位大部分问题。
5. 常见问题与排查技巧实录
5.1 代码编译与下载问题
问题一：Keil编译报错“cannot open source input file ‘xxx.h’”。这通常是头文件路径没配置好。解决方法是在Keil的Options for Target → C/C++ → Include Paths里添加对应的头文件目录。如果是CubeMX生成的工程，检查一下Drivers目录下的CMSIS和HAL_Driver路径有没有加进去。
问题二：ST-Link识别不到芯片。先检查硬件连接：SWDIO、SWCLK、GND、3.3V四根线是否接好。然后检查Keil里的Debug设置，选择ST-Link Debugger，在Settings里看看能不能识别到芯片ID。如果识别不到，可能是芯片被锁了，需要用ST-Link Utility执行全片擦除。
问题三：程序下载成功但不运行。检查BOOT0引脚的电平，正常运行时要拉低。如果BOOT0拉高了，芯片会进入系统存储器启动模式，不执行用户程序。另外检查复位电路是否正常，NRST引脚有没有被意外拉低。
问题四：串口乱码。首先检查波特率是否匹配，代码里设的115200，串口助手也要设115200。然后检查晶振频率是否正确，如果外部晶振没起振，芯片会用内部RC振荡器，频率偏差大导致波特率不准。最后检查串口线有没有接反，TX接RX，RX接TX。
5.2 原理图与PCB常见错误
| 问题现象 | 可能原因 | 排查方法 |
|---|---|---|
| 芯片发热严重 | 电源短路或接反 | 断电后用万用表测VDD和GND之间电阻 |
| 晶振不起振 | 负载电容不匹配 | 用示波器测晶振引脚波形 |
| 复位不稳定 | 复位电容太小或太大 | 检查NRST引脚波形，调整电容值 |
| 串口通信失败 | TX/RX接反 | 交换TX和RX试试 |
| ADC采样不准 | 参考电压不稳 | 检查VDDA滤波电容，增加软件滤波 |
| I2C通信无应答 | 上拉电阻缺失 | SDA和SCL各加4.7kΩ上拉电阻 |
5.3 仿真过程中的典型问题
问题一：Proteus仿真速度极慢。这通常是因为仿真步长设置太小，或者电路中有太多模拟元件。解决方法是在Simulation Options里把步长调大一些，或者把不必要的外围电路简化。
问题二：STM32模型不运行。检查.hex文件路径是否正确、时钟频率是否匹配、电源引脚是否连接。有时候Proteus的STM32模型需要手动设置VDD和VSS引脚，默认可能没连。
问题三：LCD1602不显示。检查对比度调节引脚（V0）的电压，一般接一个10kΩ电位器调到中间位置。检查数据线和控制线的连接，RS、RW、E三个控制信号不能接错。
问题四：DHT11读取失败。Proteus里的DHT11模型和实际器件时序可能有差异，建议先用实际硬件验证代码，再放到仿真里跑。如果仿真里读不到数据，可以尝试降低读取频率或者调整延时参数。
5.4 开源项目管理的经验之谈
做开源项目，代码写得好只是第一步，让别人能用起来才是关键。我踩过的几个坑：
坑一：没有写README。别人点进你的仓库，第一眼看到的就是README。如果README里没有项目介绍、编译方法、使用说明，大部分人直接就关了。README至少要包含：项目简介、功能列表、硬件需求、编译步骤、目录结构说明。
坑二：代码里硬编码太多。比如引脚定义直接写在函数里，别人想改引脚得满工程搜索。正确的做法是把所有可配置的参数集中到一个配置文件里。
坑三：没有版本管理。今天改一点，明天改一点，最后自己都不知道哪个版本是稳定的。建议用Git做版本管理，每个稳定版本打一个Tag，写清楚更新内容。
坑四：忽略了开源协议。开源不等于没有版权，你需要选择一个合适的开源协议（比如MIT、Apache 2.0、GPL），在仓库里放一个LICENSE文件。MIT协议最宽松，适合希望别人自由使用的项目；GPL协议要求衍生作品也必须开源，适合希望保持开源的场景。
6. 项目扩展与进阶方向
这个项目的基础功能跑通之后，可以往几个方向扩展。
方向一：加入OTA升级功能。OTA（Over-The-Air）升级是嵌入式设备很实用的功能，可以通过串口、蓝牙或者WiFi远程更新固件。实现思路是在Flash里划分两个区域：Bootloader区和App区。Bootloader负责接收新固件并写入App区，然后跳转执行。STM32F103C8T6的Flash只有64KB，做OTA需要仔细规划空间。
方向二：接入RTOS。目前项目是裸机跑的主循环，功能多了之后实时性会变差。可以移植FreeRTOS或者RT-Thread，把不同功能拆成独立任务，用信号量和消息队列做任务间通信。RTOS的引入会让代码结构更清晰，但也增加了调试复杂度。
方向三：增加无线通信模块。比如接一个ESP8266做WiFi通信，或者接一个HC-05做蓝牙通信，把数据上传到手机或者云平台。这部分需要注意串口通信的协议设计，建议用JSON格式封装数据，方便解析。
方向四：完善仿真模型。目前Proteus仿真只覆盖了核心功能，可以进一步增加外围电路的仿真，比如电源电路、信号调理电路等。这样在打板之前就能发现更多潜在问题。
方向五：编写自动化测试脚本。用Python写一个上位机脚本，通过串口和STM32通信，自动发送测试指令并验证返回结果。这样每次修改代码后，跑一遍测试脚本就能确认功能是否正常，比手动测试效率高得多。
我个人在实际操作中的体会是，开源项目的价值不在于代码有多复杂，而在于资料有多完整、别人有多容易复现。一个功能简单但资料齐全的项目，比一个功能炫酷但文档缺失的项目有价值得多。所以如果你也想做开源项目，先把代码、原理图、仿真这三样东西整理好，再考虑加更多功能。
