平时逛开源社区，最烦的就是看到那种"只见代码不见人"的STM32项目：压缩包里一堆无注释的.c文件和散落的原理图PDF，下载下来根本不知道从哪开始看。所以我自己在做项目开源时，会格外把"别人拿到手能不能跑通、能不能看懂"当作最低标准。这阵子整理的一个基于STM32F103C8T6的环境监测小项目，就是奔着这个标准去的——DHT11采集温湿度、0.96寸OLED屏本地显示、USART串口上传数据，配套齐全的电路原理图、Keil5工程代码和Proteus仿真文件。如果你正在找能参考着做毕业设计，或者刚入门STM32想找一个结构完整的练手项目，这篇内容应该能帮你省不少功夫。
这篇博文不打算只贴个下载链接了事，我想把项目里那些"当初怎么想的、为什么这么连、实物和仿真差在哪里"的东西都摊开来讲。所以你会看到原理图里每个元器件存在的理由、代码里每一块模块的职责拆分、仿真环境里那些特别容易卡住新手的细节，以及我踩过的几个比较典型的坑。
1. 项目全貌与技术选型：为什么是F103C8T6 + DHT11 + OLED这条路
先把这个项目到底是什么、由哪几部分组成说清楚。整个系统可以拆成三个层面来看：感知层用的是DHT11数字温湿度传感器，单总线协议，一根IO口就能读数据，便宜且上手门槛极低；显示层用的是0.96寸I2C接口OLED屏，128x64分辨率，四根线接完就能显示汉字和数字；通信层用STM32自带的USART1把采集到的数据以字符串形式发出去，方便在PC端串口助手查看，也为以后接ESP8266之类的WiFi模块留好了口子。
项目主控选择STM32F103C8T6，也就是常说的"蓝丸"最小系统板的核心芯片，64KB Flash、20KB SRAM、内置72MHz主频的Cortex-M3内核。有人可能会问，跑这么简单的活儿有必要上F103吗？答案是没必要，但这个选择恰恰是故意的。我见过太多新手一上来就追最新的H7系列或者G4系列，结果光啃参考手册就啃了半个月。F103的资源虽然算不上丰富，但恰好覆盖了GPIO操作、I2C通信、USART收发、定时器中断这些嵌入式开发最核心的知识点，而且CubeMX里对它的支持极其成熟，社区资料密度是其他型号没法比的。
再明确一下引脚分配，方便后面看原理图和代码的时候对照：
| 功能模块 | 引脚 | 说明 |
|---|---|---|
| DHT11数据线 | PB0 | 单总线协议，需外接4.7k上拉电阻 |
| OLED_SCL | PB8 | I2C1时钟线，JY-CM4模块默认引脚 |
| OLED_SDA | PB9 | I2C1数据线 |
| USART1_TX | PA9 | 串口发送，接CH340G转USB |
| USART1_RX | PA10 | 串口接收，预留升级功能 |
| BOOT0 | 接地 | 从Flash启动，正常跑代码状态 |
| NRST | 外接按键 | 复位电路 |
这个项目适合两种人：一种是正在做课程设计或者毕业设计，需要一套完整可复现的"传感器 + 显示 + 通信"框架；另一种是想搞懂STM32程序该怎么组织结构的初学者，项目里的代码不是把所有逻辑堆在main函数里，而是拆成了多个模块，每块都有清晰的职责边界。
仓库内容按目录分开管理。Hardware目录放的是嘉立创EDA绘制的原理图和PCB源文件，以及导出的PDF版图纸；Firmware目录是完整的Keil5工程，用STM32CubeMX初始化，HAL库开发；Simulation目录是Proteus 8.9及以上版本可用的仿真工程，已经配好DHT11模型和OLED屏幕模型，打开加载HEX文件就能跑；Docs目录放项目说明文档、引脚连接表和使用指南。这种组织方式也是我参考了几个优质嵌入式开源项目后逐步形成的习惯，后面会展开说。
2. 原理图设计思路：每一颗电阻电容都不是摆设
硬件部分我前后改了三个版本才定稿。第一版是直接在面包板上飞的杜邦线，能跑但没法交付给别人；第二版画了PCB，但犯了一些新手很容易犯的错；第三版才真正把电源、复位、启动模式这些细节都考虑清楚。下面按电路模块逐个拆解。
2.1 最小系统电路的三板斧：晶振、复位、BOOT
STM32F103C8T6虽然内部有RC振荡器，但精度一般，温度漂移也明显，所以外部8MHz晶振是标配。晶振电路里那两颗22pF电容不是随手选的——它们和晶振的负载电容参数要匹配，8MHz晶振典型负载电容为10~20pF，22pF是工程上最通用的取值。如果换用其他频率的晶振，要重新算匹配电容，不能无脑照抄。
复位电路这边，我用的是10k电阻上拉加一个按键对地短接的结构，这也是教科书里最常见的配置。NRST引脚平时被电阻拉至高电平，按键按下时接地产生低脉冲，芯片复位。有人觉得这玩意儿可有可无，但实际上调试的时候，程序跑飞了或者进入异常状态，一个物理复位按键比断电重插快得多。
BOOT0和BOOT1这两个引脚很多人忽略。我这块板子直接把BOOT0通过10k电阻接地，保证上电从主Flash启动。唯独要提醒的是：如果你想用串口ISP下载程序，需要临时把BOOT0拉高再复位，所以最好预留一个跳线帽的位置，而不是焊死。我的成品板上留了一个三针跳线，调试完拔掉跳线帽就能正常跑Flash里的程序。
2.2 电源电路：3.3V稳压和去耦电容的讲究
整个系统的供电方案是USB的5V进来，经AMS1117-3.3稳压到3.3V给MCU和外设。AMS1117-3.3这芯片太常见了，最大输出电流1A，无负载时静态功耗很低，应付MCU加OLED加传感器这种级别绰绰有余。输入输出各并一颗10uF钽电容和0.1uF瓷片电容，这个组合是数据手册里推荐的典型电路，直接照搬。
去耦电容我花了些心思。STM32每个VDD引脚旁边都放了一颗100nF的瓷片电容，而且尽量靠近引脚放置，这是为了让高频噪声有一个低阻抗的回流路径。很多自制的板子跑起来不稳定、ADC采样值跳来跳去，八成就是这些小电容没放到位。PCB布线时我还特别注意了模拟地和数字地的处理——本设计没有独立模拟部分，所以整个板子铺的是完整地平面，没有做分割，避免因为地平面割裂导致回流路径突变。
DHT11的数据线上必须有4.7k上拉电阻，这一点和I2C上拉原理一致：单总线协议里，总线空闲状态是高电平，MCU和传感器都是通过拉低总线来发起通信的。如果没有这个上拉电阻，总线在空闲时电平不确定，时序极容易出错。我见过有人在面包板上不加上拉电阻也能读到数据，那是因为杜邦线之间寄生电容和走线阻抗在捣乱，实际打板后就会露出马脚，该加的电阻一个都不能省。
OLED屏的I2C接口同样需要上拉电阻吗？要看模块设计。市面上大多数0.96寸OLED模块板载了4.7k上拉电阻，可以直接接MCU；但如果你是从零自己画的屏驱动电路，那SCL和SDA上必须各加一颗4.7k到3.3V，否则I2C通信会时好时坏。
2.3 原理图绘制实操：从嘉立创EDA到生成PDF
这版原理图是用嘉立创EDA画的，免费、上手快、元件库齐全，对开源项目特别友好，别人下载源文件后不需要装破解版软件就能打开。画图时有几个习惯值得养。第一，每个网络标签必须起有意义的名字，比如DHT11_DATA、OLED_SCL、USART1_TX，而不是默认的NET_LABEL1，这样别人看图时一眼能懂信号流向。第二，电源和地符号用不同类型的符号区分，VCC用三角形箭头，GND用三条横线，规范符号比什么注释都直观。第三，元件位号要重排一遍，R1、R2、C1、C2按从左到右从上到下的顺序依次生成，后期贴BOM和焊接时对照方便很多。
导出PDF图纸给不看EDA文件的人参考，导出时颜色方案选黑白打印模式最佳，灰度图在显示器上容易糊成一团。PCB部分我用了双层板，顶层走信号，底层做地平面，元器件尽可能一面贴装。OLED模块和DHT11传感器都设计成插接件接口，方便实物调试时更换，也比焊死更友好。
关于原理图里那些与实物不一致的小细节：比如DHT11传感器座选的是四针排针座，而DHT11模块通常有三个引脚（VCC、DATA、GND），留一个NC空脚不接，这在原理图上提前标注清楚就行。OLED用的是四针接口，但市场上有GND、VCC、SCL、SDA四针和六针（多出RES和DC）两种模块，选四针版本最省事，软件上也不需要额外的复位和命令引脚控制。
3. 代码架构与核心模块：Keil5工程是怎么组织出来的
代码部分最大的心得是：别把所有东西都往main.c里塞。这个项目虽然功能简单，但工程文件按模块拆成了五个源文件，每个文件只干一件事。这样做的好处是，以后想加一个GPS模块或者蓝牙模块，不用动老代码，新建一个文件然后挂到初始化流程里就行。
工程的模块划分是这样的：
| 模块文件 | 职责范围 | 对外接口 |
|---|---|---|
| main.c | 初始化外设、主循环状态调度 | main函数 |
| dht11.c | DHT11时序驱动、数据解析 | DHT11_Read_TempAndHumidity |
| oled.c | OLED初始化、显示字符串和汉字 | OLED_ShowString、OLED_ShowCHinese |
| usart.c | 串口初始化、printf重定向 | 无（中断接收预留） |
| delay.c | 微秒和毫秒级延时 | Delay_us、Delay_ms |
3.1 CubeMX初始化配置的关键设定
工程是用STM32CubeMX 6.8生成的，选芯片型号时直接搜STM32F103C8Tx，配置界面会列出所有引脚。RCC选项里，HSE选择Crystal/Ceramic Resonator，这是让外部8MHz晶振生效的前提；SYS里的Debug选Serial Wire，否则板载调试器连不上SWD接口，这是F103小白最容易踩的坑——默认Debug是No Debug，你Programmer烧完一次第二次就识别不到芯片了。
时钟树配置那里，HSE输入8MHz后，PLL倍频到72MHz。我建议这一步跟着CubeMX自动计算的走，不要手动改预分频值来"超频"，芯片最高支持72MHz，超上去虽然有的能跑但属于不规范设计。USART1配置为异步模式，波特率115200，8位数据位，1位停止位，无校验，这是和PC串口助手的默认匹配值。I2C1配置为标准模式100kHz，因为DHT11不吃I2C，但OLED用100kHz完全够，不需要拉高速。GPIO里把PB0设为推挽输出，初始电平为高——因为DHT11单总线空闲时必须是高，这也是协议要求。
3.2 DHT11时序读取：一段必须"抠时序"的代码
DHT11的数据读取是项目里最考验基础的模块。协议上，MCU要先拉低总线至少18ms再释放，传感器收到起始信号后回一个80us低电平和80us高电平的响应，然后连续发送40位数据：8位湿度整数、8位湿度小数、8位温度整数、8位温度小数、8位校验和。每一位的"0"和"1"是靠高电平持续时间区分的——26~28us高电平为"0"，70us左右高电平为"1"。所以读时序的本质就是不停采样引脚电平，测量高电平宽度。
核心代码片段长这样，配合注释可以直接背下来：
uint8_t DHT11_Read_Byte(void) { uint8_t i, data = 0; for (i = 0; i < 8; i++) { while(DHT11_DATA_PIN == GPIO_PIN_RESET); // 等待低电平结束 Delay_us(40); // 高电平持续40us后采样 if(DHT11_DATA_PIN == GPIO_PIN_SET) data |= (1 << (7 - i)); // 高电平时间大于40us，判断为1 while(DHT11_DATA_PIN == GPIO_PIN_SET); // 等待高电平结束 } return data; }关键在第二行那个while。低电平是每一位数据的起始标志，所以读每一位之前必须等到低电平结束，否则采到的电平和上一次对不上。我写这段时犯过的错是：没有等待低电平结束就开始测高电平宽度，导致数据错位，读出的湿度有时候是255，查了半天才发现是时序起始位置不对。
完整读取函数还会做一步校验：把前四字节相加取低8位，和第五字节比较，相等才认为本次读取有效。如果校验失败，我选择直接丢弃本次数据返回错误状态码，而不是输出一堆"离谱"的数据。这个习惯很重要，你可以看到很多不严谨的例程根本不校验，数据明明已经错了还在OLED上显示"湿度98%"，纯属误导。
DHT11数据引脚的工作模式有个小技巧：在输出模式下发送完起始信号后，要立刻把引脚模式切换为输入，然后才能去采样。用HAL库的话是修改GPIO配置结构体的Mode成员再重新初始化，其实可以直接对寄存器操作，用GPIO_CRL寄存器切换模式更高效。我代码里封装了一个宏来处理这种切换，比反复调用HAL_GPIO_Init干净得多。
3.3 OLED显示驱动：I2C通信和汉字取模
OLED模块用的是SSD1306控制芯片的0.96寸屏，通过I2C接口和主控通信。HAL库里用HAL_I2C_Mem_Write这个函数写屏，第一个参数是I2C句柄，第二个是设备地址，第三个是寄存器地址（SSD1306的control byte），第四个是数据缓冲区。这类屏的好处是不需要理解SSD1306内部页地址寻址的细节，只要会往显存里填充，屏幕就会刷新。
驱动代码里我把显存做成一个128x8（即128列分成8页）的局部缓冲区，所有画点、画字符的操作先在缓冲区里完成，再通过I2C一次性刷到屏幕。这样做有几个好处：一是避免频繁I2C通信导致画面闪烁，二是方便实现局部刷新功能。比如秒数变化时只需要更新对应区域的数据，而不是整个屏幕重画。
中文字符显示需要取模，我用的是PCtoLCD2002软件，取模方式选"阴码、逐行式、顺向、C51格式"，这样生成的数据可以直接塞进const数组里，节省RAM。OLED_ShowCHinese函数的核心就是按16x16像素点阵逐行读数组，把位数据写进显存缓冲区。这里面需要注意：数组下标和屏幕坐标的换算关系是很有规律的，从左到右每16列切换一个汉字，行的话每16像素切换一个页区域，很多人显示中文出现"跑偏"和"乱码"就是因为坐标计算时忘了加页偏移。
另外提一句，OLED驱动的主控频率也可以适当调整，实测我把I2C时序从标准模式100kHz提高到快速模式400kHz后，画面刷新速度明显加快，整个系统在100kHz和400kHz下对DHT11采集没有任何干扰。如果你要改I2C速度，在CubeMX里重新配置I2C时钟频率重新生成代码就行。
3.4 USART串口打印：printf重定向的底层逻辑
串口模块除了正经的协议通信，干得最多的一件事就是把采集到的温湿度数据格式化之后发出去。为了让printf能直接用，我重写了fputc函数，这也是Keil环境下标准的做法：
int fputc(int ch, FILE *f) { HAL_UART_Transmit(&huart1, (uint8_t *)&ch, 1, 0xFFFF); return ch; }这段代码在微库（MicroLIB）模式下会被printf自动调用，所以工程设置里记得勾选Use MicroLIB，否则编译能过但串口就是没输出。很多新手卡在这一步，代码检查了无数遍，其实只是缺了这个编译选项。另外，HAL_UART_Transmit的超时时间我设成0xFFFF（约65毫秒），对115200波特率来说，发送一字节只需要87微秒左右，65毫秒意味着至少能发几十字节不阻塞。
串口这边我还预留了接收中断的回调函数，目前只在回调里做了个空操作，以后想用串口指令切屏、校准传感器，直接在HAL_UART_RxCpltCallback里加解析代码就行。库函数层面，我把接收中断初始化也放在了串口配置里，用HAL_UART_Receive_IT开了一个字节的接收缓冲，这样不耽误后续功能扩展。
4. Proteus仿真环境搭建与踩坑记录
很多初学者觉得仿真没什么用，但实际上手焊板之前，先把逻辑在Proteus里跑通，能省下大把查硬件故障的时间。这个项目我带了两套仿真工程，一套是纯Proteus的简易版（适合快速验证逻辑），一套是加上虚拟串口和屏幕显示的完整版（适合演示）。下面重点讲第三个版本——带OLED和DHT11模型的完整版，以及我在搭建过程中遇到的那几个破事。
4.1 元件选型和连接：DHT11模型和OLED模型怎么找
Proteus 8.9版本以后元件库里自带DHT11模型，直接搜DHT11就能看到温湿度传感器，不需要额外下载库文件。OLED屏幕的模型有几种，我用的这个叫"OLED 128x64 I2C"，虽然是第三方提供的模型但互联接口就是标准的I2C，用起来和实物没有差别。注意老版本Proteus里可能没有这个模型，要升级到8.9以上，或者去官网库管理里面搜OLED相关关键词下载安装。
连接关系上和实物原理图保持一致：PB0接DHT11数据脚，PB8接OLED_SCL，PB9接OLED_SDA，PA9接虚拟串口的TXD，公共地线连好。仿真里不需要考虑上拉电阻的问题，但为了和实物一致性，我顺手在DHT11数据线上放了一个4.7k电阻，这个是示波器观察时序用的，没有电阻的话仿真曲线也不对。
4.2 仿真工程双击高亮检查
连线完成以后，别急着运行，Proteus左下角有个电气规则检查（ERC）功能，至少运行一次确保没有未连接引脚和总线冲突的警告。尤其是I2C两条线不能接反，否则OLED初始化时检测不到设备地址，程序会卡死在等待ACK的死循环里。
如果程序跑起来屏幕不亮，先看HEX文件有没有正确加载到STM32芯片上。双击芯片打开属性对话框，Program File一栏必须指向Keil工程生成的.hex文件，注意路径不能有中文字符，否则Proteus加载失败，这个位置卡了我一晚上。我最终把HEX文件复制到和仿真工程同级目录下，相对路径引用，避免因为Keil工程每次Rebuild路径变化导致Proteus加载旧的HEX。
4.3 虚拟串口配置：和PC端联调的仿真体验
Proteus里有个COMPIM虚拟串口组件，它和本机的物理串口或虚拟串口对接。调试时我用的是Virtual Serial Port Driver这个工具创建一对互连的虚拟串口COM3和COM4，Proteus的COMPIM组件选COM3，PC端的串口助手选COM4，这样仿真里的串口数据就能真实地显示在电脑上。这个环境搭建起来步骤有点绕，但一旦跑通，调试体验和实物几乎没差别。
要说仿真的局限性：DHT11在Proteus里的响应速度比实物快得多，实物需要差不多1秒钟完成一次采集，而仿真模型几乎瞬间就能返回一组数据。所以如果你用仿真来验证"每隔2秒采集一次"的主循环逻辑，没什么问题；但如果要抠时序、验证红外信号的精确脉宽，那仿真就不够用了。DHT11模型在仿真中不会模拟真实传感器因为上电稳定慢而输出前两次"错误数据"的现象，实物上电后第一次读出的数据通常不可信，需要做"首次读取丢弃"处理。这个差别容易让直接从仿真转到实物的同学措手不及去查代码。
4.4 仿真时常用的几个调试技巧
Proteus的虚拟示波器和逻辑分析仪是排查时序问题的神器。我调DHT11时序的时候，把虚拟示波器的A通道连接到PB0引脚，设好触发条件为下降沿，运行程序后能看到完整的起始信号和40位数据的波形。对照DHT11数据手册里时序图上标准的短高电平（约26us）和长高电平（约70us）去判断代码采样的位置是否合理。这个方法比瞎改延时然后重新编译快得多。
另一个小技巧是Proteus的调试模式。如果代码里设了断点，运行到断点处可以单步执行，观察寄存器和引脚电平等实时变化。但Proteus的单步和MDK里的硬件单步不太一样，它模拟的是整个MCU执行过程，速度非常慢，所以不要在进入DHT11读取函数后单步太久，直接用断点看结果就好。我一般在主循环开始时设一个断点，确认一遍传感器数据区的内容是否正确，然后取消断点让它全速跑。
仿真工程里顺便放了两个虚拟开关，一个模拟手动重置（接NRST），一个模拟DHT11拔出时的数据处理。这两个细节是我后来补的，目的是让项目代码能处理传感器异常情况——拔掉传感器后，系统不会死机，OLED上会显示"DHT11 Error!"，串口发送"ERR"。这个处理逻辑在实物调试时同样适用，因为传感器接线松了或者虚焊是家常便饭。
5. 从仿真到实物：那些仿真里根本看不出来的差异
如果你把仿真跑得滚瓜烂熟，觉得实物一定能一次点亮，那就太天真了。我这次从仿真移植到实物板子，至少遇到了四个仿真环境根本不会给你提示的问题，逐个讲一下缘由和排查方式。
5.1 供电不足：OLED和传感器抢电流
STM32F103C8T6正常工作时电流在30~50mA左右，OLED背光开启时约20~30mA，DHT11工作时约1~2mA，加起来不到100mA，看起来USB口5V500mA完全够。但我第一次上电时OLED屏幕亮一下就灭，反复断电上电同样的现象，拿万用表量3.3V只有2.6V。问题的根源不是总电流不够，而是AMS1117-3.3需要至少1V压降才能正常工作，即输入至少4.3V。USB口供电线如果又细又长，压降叠加之后到AMS1117输入端的电压可能不到4.2V，稳压器就"罢工"了。
排查办法很简单：用万用表量AMS1117输入端的电压，如果低于4.3V，说明USB线压降太大。换上粗短线或者直接用充电宝的高质量线缆，问题马上解决。更稳的做法是在设计时给整个系统单独加一颗100uF的电解电容做输入储能，这样上电瞬间的大电流冲击不至于把电压拉崩。
5.2 I2C通信偶发失败：OLED显示花屏的元凶
实物上OLED初始化时偶发花屏，但不是每次上电都花，时好时坏。仿真完全复现不了这个现象。我排查了很久，最后用逻辑分析仪抓到现象：SCL高电平上沿有振铃，SDA上的数据在时钟高电平期间发生了跳变，I2C协议里这是不允许的。原因是模块自带上拉电阻和STM32引脚的上拉或者旁路电容在某些情况下形成了RC延迟，时钟频率稍高时建立起时间不够。
解决办法是两板斧：一是把I2C时钟从400kHz降回100kHz，几天下来花屏再没出现过；二是在OLED模块的VCC和GND之间加一颗10uF电容吸收电流毛刺。后来我还看了眼OLED模块PCB，上面只有两个小容量的退耦电容，因为模块上没有大容量电容，所以外部补一颗很有必要。做项目要记住一句话：功能能用和稳定可靠是两码事，仿真里的稳定不代表实物的稳定。
5.3 DHT11第一次读数异常：上电后的"冷启动"问题
实物上电后，DHT11第一次读出的温湿度数据往往是错的，常见的是显示温度-999或者湿度0%，第二次才正常。这个是DHT11的固有特性：传感器上电后需要至少1秒钟稳定时间，在稳定期内MCU发起的读取请求会被忽略或者返回错乱数据。仿真模型没有这个特征，所以从仿真直接转实物的人容易误以为是代码Bug。
我的处理方式是在代码初始化里加了一个"首次采集无效"机制：系统上电后延时2秒再开始采集，第一次采集结果只做丢弃处理，从第二次开始才显示和发送。这个逻辑虽然简单，但体现了对传感器特性的理解，也避免了OLED上出现一闪而过的"垃圾数据"。
5.4 实物调试时软件和硬件的配合方法
这里分享一个调试工具的组合方案。我用一个USB转TTL模块（CH340核心）当串口调试器，接PA9/PA10，注意RX接TX、TX接RX这个交叉关系，和仿真里的虚拟串口逻辑一样。另外准备一个8通道的逻辑分析仪，采样率调20MHz，用来抓DHT11的单总线时序。逻辑分析仪的强大之处是你能看到毫秒级的完整通信过程，比示波器更适合做数字协议分析。
有个容易被忽视的问题：如果是用ST-Link给板子供电并连接SWD调试，那么调试器的复位信号可能和板子上NRST按键彼此干扰，导致程序运行时偶尔复位。排查办法是调试时用ST-Link供电并只接SWDIO、SWCLK、GND三条线，不接NRST，需要复位的时候直接在IDE里点Reset按钮。
6. 开源发布的规范与项目的后续扩展方向
项目能跑通只是第一步，把项目"交付"出去才是开源的精神所在。我这个仓库从最初的私有状态到公开推送，中间花了不少时间整理文档和结构。这里面的经验对任何一个想做嵌入式开源的人来说都值得参考。
6.1 仓库结构设计与README的写法
我的仓库目录长这样：
STM32-Env-Monitor/ ├── Hardware/ # 原理图和PCB源文件、PDF版本 ├── Firmware/ # Keil5工程源码 │ └── MDK-ARM/ # 编译输出目录，含.hex文件 ├── Simulation/ # Proteus仿真工程 ├── Docs/ # 文档说明、引脚连接表、图片 ├── LICENSE └── README.mdREADME里除了项目名称和简介，我认为最核心的三个部分是：技术参数表（主控型号、传感器型号、通信接口、供电电压）、引脚连接表（和这篇博文里的表格一样，让使用者照着接就行）、快速开始指南（从打开CubeMX到编译烧录一步一步写清楚）。如果你想让别人顺利复现，那这三个内容缺一不可。引脚表尤其重要——我见过有开源项目不给引脚定义，使用者只能反推代码，体验极差。
6.2 License选择：开源不等于放弃版权
很多刚接触开源的人以为把代码扔到网上就是"开源"，实际上不声明License的仓库在法律上默认是"保留所有权利"，别人不能用、不能改、不能分发。我这项目选的是MIT License，它允许任何人自由使用、修改、再分发，甚至商用，只要保留原作者的版权声明。MIT是嵌入式开源项目里最常见的选择，因为它最宽松，最能促进代码传播。
要是你希望自己的代码被改进后也必须开源，那就选GPLv3；如果你主要面向商业应用且不希望别人轻易用你的源码做产品，那可以选Apache 2.0，它对专利授权有更明确的说明。我个人的建议是：刚开始做开源，选MIT或者Apache 2.0，别一上来就搞GPL，GPL的传染性会限制很多潜在的使用场景，减少项目的传播范围。
6.3 从"能跑"到"能用"：这个项目的扩展路线
现在的版本算是一个比较完整的最小系统，但真要拿去当毕业设计亮点或者实际环境监测工具，还有几条明确的扩展路线。
- 加实时时钟：挂一颗DS3231或者DS1302，在OLED上显示实时时间，数据记录才有参考价值。DS3231走I2C，扩展成本很低。
- 加存储记录：用SPI接口的W25Q64存历史数据，或者简单点把数据以CSV格式通过串口上位机保存到PC。
- 加WiFi联网：最常接的就是ESP8266或ESP-01s，通过AT指令或者固件刷成MQTT协议后把数据上传到云平台，实现远程监控。
- 加菜单交互：在OLED上做两级菜单，用按键切换显示温度、湿度、运行状态，这会让项目的"软件工程感"一下子提升一个档次。
- OTA升级：STM32的固件升级从Bootloader + App结构入手，用IAP协议和YModem传输，配合串口或者WiFi模块实现远程更新。这个方向比较进阶，但对做产品化落地是必需品。
我个人比较推荐按"RTC -> 存储 -> 菜单 -> WiFi"这个顺序去做，每一环都能复用现有代码架构，新增模块不需要改动主循环以外的老代码。这才是模块化设计的红利。
6.4 开源之后：维护记录和社区互动
最后想聊聊代码公开之后的事。我这次把项目推到Gitee上，遇到的第一个问题是issue——有人按照README操作后烧录程序，但OLED不亮。我让他查了两点：CubeMX配置里Debug选项改没改；HEX文件路径是否含中文。后来确认是他Keil工程放到了某个中文路径下，Proteus加载不到HEX导致的。这个经验让我的README里立刻补了一句"所有路径建议英文，不要出现汉字"。开源项目真正的价值就在于这种"被使用、被反馈、被修正"的循环。
建议每位准备开源ST项目的人，仓库里放一个CHANGELOG文件，每次提交时顺手记一下"这个版本改了什么"，这样不仅使用者能了解版本演变，半年后你自己回头看，也知道当时的决策原因。再就是给版本打标签，v1.0.0、v1.1.0这种语义化版本号，和CHANGELOG配合起来，项目成熟度一目了然。
做这个项目前前后后花了两周多，其中一半时间在整理仓库结构、写文档、录演示视频。我觉得这才是开源项目该有的样子：不是把半成品丢出去，而是让任何一个拿到代码的人都能在半天之内跑起来、看懂、并且愿意在此基础上继续改进。希望这篇拆解能让你在参考这个项目时少走一些弯路，特别是那些仿真和实物之间的差异，我踩过的坑你真的可以避开。
