直接在这篇博客里我把自己调试这块板子的完整过程、踩过的坑、最终跑通的代码框架全部整理出来了。不用你再去翻手册、翻论坛照着做就能出结果。1. 项目到底是什么选型时我在想什么Y01-3IN1空气质量模块从名字就能看出来它把三种测量功能集成到了一块小板上环境温度、相对湿度以及空气质量相关的气体浓度常见的是TVOC/甲醛或者等效CO₂具体量程和输出协议看厂家版本。相比自己搭三个独立传感器这种三合一模块最大的好处是省事一个串口或者I2C就能把三类数据全部读回来不用分别处理不同传感器的时序、校准和换算公式。对于做室内空气监测、智能家居节点、毕业设计这类场景性价比很高。STM32作为主控在这个项目里主要干三件事通过UART接收模块的测量数据帧通过I2C把数据送到OLED屏幕以及把温湿度、空气质量值换算成人类看得懂的数字和文字。选STM32而不是Arduino或ESP32主要是考虑到很多读者手里已经有STM32开发板尤其是F103系列而且用HAL库写出来的代码后面想移植到F4、G0、L4系列都很方便不会像寄存器版本那样被某块板子锁死。OLED选择的是0.96寸、128x64分辨率、SSD1306控制器的I2C版本这是目前最主流的小尺寸显示方案。I2C只需要两根线SDA、SCL就能完成通信省下宝贵的GPIO口。整篇文章的路线是先说硬件怎么接然后用STM32CubeMX初始化工程接着分两个大块写软件——OLED驱动和空气质量模块的数据解析最后拼在一起跑出实际显示效果。适合看这篇教程的人我总结一下刚接触STM32 HAL库想拿一个真实传感器项目练手的同学。要做室内空气监测、桌面气象站、智能家居小节点需要快速上手的开发者。手里有Y01-3IN1模块但找不到清晰资料对数据帧格式一头雾水的人。想把OLED显示功能彻底搞明白从驱动层到显示层都吃透的爱好者。2. 硬件准备与接线别在第一步翻车2.1 物料清单这个项目用到的硬件非常少基本都是手头常见的编号物料型号/规格数量1STM32开发板任意F103系列推荐C8T6最小系统板或正点原子/野火板子12Y01-3IN1空气质量模块三合一温湿度空气质量13OLED显示屏0.96寸128x64I2C接口SSD130614杜邦线母对母、母对公若干若干5USB转TTL调试用CH340或CP21021可选如果你手里的OLED是SPI接口的那接线方式和代码驱动会完全不同建议还是用I2C版本因为模块本身如果也是I2C输出那整个系统只要两根数据线清爽很多。2.2 Y01-3IN1模块接口判断很多拿到这个模块的人第一反应是看丝印。常见丝印有VCC、GND、TX、RX、SDA、SCL、A0、D0之类的。这里有个容易搞混的点不同批次的Y01-3IN1输出接口可能不一样。如果你看到的是TX/RX说明模块是UART串口输出直接用STM32的USART接收。如果你看到的是SDA/SCL说明模块是I2C输出那就要用STM32的I2C外设去读取。有些版本两种模式都支持通过模块上的跳线或者配置命令切换。我手头这块板子用的是UART输出也就是通过串口主动向上位机发送数据帧。这种方式最简单不需要主机发指令去查询模块上电后以固定周期一般是1秒一次往外丢数据我们只要在STM32端把数据接收下来解析就行。2.3 接线表和供电注意事项以STM32F103C8T6为例接线如下Y01-3IN1STM32F103C8T6OLEDSTM32F103C8T6VCC5V或3.3VVCC3.3VGNDGNDGNDGNDTX模块发送PA10USART1_RXSDAPB7I2C1_SDARX模块接收若需要PA9USART1_TXSCLPB6I2C1_SCL注意Y01-3IN1的VCC供电电压以模块丝印/说明书为准。如果模块标注5V供电就接5V如果标注3.3V千万不能接5V否则可能烧掉传感器。我见过不少案例就是因为图省事把模块插到了5V上结果气体传感器直接报废。拿不准的时候先看丝印再看手册最后用万用表量一下模块自身的稳压电路。还有一个值得注意的细节模块的TX脚输出电平一般是3.3V的。如果模块是5V供电但是输出电平还是3.3V板上有电平转换电路那直接接STM32的PA10没问题。如果是老式模块输出5V电平那中间最好加一个电阻分压或者电平转换模块避免把STM32的IO口打坏。判断方法很简单用万用表量模块TX引脚在空闲状态下的电平高电平是3.3V就安全是5V就要处理。OLED的供电电压通常是3.3V也有少数5V兼容版。I2C的SDA和SCL是开漏输出需要上拉电阻不过SSD1306模块板上基本上都已经自带上拉电阻了直接接STM32的I2C引脚即可。2.4 上电前的最后检查接线完成后不要急着写代码。先做三步检查用万用表蜂鸣档测一下VCC和GND之间有没有短路防止杜邦线插错位置。确认STM32板子上的3.3V和GND是通的因为你可能需要从OLED模块取3.3V。单独给Y01-3IN1上电用逻辑分析仪或者示波器看它的TX引脚有没有波形输出。如果没有逻辑分析仪可以用USB转TTL接电脑串口助手看有没有数据刷屏。如果串口助手能收到数据说明模块是好的而且你能顺便确认它的波特率。我手上这块板子默认波特率是9600但不同厂家可能用4800、115200等这一步不做后面STM32解析就会全是乱码。3. 用STM32CubeMX搭建工程5分钟搞定外设初始化3.1 创建工程与时钟配置这里我用的是STM32CubeMX图形化配置工具加HAL库理由很直接效率高不易错而且生成代码可读性很好。你不需要手动去翻参考手册计算时钟树鼠标点几下就能完成。打开CubeMX新建Project选择芯片型号STM32F103C8Tx然后进入Pinout Configuration界面。先配置RCC高速时钟在System Core下的RCC里把HSE设置成Crystal/Ceramic Resonator晶振方式这样使用板载8MHz晶振作为高速时钟源。然后进入Clock Configuration把主频HCLK配到72MHz这是F103的标准满速。CubeMX会自动帮你算好PLL分频倍频系数你只需要在HCLK框里输入72然后回车它会弹出对话框问你是否让软件自动调整选Yes就行。在这个界面里可以看到系统时钟树从HSE经过PLL到AHB总线的完整路径直观了解STM32的时钟架构。有的新手会忽略这一步直接用默认的HSI内部时钟8MHz也能跑但I2C的时序会比较紧张而且后面如果加定时器、ADC之类的功能时钟不够用就会出各种奇怪问题。所以还是那句话先把时钟树配好后面省心。3.2 USART1配置Y01-3IN1模块通过串口发送数据所以我们需要一个UART外设。在左侧Categories列表里找到Connectivity点开USART1然后在右侧Pinout视图里会看到PA9和PA10被自动分配为USART1_TX和USART1_RX。Mode选择Asynchronous异步模式这样只需要TX、RX两根线就够了。在Parameter Settings里配置参数值Baud Rate9600Word Length8 BitsParityNoneStop Bits1波特率这里先填9600这只是个初始值。如果你之前在串口助手里确认模块是其他波特率这里改成对应的值即可。实操心得我一开始没有用串口助手确认波特率直接按说明书默认9600配好了结果收到的数据全是0xFF或者乱码。后来接USB转TTL一看原来模块实际是4800波特率说明书和实际不一致。这种细节在新出的模块上经常遇到因为厂家可能会在出货前调整固件。所以先接串口助手确认再配CubeMX这个顺序千万别省。3.3 I2C1配置OLED用的是I2C接口。在Categories列表里找到Connectivity点开I2C1Mode选择I2C默认就是I2C模式在Parameter Settings里主要关注两个参数Speed Mode和I2C Speed Frequency。一般我们选Standard Mode100kHz或者Fast Mode400kHz都可以。SSD1306在I2C模式下最高支持到400kHz左右但STM32F103的I2C外设实现有时候在Fast Mode下会有些时序抖动稳妥起见我先选Standard Mode 100kHz等代码跑通了再尝试加快速度。I2C1的引脚会自动分配到PB6SCL和PB7SDA这正好是硬件I2C1的默认引脚不需要手动改。3.4 工程设置与代码生成在Project Manager选项卡里填好Project Name和LocationToolchain选择MDK-ARM也就是Keil或者你习惯用STM32CubeIDE的话选STM32CubeIDE也行。重点来了在Project Manager的Code Generator里勾选Generate peripheral initialization as a pair of .c/.h files per peripheral每个外设单独生成c/h文件和Add necessary library files as reference in the toolchain添加必要的库文件到工程。这样生成的代码会把每个外设的初始化函数独立放结构清晰调试的时候不容易搞混。点击GENERATE CODE生成代码然后用Keil或者CubeIDE打开工程。此时编译一次应该能零错误通过说明环境没问题可以开始往里面填业务逻辑了。4. OLED驱动细节从像素到字符的原理4.1 SSD1306控制器核心机制0.96寸OLED128x64的核心控制器是SSD1306它的显示原理和传统LCD完全不同。简单说屏幕分成128列、64行每个像素点就是一个OLED有机发光二极管通电就亮断电就灭没有背光所以黑色区域是真正不发光对比度极高。SSD1306内部有一块1KB的GDDRAM显存分成8页Page0到Page7每页有128个字节每个字节对应一行中的8个像素点垂直方向。也就是说这64行像素被分成了8个水平条每个条高8像素。你往某个Page的某个字节写入0x55就等于把这个字节对应的8个垂直像素点间隔点亮。这是SSD1306最核心的寻址原理刚开始接触OLED的人需要花点时间理解这种页列的结构。画图的时候大多数驱动库比如比较流行的u8g2或Adafruit_SSD1306底层封装了SSD1306的写显存接口你只需要操作一个128x64的缓冲区数组最后统一刷到屏幕即可。4.2 I2C读写OLED的时序SSD1306在I2C模式下从机地址固定是0x3C如果SA0引脚接地或者0x3DSA0接高。大多数模块SA0默认接地所以地址0x3C如果过手机地址不对可以在代码里把地址改成0x3D试试。用HAL库发送命令的流程是起始信号发送从机地址写位0x3C 1 | 0发送控制字节0x00表示后续是命令0x40表示后续是数据发送命令/数据终止信号在HAL库里这个流程可以封装成一个很小的函数使用HAL_I2C_Mem_Write或直接HAL_I2C_Master_Transmit。下面是用HAL_I2C_Master_Transmit发命令的写法#define OLED_ADDR 0x3C void OLED_WriteCmd(uint8_t cmd) { uint8_t buf[2]; buf[0] 0x00; // 控制字节命令 buf[1] cmd; HAL_I2C_Master_Transmit(hi2c1, OLED_ADDR 1, buf, 2, 100); } void OLED_WriteData(uint8_t data) { uint8_t buf[2]; buf[0] 0x40; // 控制字节数据 buf[1] data; HAL_I2C_Master_Transmit(hi2c1, OLED_ADDR 1, buf, 2, 100); }注意HAL_I2C_Master_Transmit的地址参数需要左移一位因为HAL库内部处理7位地址时要求传入完整8位地址也就是把7位地址左移1位最低位是读写标志而且传入的值需要是设备地址左移1位的结果。容易漏掉的部分漏了的话OLED完全没反应这算是HAL库使用中一个很典型的坑。4.3 初始化命令序列SSD1306上电后需要发一串初始化命令才会开始工作。网上各种代码的初始化序列大同小异关键是几组命令0xAE/0xAF关闭/开启显示0x8D 0x14开启内部电荷泵这是OLED能亮起来的关键0xD5 0x80设置显示时钟分频/振荡频率0xA8 0x3F设置多路复用比128x64屏幕填0x3F0xD3 0x00显示偏移0x40设置显示起始行0xA1设置段重映射左右镜像相关0xC8设置COM扫描方向上下镜像相关0xDA 0x12设置COM引脚硬件配置64行屏幕用0x120x81 0x7F设置对比度0xA4从RAM内容显示正常0xA6设置为正常显示非反显初始化完成后把显示内存全部清除写入0x00再打开显示0xAF屏幕上显示什么完全由你往GDDRAM写的数据决定。小技巧如果你不想重新发明轮子可以用现成的ssd1306.h/ssd1306.c开源驱动Github上很多再把HAL库的I2C发送接口替换成上面那两个函数就行。但我的建议是自己动手把初始化序列写一遍哪怕只写一遍你对这个显示器的理解深度会和直接调用库完全不一样。4.4 显示字符和数字的实现思路要在OLED上显示文字最朴素的办法是建一个字模库点阵字库每个字符用一个数组表示数组里的每一位对应一个像素点1就点亮0就熄灭。常见的字模是8x16或者16x168x16表示字符占8列16行刚好和SSD1306的一页一列对齐处理起来很方便。以显示一个ASCII字符为例先定义一个8x16的字模数组比如字符Aconst uint8_t font8x16[95][16] { // A 0x41 { 0x00,0x00,0x00,0x18,0x3C,0x66,0x66,0x7E, 0x66,0x66,0x66,0x66,0x00,0x00,0x00,0x00 }, // ... 其他字符 };然后在指定位置显示这个字符把每一列的数据写入对应的页即可。更高效的做法是在内存里维护一个128x64的显存缓冲区用一个128x8 1024字节的数组模拟所有显示操作画点、画线、画字符都先往缓冲区里写最后用一个批量刷新函数把整个缓冲区一次性发到SSD1306。这样避免了频繁I2C操作画面也不会闪烁。刷新函数核心就是循环8页每页发128字节数据用HAL_I2C_Mem_Write可以快速搞定甚至支持DMA不过对于本项目显示频率不高阻塞发送就够用了。5. Y01-3IN1数据解析关键是搞懂数据帧5.1 模块工作原理Y01-3IN1内部的三个传感器分工明确温湿度传感器负责测量环境温度和相对湿度空气质量传感器负责检测气体浓度。模块内部自带的MCU会读取这些传感器的数据进行简单的滤波和校准然后按照协议格式通过串口发送出来。这样做的好处是传感器侧的工作全部被封装好了。如果你自己买独立的温湿度传感器和气体传感器就得分别处理I2C地址冲突、上电时序、校准命令麻烦得多。三合一模块把这些问题全部解决了代价是你必须严格按照它的帧格式解析数据。我在市面上见过的Y01-3IN1模块输出帧格式大概是这样帧头长度数据类型温度高字节温度低字节湿度高字节湿度低字节气体高字节气体低字节校验0xFF0x0C0x01..................X不过请注意不同厂家对Y01-3IN1这个词的使用并不完全统一。有的模块输出的是甲醛浓度单位ug/m³有的是TVOC指数有的是CO2当量字节序和校验算法也可能不同。这篇文章里我给出一套通用的解析框架你只要根据自己模块的说明书把对应字节位置和换算系数替换一下就能复用。5.2 解析代码的框架设计先用一个状态机来接收串口数据。状态机是处理不定长数据帧最经典的方案每收到一个字节判断当前状态把帧头、长度、数据、校验一步步凑齐。先说接收时的数据结构#define FRAME_HEADER1 0xFF #define FRAME_HEADER2 0x0C // 按实际帧头调整 #define FRAME_DATA_LEN 9 // 按实际长度调整 uint8_t rx_buffer[32]; uint8_t rx_index 0; uint8_t frame_complete 0; void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { uint8_t byte; if (huart-Instance USART1) { // 从环形缓冲区/变量中读取接收到的字节 byte rx_byte; // rx_byte 是 HAL_UART_Receive_IT 接收到的单字节 // 用状态机处理 static uint8_t state 0; switch(state) { case 0: if (byte FRAME_HEADER1) { rx_buffer[0] byte; rx_index 1; state 1; } break; case 1: rx_buffer[rx_index] byte; if (rx_index FRAME_DATA_LEN 4) { state 2; } break; case 2: // 校验 if (CheckCRC(rx_buffer, FRAME_DATA_LEN 2)) { frame_complete 1; ParseFrame(rx_buffer); } state 0; rx_index 0; break; } // 继续开启下一次接收 HAL_UART_Receive_IT(huart1, rx_byte, 1); } }这里的关键是在main函数里先调用一次HAL_UART_Receive_IT开启单字节中断接收之后每次回调里重新开启。这个模式要记住否则中断触发一次后就不再有新的数据进来了这也是新手最容易犯的错误之一。5.3 温湿度换算帧里的温湿度一般以16位有符号整数传输单位是0.01°C或0.01%RH。也就是说如果收到的温度原值是2500那实际温度是25.00°C。换算很简单int16_t temp_raw (int16_t)((rx_buffer[3] 8) | rx_buffer[4]); int16_t humi_raw (int16_t)((rx_buffer[5] 8) | rx_buffer[6]); float temperature temp_raw * 0.01f; float humidity humi_raw * 0.01f;如果按这个公式算出来的温度明显不对比如几百度的荒谬值那基本可以确定是字节序或者单位不对需要查看你的模块说明书确认。5.4 空气质量数值解析空气质量部分的解析要看模块类型。如果是气体浓度数值比如CO2或TVOC一般也是16位整数可能是原始ADC值也可能已经是线性化的浓度单位。我们假设模块输出的空气质量字段单位是ppm百万分之一浓度那解析方式uint16_t air_quality_raw (uint16_t)((rx_buffer[7] 8) | rx_buffer[8]); float air_quality_ppm air_quality_raw * 1.0f; // 是否要乘系数看手册如果模块输出的是等级1-5级比如1级优、5级差那就要做映射了。我这边建议直接在OLED上同时显示原始数值和一个简单的等级说明比如const char* GetAirLevel(float ppm) { if (ppm 400) return Excellent; if (ppm 1000) return Good; if (ppm 2000) return Moderate; return Poor; }从实用角度讲用户看到空气质量等级 数值比看到一个孤零零的数字直观得多。这个思路在做显示界面的时候用处很大。5.5 校验算法的实现校验是整个解析里最容易踩坑的地方也是排查为什么数据偶尔出问题的关键。不同手册的校验算法五花八门校验和Sum Check把帧的所有字节加起来取低8位和帧尾的校验字节比对。CRC8常见的多项式是0x31和MAXIM/DS18B20一样的算法。XOR校验把所有字节异或得到的结果作为校验字节。最简单的实现是求和校验uint8_t CheckSum(uint8_t *data, uint8_t len) { uint8_t sum 0; for (uint8_t i 0; i len; i) { sum data[i]; } return sum; }然后和接收到的校验字节比较相等则说明这一帧数据没有被破坏。校验不通过时我建议直接把这一帧丢弃不要用半截数据更新显示否则屏幕上会出现跳动明显的错误值。实操心得我在调试的时候遇到过一种情况模块刚上电的几秒内输出的是不定长的校准数据帧格式和正常数据帧不一样。这时候如果用固定的帧解析逻辑去处理会一直卡在校验错误。解决办法很简单软件里做一个超时或者帧计数逻辑连续失败多次后重新同步帧头。也就是在状态机里如果超过一定时间没有收到预期数据就强制回到等待帧头的初始状态。6. 界面设计与主循环逻辑把数据用起来6.1 数据流打通后的总体结构当OLED驱动和数据解析都完成后把它们串联起来。主循环的逻辑很清晰int main(void) { // HAL初始化、外设初始化、OLED初始化 OLED_Init(); OLED_Clear(); OLED_ShowString(0, 0, System Init..., Font_8x16); // 开启UART中断接收 HAL_UART_Receive_IT(huart1, rx_byte, 1); while (1) { if (frame_complete) { frame_complete 0; OLED_UpdateDisplay(); // 刷新整屏 } HAL_Delay(10); } }实际上我建议把显示刷新和控制逻辑分离。数据解析在UART中断回调里完成显示刷新在主循环里做两者通过全局变量或者结构体传递数据。由于解析速度很快一帧数据几毫秒内就能处理完中断里的工作量很小不会影响系统实时性。6.2 OLED界面布局实操128x64的屏幕能显示的信息有限但合理安排布局还是能装下不少内容。我的排列方式第一行标题Air Quality Monitor用较小字号。第二行温度显示格式Temp: 25.5 C用8x16字体。第三行湿度显示格式Humi: 45.2 %。第四行空气质量显示格式Air: Good或Air: 356 ppm。如果要显示中文字符需要准备16x16的中文字模这会让字库文件变得很大显示多少字就要拷多少字模。如果你不追求中文字体ASCII字符配合缩写完全够用。OLED的显示坐标xy和SSD1306的页结构有关8x16字体的每个字符占8列宽、16行高所以x坐标按8的倍数排y坐标按16的倍数排。我常用的一个简化方法是写一个OLED_SetPos(x, y)函数里面把y转换成页地址y/8再按页码设置起始列地址这样画字符的时候就非常直观。6.3 刷新策略与防闪烁OLED刷屏如果每次只改一个数字也整屏刷新会显得很闪。虽然SSD1306本身没有余晖效应但整屏重写时人眼能感受到轻微闪烁尤其在显示大量文本时比较明显。想避免闪烁有两个办法局部区域更新只把一个数值所在的8x16区域重新发送不整屏刷。屏幕缓冲分块维护一个脏标记某区域的值变了才去刷新对应区域。对于这个项目数据1秒才更新一次整屏刷新其实不怎么闪。但如果你要加快刷新频率建议用脏标记法。我实现的时候就是在每个数据更新后调用一次区域刷新函数参数是坐标和宽高内部只发送对应页和列的数据这样比全屏刷新快4倍左右。6.4 数据的平滑处理传感器原始数据有时候会跳变比如人从传感器旁边走过温度瞬间波动1°C空气质量数值起伏更大。如果OLED上的数字跟着剧烈跳动观感很差。解决办法是滑动平均滤波#define FILTER_SIZE 10 float temp_history[FILTER_SIZE]; uint8_t temp_index 0; float temp_sum 0.0f; float FilterTemperature(float new_temp) { temp_sum - temp_history[temp_index]; temp_history[temp_index] new_temp; temp_sum new_temp; temp_index (temp_index 1) % FILTER_SIZE; return temp_sum / FILTER_SIZE; }滑动平均的优点是实现简单、内存占用小而且能有效滤掉高频噪声。代价是响应速度变慢大概是滤波窗口长度乘以采样周期的滞后。对于室内空气质量监测这种对实时性要求不高的场景10次平均10秒完全能接受。7. 调试实录我遇到的四个卡壳问题7.1 OLED不亮或者显示乱码这个现象大概是这种项目的头号问题原因是多样的。先看电源用万用表量OLED的VCC引脚是不是3.3V如果GND没接好模块可能半亮不亮。再看接线确认SDA接PB7SCL接PB6或者你在CubeMX里配的其他I2C引脚不要把SDA和SCL接反。最后看代码确认初始化时调用了OLED_Init而且I2C地址没错。我吃过的亏是把SSD1306当成0x3D去驱动屏幕上完全无反应改回0x3C后立刻正常。如果显示乱码那多半是初始化序列里某个参数不对。比如设置COM扫描方向0xC8和段重映射0xA1这两条反了会出现上下镜像或左右镜像看起来像乱码但其实数据是对的改一下命令参数就能恢复。7.2 UART收到全0xFF或者全0x00全0xFF通常说明引脚悬空或者接线错误串口读到了空闲电平。检查TX/RX是不是接反了确认模块的TX确实连到了STM32的RX。全0x00则可能是模块没正常工作没有数据输出检查模块的供电和使能引脚。如果串口助手能收到正常数据但STM32收不到那就要检查GPIO复用配置是否正确。在CubeMX里配置好USART1后PA9/PA10的GPIO模式会被自动设置成复用推挽/复用开漏不需要手动干预。如果你自己手写了GPIO初始化代码覆盖了CubeMX的设置就会导致UART失效。7.3 波特率不对导致乱码这是我前面反复强调过的问题。乱码的典型特征是能看到有规律的波形但解析出来全是乱七八爪的值。用逻辑分析仪或者串口助手确认模块的实际波特率然后在CubeMX里改过来就行。有的模块在固件里可以配置比如发送特定命令切换波特率这也要看说明书。7.4 HAL_UART_Receive_IT只收到一帧就停了这就是前面提到的中断只开启一次的问题。HAL_UART_Receive_IT是一次性的接收完成回调后不会自动开启下一次接收。如果你不在回调里重新调用一次串口就再也收不到数据了。这是HAL库小白一定会踩的坑解决办法就是在HAL_UART_RxCpltCallback末尾再加一行HAL_UART_Receive_IT。常见问题排查方向解决方法OLED完全无显示供电、接线、I2C地址万用表量VCC/GND确认SDA/SCL检查0x3C/0x3DOLED乱码/镜像初始化命令序列调整0xA1段重映射和0xC8扫描方向UART全0xFF接线错误或引脚悬空检查TX/RX是否接反确认模块供电UART乱码波特率不匹配用串口助手确认实际波特率并修改CubeMX配置数据帧校验失败帧格式不匹配按说明书逐字节核对帧头和长度调整解析代码数值跳变严重传感器噪声加入滑动平均滤波8. 这个项目还能怎么扩展把STM32、Y01-3IN1和OLED这三样东西的基本用法搞清楚之后其实可以做很多有意思的延展一是加数据存储。用STM32内部Flash或者外接SPI Flash把长时间采集的温湿度和空气质量数据存下来按天/周生成趋势。加上一个RTC时钟芯片或者用STM32内部的RTC就能在OLED上显示时间戳成为一个小型环境记录仪。二是加联网功能。接一个ESP8266或者ESP32模块把数据通过WiFi上传到云平台比如MQTT服务器或者物联网平台这样手机APP上就能实时查看家里的空气质量。如果不想折腾云服务也可以用蓝牙模块HC-05/HC-08和手机串口助手通信几行代码就能实现。三是加报警功能。当空气质量数值超过设定的阈值时驱动蜂鸣器响、LED闪烁或者通过继电器控制新风系统/排风扇自动启动。这类联动逻辑很适合放在智能家居项目里。四是换显示屏。如果你觉得128x64太小可以直接换1.3寸或者2.4寸的TFT屏幕ST7735/ILI9341I2C不够用就用SPI显示的界面内容可以丰富很多。OLED的驱动代码主体思路不变显示层做一次适配即可。如果在实操中还是有问题我建议你把模块的说明书尤其是串口协议部分、接线照片、串口助手截屏整理好一起排查。大多数情况下问题都出在线没接对和波特率没对上这两类逐个排除一定能跑通。 STM32驱动Y01-3IN1空气质量模块+OLED显示完整指南
直接在这篇博客里我把自己调试这块板子的完整过程、踩过的坑、最终跑通的代码框架全部整理出来了。不用你再去翻手册、翻论坛照着做就能出结果。1. 项目到底是什么选型时我在想什么Y01-3IN1空气质量模块从名字就能看出来它把三种测量功能集成到了一块小板上环境温度、相对湿度以及空气质量相关的气体浓度常见的是TVOC/甲醛或者等效CO₂具体量程和输出协议看厂家版本。相比自己搭三个独立传感器这种三合一模块最大的好处是省事一个串口或者I2C就能把三类数据全部读回来不用分别处理不同传感器的时序、校准和换算公式。对于做室内空气监测、智能家居节点、毕业设计这类场景性价比很高。STM32作为主控在这个项目里主要干三件事通过UART接收模块的测量数据帧通过I2C把数据送到OLED屏幕以及把温湿度、空气质量值换算成人类看得懂的数字和文字。选STM32而不是Arduino或ESP32主要是考虑到很多读者手里已经有STM32开发板尤其是F103系列而且用HAL库写出来的代码后面想移植到F4、G0、L4系列都很方便不会像寄存器版本那样被某块板子锁死。OLED选择的是0.96寸、128x64分辨率、SSD1306控制器的I2C版本这是目前最主流的小尺寸显示方案。I2C只需要两根线SDA、SCL就能完成通信省下宝贵的GPIO口。整篇文章的路线是先说硬件怎么接然后用STM32CubeMX初始化工程接着分两个大块写软件——OLED驱动和空气质量模块的数据解析最后拼在一起跑出实际显示效果。适合看这篇教程的人我总结一下刚接触STM32 HAL库想拿一个真实传感器项目练手的同学。要做室内空气监测、桌面气象站、智能家居小节点需要快速上手的开发者。手里有Y01-3IN1模块但找不到清晰资料对数据帧格式一头雾水的人。想把OLED显示功能彻底搞明白从驱动层到显示层都吃透的爱好者。2. 硬件准备与接线别在第一步翻车2.1 物料清单这个项目用到的硬件非常少基本都是手头常见的编号物料型号/规格数量1STM32开发板任意F103系列推荐C8T6最小系统板或正点原子/野火板子12Y01-3IN1空气质量模块三合一温湿度空气质量13OLED显示屏0.96寸128x64I2C接口SSD130614杜邦线母对母、母对公若干若干5USB转TTL调试用CH340或CP21021可选如果你手里的OLED是SPI接口的那接线方式和代码驱动会完全不同建议还是用I2C版本因为模块本身如果也是I2C输出那整个系统只要两根数据线清爽很多。2.2 Y01-3IN1模块接口判断很多拿到这个模块的人第一反应是看丝印。常见丝印有VCC、GND、TX、RX、SDA、SCL、A0、D0之类的。这里有个容易搞混的点不同批次的Y01-3IN1输出接口可能不一样。如果你看到的是TX/RX说明模块是UART串口输出直接用STM32的USART接收。如果你看到的是SDA/SCL说明模块是I2C输出那就要用STM32的I2C外设去读取。有些版本两种模式都支持通过模块上的跳线或者配置命令切换。我手头这块板子用的是UART输出也就是通过串口主动向上位机发送数据帧。这种方式最简单不需要主机发指令去查询模块上电后以固定周期一般是1秒一次往外丢数据我们只要在STM32端把数据接收下来解析就行。2.3 接线表和供电注意事项以STM32F103C8T6为例接线如下Y01-3IN1STM32F103C8T6OLEDSTM32F103C8T6VCC5V或3.3VVCC3.3VGNDGNDGNDGNDTX模块发送PA10USART1_RXSDAPB7I2C1_SDARX模块接收若需要PA9USART1_TXSCLPB6I2C1_SCL注意Y01-3IN1的VCC供电电压以模块丝印/说明书为准。如果模块标注5V供电就接5V如果标注3.3V千万不能接5V否则可能烧掉传感器。我见过不少案例就是因为图省事把模块插到了5V上结果气体传感器直接报废。拿不准的时候先看丝印再看手册最后用万用表量一下模块自身的稳压电路。还有一个值得注意的细节模块的TX脚输出电平一般是3.3V的。如果模块是5V供电但是输出电平还是3.3V板上有电平转换电路那直接接STM32的PA10没问题。如果是老式模块输出5V电平那中间最好加一个电阻分压或者电平转换模块避免把STM32的IO口打坏。判断方法很简单用万用表量模块TX引脚在空闲状态下的电平高电平是3.3V就安全是5V就要处理。OLED的供电电压通常是3.3V也有少数5V兼容版。I2C的SDA和SCL是开漏输出需要上拉电阻不过SSD1306模块板上基本上都已经自带上拉电阻了直接接STM32的I2C引脚即可。2.4 上电前的最后检查接线完成后不要急着写代码。先做三步检查用万用表蜂鸣档测一下VCC和GND之间有没有短路防止杜邦线插错位置。确认STM32板子上的3.3V和GND是通的因为你可能需要从OLED模块取3.3V。单独给Y01-3IN1上电用逻辑分析仪或者示波器看它的TX引脚有没有波形输出。如果没有逻辑分析仪可以用USB转TTL接电脑串口助手看有没有数据刷屏。如果串口助手能收到数据说明模块是好的而且你能顺便确认它的波特率。我手上这块板子默认波特率是9600但不同厂家可能用4800、115200等这一步不做后面STM32解析就会全是乱码。3. 用STM32CubeMX搭建工程5分钟搞定外设初始化3.1 创建工程与时钟配置这里我用的是STM32CubeMX图形化配置工具加HAL库理由很直接效率高不易错而且生成代码可读性很好。你不需要手动去翻参考手册计算时钟树鼠标点几下就能完成。打开CubeMX新建Project选择芯片型号STM32F103C8Tx然后进入Pinout Configuration界面。先配置RCC高速时钟在System Core下的RCC里把HSE设置成Crystal/Ceramic Resonator晶振方式这样使用板载8MHz晶振作为高速时钟源。然后进入Clock Configuration把主频HCLK配到72MHz这是F103的标准满速。CubeMX会自动帮你算好PLL分频倍频系数你只需要在HCLK框里输入72然后回车它会弹出对话框问你是否让软件自动调整选Yes就行。在这个界面里可以看到系统时钟树从HSE经过PLL到AHB总线的完整路径直观了解STM32的时钟架构。有的新手会忽略这一步直接用默认的HSI内部时钟8MHz也能跑但I2C的时序会比较紧张而且后面如果加定时器、ADC之类的功能时钟不够用就会出各种奇怪问题。所以还是那句话先把时钟树配好后面省心。3.2 USART1配置Y01-3IN1模块通过串口发送数据所以我们需要一个UART外设。在左侧Categories列表里找到Connectivity点开USART1然后在右侧Pinout视图里会看到PA9和PA10被自动分配为USART1_TX和USART1_RX。Mode选择Asynchronous异步模式这样只需要TX、RX两根线就够了。在Parameter Settings里配置参数值Baud Rate9600Word Length8 BitsParityNoneStop Bits1波特率这里先填9600这只是个初始值。如果你之前在串口助手里确认模块是其他波特率这里改成对应的值即可。实操心得我一开始没有用串口助手确认波特率直接按说明书默认9600配好了结果收到的数据全是0xFF或者乱码。后来接USB转TTL一看原来模块实际是4800波特率说明书和实际不一致。这种细节在新出的模块上经常遇到因为厂家可能会在出货前调整固件。所以先接串口助手确认再配CubeMX这个顺序千万别省。3.3 I2C1配置OLED用的是I2C接口。在Categories列表里找到Connectivity点开I2C1Mode选择I2C默认就是I2C模式在Parameter Settings里主要关注两个参数Speed Mode和I2C Speed Frequency。一般我们选Standard Mode100kHz或者Fast Mode400kHz都可以。SSD1306在I2C模式下最高支持到400kHz左右但STM32F103的I2C外设实现有时候在Fast Mode下会有些时序抖动稳妥起见我先选Standard Mode 100kHz等代码跑通了再尝试加快速度。I2C1的引脚会自动分配到PB6SCL和PB7SDA这正好是硬件I2C1的默认引脚不需要手动改。3.4 工程设置与代码生成在Project Manager选项卡里填好Project Name和LocationToolchain选择MDK-ARM也就是Keil或者你习惯用STM32CubeIDE的话选STM32CubeIDE也行。重点来了在Project Manager的Code Generator里勾选Generate peripheral initialization as a pair of .c/.h files per peripheral每个外设单独生成c/h文件和Add necessary library files as reference in the toolchain添加必要的库文件到工程。这样生成的代码会把每个外设的初始化函数独立放结构清晰调试的时候不容易搞混。点击GENERATE CODE生成代码然后用Keil或者CubeIDE打开工程。此时编译一次应该能零错误通过说明环境没问题可以开始往里面填业务逻辑了。4. OLED驱动细节从像素到字符的原理4.1 SSD1306控制器核心机制0.96寸OLED128x64的核心控制器是SSD1306它的显示原理和传统LCD完全不同。简单说屏幕分成128列、64行每个像素点就是一个OLED有机发光二极管通电就亮断电就灭没有背光所以黑色区域是真正不发光对比度极高。SSD1306内部有一块1KB的GDDRAM显存分成8页Page0到Page7每页有128个字节每个字节对应一行中的8个像素点垂直方向。也就是说这64行像素被分成了8个水平条每个条高8像素。你往某个Page的某个字节写入0x55就等于把这个字节对应的8个垂直像素点间隔点亮。这是SSD1306最核心的寻址原理刚开始接触OLED的人需要花点时间理解这种页列的结构。画图的时候大多数驱动库比如比较流行的u8g2或Adafruit_SSD1306底层封装了SSD1306的写显存接口你只需要操作一个128x64的缓冲区数组最后统一刷到屏幕即可。4.2 I2C读写OLED的时序SSD1306在I2C模式下从机地址固定是0x3C如果SA0引脚接地或者0x3DSA0接高。大多数模块SA0默认接地所以地址0x3C如果过手机地址不对可以在代码里把地址改成0x3D试试。用HAL库发送命令的流程是起始信号发送从机地址写位0x3C 1 | 0发送控制字节0x00表示后续是命令0x40表示后续是数据发送命令/数据终止信号在HAL库里这个流程可以封装成一个很小的函数使用HAL_I2C_Mem_Write或直接HAL_I2C_Master_Transmit。下面是用HAL_I2C_Master_Transmit发命令的写法#define OLED_ADDR 0x3C void OLED_WriteCmd(uint8_t cmd) { uint8_t buf[2]; buf[0] 0x00; // 控制字节命令 buf[1] cmd; HAL_I2C_Master_Transmit(hi2c1, OLED_ADDR 1, buf, 2, 100); } void OLED_WriteData(uint8_t data) { uint8_t buf[2]; buf[0] 0x40; // 控制字节数据 buf[1] data; HAL_I2C_Master_Transmit(hi2c1, OLED_ADDR 1, buf, 2, 100); }注意HAL_I2C_Master_Transmit的地址参数需要左移一位因为HAL库内部处理7位地址时要求传入完整8位地址也就是把7位地址左移1位最低位是读写标志而且传入的值需要是设备地址左移1位的结果。容易漏掉的部分漏了的话OLED完全没反应这算是HAL库使用中一个很典型的坑。4.3 初始化命令序列SSD1306上电后需要发一串初始化命令才会开始工作。网上各种代码的初始化序列大同小异关键是几组命令0xAE/0xAF关闭/开启显示0x8D 0x14开启内部电荷泵这是OLED能亮起来的关键0xD5 0x80设置显示时钟分频/振荡频率0xA8 0x3F设置多路复用比128x64屏幕填0x3F0xD3 0x00显示偏移0x40设置显示起始行0xA1设置段重映射左右镜像相关0xC8设置COM扫描方向上下镜像相关0xDA 0x12设置COM引脚硬件配置64行屏幕用0x120x81 0x7F设置对比度0xA4从RAM内容显示正常0xA6设置为正常显示非反显初始化完成后把显示内存全部清除写入0x00再打开显示0xAF屏幕上显示什么完全由你往GDDRAM写的数据决定。小技巧如果你不想重新发明轮子可以用现成的ssd1306.h/ssd1306.c开源驱动Github上很多再把HAL库的I2C发送接口替换成上面那两个函数就行。但我的建议是自己动手把初始化序列写一遍哪怕只写一遍你对这个显示器的理解深度会和直接调用库完全不一样。4.4 显示字符和数字的实现思路要在OLED上显示文字最朴素的办法是建一个字模库点阵字库每个字符用一个数组表示数组里的每一位对应一个像素点1就点亮0就熄灭。常见的字模是8x16或者16x168x16表示字符占8列16行刚好和SSD1306的一页一列对齐处理起来很方便。以显示一个ASCII字符为例先定义一个8x16的字模数组比如字符Aconst uint8_t font8x16[95][16] { // A 0x41 { 0x00,0x00,0x00,0x18,0x3C,0x66,0x66,0x7E, 0x66,0x66,0x66,0x66,0x00,0x00,0x00,0x00 }, // ... 其他字符 };然后在指定位置显示这个字符把每一列的数据写入对应的页即可。更高效的做法是在内存里维护一个128x64的显存缓冲区用一个128x8 1024字节的数组模拟所有显示操作画点、画线、画字符都先往缓冲区里写最后用一个批量刷新函数把整个缓冲区一次性发到SSD1306。这样避免了频繁I2C操作画面也不会闪烁。刷新函数核心就是循环8页每页发128字节数据用HAL_I2C_Mem_Write可以快速搞定甚至支持DMA不过对于本项目显示频率不高阻塞发送就够用了。5. Y01-3IN1数据解析关键是搞懂数据帧5.1 模块工作原理Y01-3IN1内部的三个传感器分工明确温湿度传感器负责测量环境温度和相对湿度空气质量传感器负责检测气体浓度。模块内部自带的MCU会读取这些传感器的数据进行简单的滤波和校准然后按照协议格式通过串口发送出来。这样做的好处是传感器侧的工作全部被封装好了。如果你自己买独立的温湿度传感器和气体传感器就得分别处理I2C地址冲突、上电时序、校准命令麻烦得多。三合一模块把这些问题全部解决了代价是你必须严格按照它的帧格式解析数据。我在市面上见过的Y01-3IN1模块输出帧格式大概是这样帧头长度数据类型温度高字节温度低字节湿度高字节湿度低字节气体高字节气体低字节校验0xFF0x0C0x01..................X不过请注意不同厂家对Y01-3IN1这个词的使用并不完全统一。有的模块输出的是甲醛浓度单位ug/m³有的是TVOC指数有的是CO2当量字节序和校验算法也可能不同。这篇文章里我给出一套通用的解析框架你只要根据自己模块的说明书把对应字节位置和换算系数替换一下就能复用。5.2 解析代码的框架设计先用一个状态机来接收串口数据。状态机是处理不定长数据帧最经典的方案每收到一个字节判断当前状态把帧头、长度、数据、校验一步步凑齐。先说接收时的数据结构#define FRAME_HEADER1 0xFF #define FRAME_HEADER2 0x0C // 按实际帧头调整 #define FRAME_DATA_LEN 9 // 按实际长度调整 uint8_t rx_buffer[32]; uint8_t rx_index 0; uint8_t frame_complete 0; void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { uint8_t byte; if (huart-Instance USART1) { // 从环形缓冲区/变量中读取接收到的字节 byte rx_byte; // rx_byte 是 HAL_UART_Receive_IT 接收到的单字节 // 用状态机处理 static uint8_t state 0; switch(state) { case 0: if (byte FRAME_HEADER1) { rx_buffer[0] byte; rx_index 1; state 1; } break; case 1: rx_buffer[rx_index] byte; if (rx_index FRAME_DATA_LEN 4) { state 2; } break; case 2: // 校验 if (CheckCRC(rx_buffer, FRAME_DATA_LEN 2)) { frame_complete 1; ParseFrame(rx_buffer); } state 0; rx_index 0; break; } // 继续开启下一次接收 HAL_UART_Receive_IT(huart1, rx_byte, 1); } }这里的关键是在main函数里先调用一次HAL_UART_Receive_IT开启单字节中断接收之后每次回调里重新开启。这个模式要记住否则中断触发一次后就不再有新的数据进来了这也是新手最容易犯的错误之一。5.3 温湿度换算帧里的温湿度一般以16位有符号整数传输单位是0.01°C或0.01%RH。也就是说如果收到的温度原值是2500那实际温度是25.00°C。换算很简单int16_t temp_raw (int16_t)((rx_buffer[3] 8) | rx_buffer[4]); int16_t humi_raw (int16_t)((rx_buffer[5] 8) | rx_buffer[6]); float temperature temp_raw * 0.01f; float humidity humi_raw * 0.01f;如果按这个公式算出来的温度明显不对比如几百度的荒谬值那基本可以确定是字节序或者单位不对需要查看你的模块说明书确认。5.4 空气质量数值解析空气质量部分的解析要看模块类型。如果是气体浓度数值比如CO2或TVOC一般也是16位整数可能是原始ADC值也可能已经是线性化的浓度单位。我们假设模块输出的空气质量字段单位是ppm百万分之一浓度那解析方式uint16_t air_quality_raw (uint16_t)((rx_buffer[7] 8) | rx_buffer[8]); float air_quality_ppm air_quality_raw * 1.0f; // 是否要乘系数看手册如果模块输出的是等级1-5级比如1级优、5级差那就要做映射了。我这边建议直接在OLED上同时显示原始数值和一个简单的等级说明比如const char* GetAirLevel(float ppm) { if (ppm 400) return Excellent; if (ppm 1000) return Good; if (ppm 2000) return Moderate; return Poor; }从实用角度讲用户看到空气质量等级 数值比看到一个孤零零的数字直观得多。这个思路在做显示界面的时候用处很大。5.5 校验算法的实现校验是整个解析里最容易踩坑的地方也是排查为什么数据偶尔出问题的关键。不同手册的校验算法五花八门校验和Sum Check把帧的所有字节加起来取低8位和帧尾的校验字节比对。CRC8常见的多项式是0x31和MAXIM/DS18B20一样的算法。XOR校验把所有字节异或得到的结果作为校验字节。最简单的实现是求和校验uint8_t CheckSum(uint8_t *data, uint8_t len) { uint8_t sum 0; for (uint8_t i 0; i len; i) { sum data[i]; } return sum; }然后和接收到的校验字节比较相等则说明这一帧数据没有被破坏。校验不通过时我建议直接把这一帧丢弃不要用半截数据更新显示否则屏幕上会出现跳动明显的错误值。实操心得我在调试的时候遇到过一种情况模块刚上电的几秒内输出的是不定长的校准数据帧格式和正常数据帧不一样。这时候如果用固定的帧解析逻辑去处理会一直卡在校验错误。解决办法很简单软件里做一个超时或者帧计数逻辑连续失败多次后重新同步帧头。也就是在状态机里如果超过一定时间没有收到预期数据就强制回到等待帧头的初始状态。6. 界面设计与主循环逻辑把数据用起来6.1 数据流打通后的总体结构当OLED驱动和数据解析都完成后把它们串联起来。主循环的逻辑很清晰int main(void) { // HAL初始化、外设初始化、OLED初始化 OLED_Init(); OLED_Clear(); OLED_ShowString(0, 0, System Init..., Font_8x16); // 开启UART中断接收 HAL_UART_Receive_IT(huart1, rx_byte, 1); while (1) { if (frame_complete) { frame_complete 0; OLED_UpdateDisplay(); // 刷新整屏 } HAL_Delay(10); } }实际上我建议把显示刷新和控制逻辑分离。数据解析在UART中断回调里完成显示刷新在主循环里做两者通过全局变量或者结构体传递数据。由于解析速度很快一帧数据几毫秒内就能处理完中断里的工作量很小不会影响系统实时性。6.2 OLED界面布局实操128x64的屏幕能显示的信息有限但合理安排布局还是能装下不少内容。我的排列方式第一行标题Air Quality Monitor用较小字号。第二行温度显示格式Temp: 25.5 C用8x16字体。第三行湿度显示格式Humi: 45.2 %。第四行空气质量显示格式Air: Good或Air: 356 ppm。如果要显示中文字符需要准备16x16的中文字模这会让字库文件变得很大显示多少字就要拷多少字模。如果你不追求中文字体ASCII字符配合缩写完全够用。OLED的显示坐标xy和SSD1306的页结构有关8x16字体的每个字符占8列宽、16行高所以x坐标按8的倍数排y坐标按16的倍数排。我常用的一个简化方法是写一个OLED_SetPos(x, y)函数里面把y转换成页地址y/8再按页码设置起始列地址这样画字符的时候就非常直观。6.3 刷新策略与防闪烁OLED刷屏如果每次只改一个数字也整屏刷新会显得很闪。虽然SSD1306本身没有余晖效应但整屏重写时人眼能感受到轻微闪烁尤其在显示大量文本时比较明显。想避免闪烁有两个办法局部区域更新只把一个数值所在的8x16区域重新发送不整屏刷。屏幕缓冲分块维护一个脏标记某区域的值变了才去刷新对应区域。对于这个项目数据1秒才更新一次整屏刷新其实不怎么闪。但如果你要加快刷新频率建议用脏标记法。我实现的时候就是在每个数据更新后调用一次区域刷新函数参数是坐标和宽高内部只发送对应页和列的数据这样比全屏刷新快4倍左右。6.4 数据的平滑处理传感器原始数据有时候会跳变比如人从传感器旁边走过温度瞬间波动1°C空气质量数值起伏更大。如果OLED上的数字跟着剧烈跳动观感很差。解决办法是滑动平均滤波#define FILTER_SIZE 10 float temp_history[FILTER_SIZE]; uint8_t temp_index 0; float temp_sum 0.0f; float FilterTemperature(float new_temp) { temp_sum - temp_history[temp_index]; temp_history[temp_index] new_temp; temp_sum new_temp; temp_index (temp_index 1) % FILTER_SIZE; return temp_sum / FILTER_SIZE; }滑动平均的优点是实现简单、内存占用小而且能有效滤掉高频噪声。代价是响应速度变慢大概是滤波窗口长度乘以采样周期的滞后。对于室内空气质量监测这种对实时性要求不高的场景10次平均10秒完全能接受。7. 调试实录我遇到的四个卡壳问题7.1 OLED不亮或者显示乱码这个现象大概是这种项目的头号问题原因是多样的。先看电源用万用表量OLED的VCC引脚是不是3.3V如果GND没接好模块可能半亮不亮。再看接线确认SDA接PB7SCL接PB6或者你在CubeMX里配的其他I2C引脚不要把SDA和SCL接反。最后看代码确认初始化时调用了OLED_Init而且I2C地址没错。我吃过的亏是把SSD1306当成0x3D去驱动屏幕上完全无反应改回0x3C后立刻正常。如果显示乱码那多半是初始化序列里某个参数不对。比如设置COM扫描方向0xC8和段重映射0xA1这两条反了会出现上下镜像或左右镜像看起来像乱码但其实数据是对的改一下命令参数就能恢复。7.2 UART收到全0xFF或者全0x00全0xFF通常说明引脚悬空或者接线错误串口读到了空闲电平。检查TX/RX是不是接反了确认模块的TX确实连到了STM32的RX。全0x00则可能是模块没正常工作没有数据输出检查模块的供电和使能引脚。如果串口助手能收到正常数据但STM32收不到那就要检查GPIO复用配置是否正确。在CubeMX里配置好USART1后PA9/PA10的GPIO模式会被自动设置成复用推挽/复用开漏不需要手动干预。如果你自己手写了GPIO初始化代码覆盖了CubeMX的设置就会导致UART失效。7.3 波特率不对导致乱码这是我前面反复强调过的问题。乱码的典型特征是能看到有规律的波形但解析出来全是乱七八爪的值。用逻辑分析仪或者串口助手确认模块的实际波特率然后在CubeMX里改过来就行。有的模块在固件里可以配置比如发送特定命令切换波特率这也要看说明书。7.4 HAL_UART_Receive_IT只收到一帧就停了这就是前面提到的中断只开启一次的问题。HAL_UART_Receive_IT是一次性的接收完成回调后不会自动开启下一次接收。如果你不在回调里重新调用一次串口就再也收不到数据了。这是HAL库小白一定会踩的坑解决办法就是在HAL_UART_RxCpltCallback末尾再加一行HAL_UART_Receive_IT。常见问题排查方向解决方法OLED完全无显示供电、接线、I2C地址万用表量VCC/GND确认SDA/SCL检查0x3C/0x3DOLED乱码/镜像初始化命令序列调整0xA1段重映射和0xC8扫描方向UART全0xFF接线错误或引脚悬空检查TX/RX是否接反确认模块供电UART乱码波特率不匹配用串口助手确认实际波特率并修改CubeMX配置数据帧校验失败帧格式不匹配按说明书逐字节核对帧头和长度调整解析代码数值跳变严重传感器噪声加入滑动平均滤波8. 这个项目还能怎么扩展把STM32、Y01-3IN1和OLED这三样东西的基本用法搞清楚之后其实可以做很多有意思的延展一是加数据存储。用STM32内部Flash或者外接SPI Flash把长时间采集的温湿度和空气质量数据存下来按天/周生成趋势。加上一个RTC时钟芯片或者用STM32内部的RTC就能在OLED上显示时间戳成为一个小型环境记录仪。二是加联网功能。接一个ESP8266或者ESP32模块把数据通过WiFi上传到云平台比如MQTT服务器或者物联网平台这样手机APP上就能实时查看家里的空气质量。如果不想折腾云服务也可以用蓝牙模块HC-05/HC-08和手机串口助手通信几行代码就能实现。三是加报警功能。当空气质量数值超过设定的阈值时驱动蜂鸣器响、LED闪烁或者通过继电器控制新风系统/排风扇自动启动。这类联动逻辑很适合放在智能家居项目里。四是换显示屏。如果你觉得128x64太小可以直接换1.3寸或者2.4寸的TFT屏幕ST7735/ILI9341I2C不够用就用SPI显示的界面内容可以丰富很多。OLED的驱动代码主体思路不变显示层做一次适配即可。如果在实操中还是有问题我建议你把模块的说明书尤其是串口协议部分、接线照片、串口助手截屏整理好一起排查。大多数情况下问题都出在线没接对和波特率没对上这两类逐个排除一定能跑通。