1. 项目概述：这个KLL到底是什么
1.1 项目起源与命名
先说清楚KLL是什么。它是我花了两个多月整理出来的一套室内空气质量检测开源项目，软硬件资料全部放出来了，包含STM32固件、传感器驱动、PCB工程、3D外壳模型和配套的上位机脚本。KLL这个名字是我自己起的，全称叫Keep Life Livable，意思是让居住环境保持“适合生活”的状态。我本来想起个正经点的英文名，但缩写念多了反而顺口，就一直沿用下来了。
做这个项目的初衷其实有点私人。家里重新装修之后，我总觉得房间里有股说不清的味道，但你说它有毒有害吧，鼻子又给不出一个确切的答案。市面上空气检测仪要么贵得离谱，要么只能测单个指标，数据还不透明，想导出做分析基本没门。我本身是做嵌入式的，就想着干脆自己搭一套：既能测PM2.5、TVOC、二氧化碳和温湿度，又能把数据存下来看趋势，还能通过MQTT上报到Home Assistant，这样人在外面也能看到家里空气情况。
项目整体跑下来效果很好，现在已经连续稳定运行了几个月。最典型的场景是，我在厨房做饭的时候，TVOC数值会明显飙升，PM2.5也会跟着涨一波；而晚上关窗睡觉，二氧化碳浓度经常能到1500ppm以上，这时候KLL就会亮起橙色指示灯提醒我开窗通风。这个项目对两类人特别有用：一类是刚开始接触STM32和FreeRTOS的嵌入式学习者，因为代码结构相对清晰，传感器驱动也不复杂，很适合做入门进阶；另一类是像我这样想做一个真正能长期运行的家用设备、而不是只要一个玩具Demo的人。
1.2 项目的功能范围与整体剖面
这套系统分成四个层次：数据采集层、主控计算层、交互显示层、联网上报层。数据采集层用了三个传感器，分别负责颗粒物、气体和温湿度；主控层用STM32F401CCU6单片机，跑FreeRTOS操作系统，负责把所有传感器数据读回来后做滤波、校准和空气质量指数计算；交互层是一块1.3寸的OLED屏幕加两个实体按键，可以切换显示页面；联网上报层则通过串口连接一个ESP8266模块，走MQTT协议把数据推给局域网或云端的服务。
固件源码按模块划分，hal目录放的是各传感器和硬件的底层驱动，app目录放的是业务逻辑，比如空气质量指数计算、页面菜单管理、MQTT消息拼接等。我会在后面章节里逐个拆解这些模块的设计思路和踩坑记录，尽量把“为什么这样做”讲清楚，而不是直接丢一份代码让你自己看。
2. 核心硬件架构设计
2.1 主控选型：为什么选STM32F401CCU6而不是F103
这可能是很多人拿到项目后问的第一个问题。KLL的主控芯片选的是STM32F401CCU6，而不是烂大街的STM32F103C8T6，也不是更贵的STM32F429系列。我的理由很现实：F401是Cortex-M4内核，主频最高84MHz，带硬件浮点单元，做传感器数据的实时滤波和线性插值计算比F103这种M3内核舒服很多，特别是做空气质量指数这种分段线性函数时，浮点运算要高效不少。
从成本角度看，F401CCU6的散片价格已经降到和F103非常接近，Flash有256KB，SRAM有64KB，对于跑FreeRTOS加若干业务任务的场景完全够用。我最早用F103C8T6做原型，Flash其实也能放下，但RAM比较紧张，一旦开了几个任务加几个队列之后，剩余堆空间就捉襟见肘了。如果你手里已经有F103开发板，也不是不能跑，只需要把启动文件和链接脚本换成对应的型号，代码层面改动量不大，但我不建议用于长期运行的版本，因为算力和内存余量都不够宽裕。
供电方面，KLL采用的是5V DC输入，板载AMS1117-3.3把电压降到3.3V给单片机、屏幕和气体传感器供电。颗粒物传感器PMS7003比较特殊，它的风扇需要5V供电，所以接在输入侧。整机功耗大概在0.4W左右，如果换成不带风扇的颗粒物传感器，可以再降一半，但目前的风扇方案换来的是更稳定的采样气流，我认为值得。
2.2 传感器选型与对比：不是越多越好
选传感器是这类型项目里最容易犯迷糊的地方。我见过有人一口气上了七八个传感器，结果数据打架、驱动冲突、接口不够用，最后只能砍掉一半。KLL最终选了三颗核心传感器加一个可选的环境光传感器，每一颗都是经过实际对比才定下来的。
第一颗是盛思锐的SGP30，用来测TVOC和eCO2。这是一颗基于金属氧化物原理的气体传感器，I2C接口，输出的是经过内部算法估算的TVOC浓度和二氧化碳当量。为什么选它？因为它在同类MEMS气体传感器里功耗低、体积小、长期稳定性相对可接受，而且驱动简单，不需要复杂的模拟电路。需要注意，SGP30输出的是“等效估算值”，不是专业级红外二氧化碳传感器的精度，但用在室内环境趋势监测上完全够用。
第二颗是SHT30温湿度传感器，同样走I2C接口。温度和湿度数据不仅本身有展示价值，更重要的是要给SGP30做湿度补偿。SGP30的算法手册里明确写了，湿度变化会影响气体传感器读数，官方建议在实际运行中定期把湿度数据写入传感器，这样eCO2和TVOC的估算才会更准确。我在项目初期就跳过了这一步，结果室内湿度从40%升到70%的时候，TVOC读数凭空涨了三分之一，加完补偿之后波动立即变平稳了。
第三颗是攀藤PMS7003颗粒物传感器，串口输出，能同时给PM1.0、PM2.5和PM10三组数据。它内部有一个微型风扇吸入空气，通过激光散射原理测颗粒物浓度。这颗传感器唯一的缺点是必须5V供电、体积略大，但数据稳定性和一致性在 DIY 项目里算很不错的。如果你预算更低，也可以换成PMS5003，代码兼容，只是体积和精度略有差异。
| 传感器 | 测量对象 | 接口 | 供电 | 典型成本 | 精度定位 |
|---|---|---|---|---|---|
| SGP30 | TVOC / eCO2 | I2C | 3.3V | 中 | 趋势级估算 |
| SHT30 | 温度 / 湿度 | I2C | 3.3V | 低 | 消费级 |
| PMS7003 | PM1.0 / PM2.5 / PM10 | UART | 5V | 中 | 消费级激光散射 |
2.3 供电、总线和结构设计细节
选完芯片和传感器，硬件部分还有很多容易被忽略的细节。KLL的PCB是我画的四层板，但如果你用面包板或洞洞板搭电路，也完全可以跑通，只是稳定性要差一些。这里分享三个我踩过坑的地方。
第一个坑是I2C总线的上拉电阻。STM32的I2C引脚是开漏输出，必须在总线上接上拉电阻才能工作。很多开发板已经自带了上拉电阻，但当你外接多个I2C设备、又用了较长杜邦线时，总线电容变大，会导致信号上升沿变慢，从而出现随机通信错误。KLL的板载设计选的是4.7kΩ上拉，走线控制在10cm以内，实测在多设备场景下很稳定。如果你用杜邦线接线，建议把上拉电阻换成2.2kΩ，能有效改善信号质量。
第二个坑是PMS7003的排线。这颗传感器自带的连接器是1.0mm间距的卧式端子，打样PCB时很容易弄错封装。我第一次画PCB就买成了1.25mm间距的连接器，结果只能飞线解决。建议买传感器之前先确认好排线规格，或者干脆选那种已经焊接好端子转接板的模块，省得折腾。
第三个坑是气体传感器的放置位置。SGP30这类金属氧化物传感器的敏感元件会被气流干扰，所以不要把它直接放在风扇出风口附近，也不要紧贴着PCB上的电源芯片。KLL的结构设计里，SGP30放在PCB边缘，用一个小的3D打印风道把气流引导到敏感元件周围，确保读数稳定。
3. 传感器数据采集：驱动与实操
3.1 I2C传感器读取：SGP30和SHT30
下面进入实际代码环节。KLL的底层驱动基于STM32的HAL库，因为HAL库的API清晰、代码可读性好，适合开源项目让更多人看。如果你习惯用标准外设库或LL库，逻辑是一样的。
先看SGP30的读取流程。这颗芯片的I2C操作有点特殊，它不是通过寄存器地址直接读数据的，而是要先发送一个“测量命令”，等一段时间后再读出结果。例如读取TVOC和eCO2的命令是0x2003，发送命令后需要等待约12ms，然后再以I2C读操作连续读6个字节，前两个字节是CO2，中间两个字节是TVOC，最后两个字节是CRC校验。这里的关键是等待时间绝对不能省略，否则读出来的数据是上一次的残留值。
我封装了一个简单的读取函数，核心逻辑长这样：
#define SGP30_I2C_ADDR (0x58 << 1) #define SGP30_CMD_MEASURE 0x2003 static HAL_StatusTypeDef sgp30_read_measure(uint16_t *co2, uint16_t *tvoc) { uint8_t cmd[2] = {0x20, 0x03}; uint8_t buf[6]; HAL_StatusTypeDef status; status = HAL_I2C_Master_Transmit(&hi2c1, SGP30_I2C_ADDR, cmd, 2, 100); if (status != HAL_OK) return status; HAL_Delay(15); status = HAL_I2C_Master_Receive(&hi2c1, SGP30_I2C_ADDR, buf, 6, 100); if (status != HAL_OK) return status; *co2 = (uint16_t)((buf[0] << 8) | buf[1]); *tvoc = (uint16_t)((buf[2] << 8) | buf[3]); return HAL_OK; }注意这里我没有做CRC校验，原因是SGP30在室内短距离通信场景下出现误码的概率很低，而且即使偶尔读错一个字节，后续的滑动平均滤波也能把毛刺消化掉。但如果你追求严谨，手册里的CRC算法是CRC-8，多项式是0x31，网上的参考实现很多，加上去也不困难。
SHT30的读取更直接，它支持标准的寄存器读。发送0x2C06命令开启高重复性测量，等约8ms后，连续读取6个字节，前两个是温度，后两个是湿度，同样带CRC。温度要除以175.0再乘以上限值，再减去45，公式还涉及0xFFFF满量程缩放，我在代码里已经写清楚了，可以对照手册看。
3.2 串口解析PMS7003颗粒物数据
PMS7003的数据格式比较规整，每秒钟向串口发送一个32字节的数据帧，帧头固定为0x42 0x4D，第2、3字节表示帧长度，后面是按顺序排列的PM1.0、PM2.5、PM10等字段，帧尾是两个字节的校验和，等于前面所有字节之和的低16位。
我在串口驱动里做了一个简单的状态机来解析这个帧结构，核心是把数据接收放到中断回调里，一个个字节喂给状态机。状态机分成四个状态：等待帧头1、等待帧头2、接收数据体、校验收尾。这样做的好处是不需要开一个大的DMA缓冲区，内存占用很小，也天然支持掉帧后的自动重新同步。
解析PM2.5的代码如下：
typedef enum { PMS_STATE_WAIT_H1, PMS_STATE_WAIT_H2, PMS_STATE_WAIT_LEN, PMS_STATE_WAIT_DATA, PMS_STATE_WAIT_SUM_H, PMS_STATE_WAIT_SUM_L } pms_state_t; static pms_state_t state = PMS_STATE_WAIT_H1; static uint8_t pms_buf[30]; static uint8_t pms_idx = 0; static uint16_t pms_sum = 0; void pms_parse_byte(uint8_t byte) { switch (state) { case PMS_STATE_WAIT_H1: if (byte == 0x42) state = PMS_STATE_WAIT_H2; break; case PMS_STATE_WAIT_H2: if (byte == 0x4D) { state = PMS_STATE_WAIT_LEN; pms_sum = 0x42 + 0x4D; } else state = PMS_STATE_WAIT_H1; break; case PMS_STATE_WAIT_LEN: /* 假设只有一个标准帧，长度固定为0x001C */ if (byte == 0x00 || byte == 0x1C) { state = PMS_STATE_WAIT_DATA; pms_idx = 0; } else state = PMS_STATE_WAIT_H1; pms_sum += byte; break; case PMS_STATE_WAIT_DATA: pms_buf[pms_idx++] = byte; pms_sum += byte; if (pms_idx >= 30) state = PMS_STATE_WAIT_SUM_H; break; case PMS_STATE_WAIT_SUM_H: /* 这里假设只是收校验值，不继续累加 */ state = PMS_STATE_WAIT_SUM_L; break; default: state = PMS_STATE_WAIT_H1; break; } }完整项目里我做了校验和的判断，校验通过才更新全局浓度变量，校验失败则丢弃整帧，等待下一帧重新同步。帧率是每秒一帧，所以即使偶尔丢一帧，也不会影响整体数据连续性。
3.3 传感器校准与数据平滑：几个必须处理的细节
传感器数据直接读出来就能用吗？能，但不准。这里分享三个我在项目中实际解决的校准问题。
第一个是SGP30的基线问题。SGP30传感器前面提到过，是金属氧化物原理，它有一个“基线”概念：在没有目标气体的标准环境下，传感器输出TVOC应该近似为0ppb；但在实际环境里，基线会随温度和湿度漂移，长期通电后尤其明显。SGP30内置了一个自动基线补偿算法，但它要求传感器连续运行一定时间才能完成学习，如果期间断电重启，基线会丢失。KLL的处理方式是每10分钟把SGP30的当前基线值写入Flash，开机后先尝试从Flash恢复基线，然后再开始正常采样。这个功能通过SGP30的0x2115命令读取基线、0x201E命令写入基线来实现，代码量不大，但对长期稳定性帮助很大。
第二个是PMS7003的启动稳定时间。这颗传感器的风扇需要一点时间才能建立稳定气流，激光器也需要热稳定。实测下来，冷启动后的前30秒数据波动较大，读数可能会明显偏高。KLL的做法是在开机后丢弃前5帧数据，然后从第6帧开始进入正规的滑动平均队列。如果你的应用对实时性要求不高，甚至可以等1分钟再开始显示，体验会好很多。
第三个是数据平滑。原始传感器的读数总会有随机噪声，特别是TVOC和PM2.5这种受气流影响的物理量，瞬时值可能跳来跳去。我在KLL里实现了一个窗口长度为10的滑动平均滤波器：
#define SMOOTH_WINDOW 10 static float ring_buf[SMOOTH_WINDOW]; static uint8_t ring_index = 0; static uint8_t ring_count = 0; float smooth_add(float new_value) { float sum = 0, avg = 0; ring_buf[ring_index] = new_value; ring_index = (ring_index + 1) % SMOOTH_WINDOW; if (ring_count < SMOOTH_WINDOW) ring_count++; for (uint8_t i = 0; i < ring_count; i++) { sum += ring_buf[i]; } avg = sum / ring_count; return avg; }这个滤波器在平滑噪声的同时，还能保证响应速度不至于太慢，窗口10对TVOC这种变化较缓慢的参数来说刚刚好。如果窗口取50，虽然曲线更光滑，但厨房开油烟机后TVOC要很久才能反映出来，实用性会大打折扣。
4. 核心算法：空气质量指数的计算
4.1 为什么不能直接拿传感器原始数据告警
如果你只是把TVOC、CO2、PM2.5几个数字轮流显示在屏幕上，其实不需要什么复杂算法。但如果要做一个能告警、能分级、能被普通人理解的设备，就必须把这些物理量映射到统一的评价体系里。这里我用的是类似中国环境空气质量指数AQI的分段线性映射方式。
AQI的基本思路是：每一种污染物都有一个“分指数”，称为IAQI，然后取所有污染物分指数中的最大值作为最终的空气质量指数。每种污染物的浓度范围被划分成若干区间，每个区间对应一个IAQI范围，比如IAQI 0对应PM2.5浓度0~35μg/m³，IAQI 50对应35~75μg/m³。浓度落在某个区间内时，IAQI采用线性插值计算。
用一个生活化的类比来解释：这就像考试评分，每门课都要先换算成百分制，再取最低分，不对，这里应该是取最差的那门课作为总评。如果PM2.5这门课只考了40分，但TVOC这门课考了90分，那空气质量总评就是90分，因为它最大的污染因子是TVOC。
4.2 用C语言实现IAQI计算
KLL的代码里实际实现了两个污染物的IAQI计算：PM2.5分指数和CO2分指数。这里以PM2.5为例，先定义分段区间表：
typedef struct { float conc_low; float conc_high; int iaqi_low; int iaqi_high; } iaqi_bp_t; static const iaqi_bp_t pm25_bp[] = { { 0.0, 35.0, 0, 50}, { 35.0, 75.0, 50, 100}, { 75.0, 115.0, 100, 150}, {115.0, 150.0, 150, 200}, {150.0, 250.0, 200, 300}, {250.0, 350.0, 300, 400}, {350.0, 500.0, 400, 500}, };线性插值公式参照标准定义：
int calc_iaqi_pm25(float conc) { uint8_t i; for (i = 0; i < sizeof(pm25_bp)/sizeof(pm25_bp[0]); i++) { if (conc >= pm25_bp[i].conc_low && conc < pm25_bp[i].conc_high) { float ratio = (conc - pm25_bp[i].conc_low) / (pm25_bp[i].conc_high - pm25_bp[i].conc_low); return pm25_bp[i].iaqi_low + (int)(ratio * (pm25_bp[i].iaqi_high - pm25_bp[i].iaqi_low)); } } if (conc >= pm25_bp[6].conc_high) return 500; return 0; }同样方式可以扩展CO2、TVOC等污染物。需要注意的是，传感器给出的eCO2估算值不能完全等同真实环境的二氧化碳标准浓度，所以我在KLL里把CO2的IAQI计算降级为“参考值”而非“标准值”，告警逻辑也以PM2.5和TVOC为主，避免过度依赖单一估算源导致误报。
4.3 告警阈值与界面提示设计
IAQI算出来后，下一步是把它映射成用户能感知的提示。KLL把空气质量分成四个等级：优、良、轻度污染、重度污染。界面显示对应等级文字，同时用RGB LED做颜色提示，绿色为优，黄色为良，橙色为轻度污染，红色为重度污染。同时在重度污染时启动蜂鸣器，频率2Hz，提示强度比较有存在感但又不至于扰民。
这里有一个实际经验：不要把告警阈值写死在代码里。KLL把阈值放到一个独立的配置文件里，用宏定义集中管理，后续想调阈值只需要改一个头文件。实际使用中发现，冬天开暖气之后室内PM2.5经常会到60~70左右，如果阈值设成35就疯狂报警，用户会直接关掉设备。后来我把“优”的阈值放宽到45，减少了大量无效提醒。
5. 嵌入式软件架构：任务划分与数据流
5.1 FreeRTOS任务规划
KLL的固件跑的是FreeRTOS，核心原因在于系统里有多个周期不同、时间要求不同的任务：传感器采集需要周期性执行，屏幕刷新需要及时，WiFi通信任务可能因为网络阻塞而长时间卡住。如果用裸机前后台轮询，一个任务阻塞很可能会导致传感器读取失败；用RTOS则可以把这些相互独立的逻辑分开，各自维护自己的调度周期。
任务规划如下：
| 任务名称 | 周期 / 触发方式 | 优先级 | 主要职责 |
|---|---|---|---|
| sensor_task | 每2秒唤醒 | 中 | 读取SGP30、SHT30、PMS7003，写入数据池 |
| calc_task | 每10秒唤醒 | 低 | 滑动平均、IAQI计算、告警状态判断 |
| display_task | 每500毫秒唤醒 | 中 | 刷新OLED屏幕，处理按键事件 |
| network_task | 事件触发/每30秒 | 低 | 组包发布MQTT消息，断线自动重连 |
这里的关键设计是传感器采集和计算分离。采集任务只负责拿到原始数据并放进一个全局数据池，计算任务再基于这些数据进行平滑和指数换算。这样即使网络通信卡顿，采集和显示也不会受到影响。我在最初版本里把采集和计算放在同一个任务里，结果网络任务一次15秒的超时阻塞，系统整体数据就出现了明显延迟，改成分离架构之后问题消失。
5.2 关键代码片段：任务创建与任务间通信
任务创建使用标准的xTaskCreate接口，每个任务分配独立的栈空间。传感器任务和计算任务之间没有用队列传大量数据，而是直接读写一个带互斥锁保护的全局结构体。原因很简单：数据量小、更新频率低，用队列反而增加内存开销和拷贝成本。
typedef struct { float temperature; float humidity; uint16_t co2; uint16_t tvoc; uint16_t pm25; uint16_t pm10; } air_data_t; static air_data_t g_air_data; static SemaphoreHandle_t g_data_mutex; void sensor_task(void *arg) { uint16_t co2, tvoc; uint16_t pm25, pm10; float temp, humi; for (;;) { if (sgp30_read_measure(&co2, &tvoc) == HAL_OK && sht30_read_measure(&temp, &humi) == HAL_OK) { pms_read(&pm25, &pm10); osMutexAcquire(g_data_mutex, osWaitForever); g_air_data.co2 = co2; g_air_data.tvoc = tvoc; g_air_data.pm25 = pm25; g_air_data.pm10 = pm10; g_air_data.temperature = temp; g_air_data.humidity = humi; osMutexRelease(g_data_mutex); } vTaskDelay(pdMS_TO_TICKS(2000)); } }如果你打开KLL的源码，会发现实际代码比这段更“健壮”，包括传感器通信失败时的重试计数、数据超出合理范围时的异常标记等，但核心结构就是这样：一个循环，一次采样，写入共享区，然后进入睡眠等待下一个周期。
5.3 长期运行的稳定性设计
作为要长期摆在室内的设备，稳定性比功能数量更重要。KLL做了三层防护。第一层是硬件看门狗。STM32的内部独立看门狗IWDG设置为约4秒超时，主循环里定期喂狗，一旦固件卡死或死循环，看门狗会自动复位整个系统，避免设备一夜之间变成一块黑砖。
第二层是任务看门狗。FreeRTOS的软件看门狗通过一个高优先级监控任务实现，它检查系统中几个关键任务的最近一次运行时间戳，如果某个任务超过设定的超时时间没有更新，监控任务就主动重启系统。这个设计在排查网络任务卡死时非常有效。
第三层是参数持久化。除了前面提到的SGP30基线，KLL还保存了设备ID、WiFi配置等参数到Flash。使用STM32内部Flash模拟EEPROM，每类参数写一个独立的存储页，避免频繁擦写导致磨损。实测下来，这套方案的每日平均擦写次数不超过3次，Flash使用寿命可以覆盖数年。
6. 联网与数据可视化
6.1 本机显示：OLED屏幕与菜单状态机
KLL使用了一块1.3寸的SSD1306 OLED屏幕，分辨率128x64。OLED的优点是功耗低、可视角度大、在暗光环境下效果好；缺点是尺寸小，一屏显示不下所有数据，所以需要一个简单的菜单系统来切换页面。
菜单系统我用的是一个轻量级状态机，状态枚举包括PAGE_MAIN、PAGE_TEMP_HUMI、PAGE_PM、PAGE_GAS、PAGE_STATUS几个状态。按键事件驱动状态切换，每个状态对应一个页面绘制函数：
typedef void (*page_draw_fn)(void); static const page_draw_fn page_table[] = { draw_page_main, draw_page_temp_humi, draw_page_pm, draw_page_gas, draw_page_status, }; static uint8_t current_page = 0; void ui_on_key_next(void) { current_page = (current_page + 1) % (sizeof(page_table)/sizeof(page_table[0])); display_clear(); } void ui_task_refresh(void) { page_table[current_page](); }这样设计的好处是以后要增加新页面，只需要写一个绘制函数并把它加进数组，完全不需要改动状态切换逻辑，扩展性很好。
6.2 用MQTT把数据发到云或Home Assistant
联网层选用ESP8266模块，通过串口和STM32通信。固件端不做WiFi协议栈，只是通过AT指令操控ESP8266。这种方案的优点是主控代码简单、稳定，缺点是需要两颗芯片配合，功耗高一些。但对家用固定设备来说，功耗不是主要矛盾。
ESP8266连接WiFi时，我用的是主动重连策略。启动后，STM32发送AT+CWMODE=1设置Station模式，AT+CWJAP连接路由器，然后AT+CIPSTART建立TCP连接，再通过MQTT协议发布消息。为了避免代码里嵌入MQTT客户端库，KLL直接用MQTT的底层报文格式，自己组包，把payload发送到指定的broker。
数据打包格式是JSON，示例：
{ "device": "kll-01", "temp": 26.4, "humi": 58.2, "pm25": 12, "pm10": 18, "co2": 820, "tvoc": 156, "aqi": 35, "level": "good" }在STM32上拼JSON用了cJSON库，这个库非常小，适合嵌入式使用。发布频率设为每30秒一次，避免broker和ESP8266压力过大。如果网络断了，网络任务会进入重连状态，每5秒尝试重连一次，但不会影响本地采集和显示。
如果你不想搭MQTT broker，也可以直接把数据通过串口发到上位机，KLL仓库里包含一个Python脚本，使用pyserial读串口、用matplotlib绘制实时曲线，适合临时调试或演示场景。
7. 开源项目如何组织：从代码到协作
7.1 一个嵌入式开源项目应该有什么
很多人以为开源就是把代码丢到GitHub上，其实差的远。KLL从个人项目转成开源项目的过程中，我花了将近三成的时间整理仓库结构、文档、脚本和示例。一个合格的嵌入式开源项目至少应该包含这些内容。
仓库目录结构我按功能拆分：
KLL/ ├── docs/ # 设计文档 │ ├── hardware.md # 硬件设计说明 │ ├── build.md # 固件编译烧录指南 │ └── protocol.md # 传感器协议和MQTT协议 ├── firmware/ # 固件源码 │ ├── Core/ # STM32CubeMX生成文件 │ ├── Drivers/ # HAL库 │ └── App/ # 业务逻辑代码 ├── hardware/ │ ├── schematic/ # 原理图PDF与工程文件 │ ├── pcb/ # PCB工程文件 │ └── bom/ # 物料清单 ├── script/ # 上位机工具脚本 ├── LICENSE # 开源协议 └── README.mdREADME不是摆设，它需要回答五个问题：这个项目是什么、能做什么、硬件怎么准备、固件怎么编译、常见问题去哪里看。我在README里放了设备的实物照片、功能演示动图和一键编译的命令说明，让用户不用翻代码也能快速上手。
7.2 CI、Issue模板与PR流程
嵌入式项目也可以上持续集成。KLL的仓库里放了一个GitHub Actions的配置文件，主要做三件事：用arm-none-eabi-gcc编译固件、检查有无编译警告、构建CMake模拟测试。虽然嵌入式代码最终要烧到芯片上才能验证，但至少能保证代码每次提交后不会把编译弄挂。这对多人协作很有价值，因为我之前遇到过贡献者推了一版代码，结果HAL库版本不一致导致编译失败的情况。
Issue模板我用的是GitHub自带的多模板功能，给bug报告、硬件求助、功能建议各建了一个模板，每个模板都有固定的填写项，比如硬件版本、固件版本、日志内容、复现步骤。有了模板之后，问题信息明显完整了，不再需要反反复复追问对方用的什么板子、什么传感器。
PR流程方面，我在CONTRIBUTING.md里写明了三条硬性规则：通过CI检查、遵循代码风格、必须有明确的功能说明。嵌入式项目还要额外注意：不要提交自己的CubeMX工程配置文件，因为不同版本的CubeMX会互相覆盖，导致无谓的合并冲突。
7.3 硬件也要开源：原理图、BOM和Gerber
很多嵌入式开源项目只开源了代码，硬件资料散落在博客或论坛附件里，这对想要自己打样PCB的用户非常不友好。KLL把硬件部分完整放了出来，原理图和PCB用的是KiCad工程，同时导出了PDF版的原理图和Gerber文件。Gerber是最重要的，因为只要把Gerber压缩包上传到任意PCB工厂，就能直接打样出板。
BOM表也需要认真整理。我最初只给了“电阻电容若干”这种模糊描述，被好几个网友私下问得焦头烂额。后来把每个元件的位号、容值/阻值、封装、推荐型号、数量、参考购买链接全部列清楚，大家照着买就行。实际经验是，BOM里最容易出错的是TVS二极管、ESD防护件这类小元件，封装很容易买错，所以我在BOM里额外加了一列“容易买错”的备注，比如0603和0805的区别，尽量帮后来人避坑。
8. 常见问题与排查技巧实录
8.1 快速排障速查表
我把KLL在过去几个月里收到的反馈和自己遇到的问题整理成了排障表，涵盖大多数使用场景。
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| I2C读取全部失败 | 地址错误 / 上拉不足 / 接线接触不良 | 先扫描总线地址，确认0x58和0x44存在 |
| 颗粒物数据始终为0 | PMS7003供电不足 / 串口接线反了 | 用万用表量5V带载电压，检查TX/RX是否交叉 |
| TVOC读数持续偏高不下降 | SGP30基线未建立 / 传感器老化 | 恢复出厂基线，连续开机24小时 |
| OLED花屏或闪屏 | 供电纹波大 / SPI/I2C速率过高 | 在电源两端并100uF电容，降低I2C频率到100kHz |
| ESP8266频繁掉线 | 路由器AP隔离 / 供电不足 | 检查调试串口日志，给ESP8266单独加100uF电容 |
| 数据跳变剧烈 | 平滑窗口太短 / 空气流动突变 | 适当增大滑动平均窗口，检查传感器附近有无热源 |
| 电源芯片发热严重 | 输入电压过高 / 输出电压短路 | 量3.3V对地阻抗，确认负载电流是否超规格 |
8.2 三个让我印象深刻的翻车现场
第一个坑是SGP30的I2C地址搞错。SGP30的数据手册里地址是0x58，但这是7位地址。STM32 HAL库的I2C地址需要左移一位变成8位格式，也就是0xB0。我一开始忘了移位，结果传感器死活不出数据，排查了整整一个晚上才发现是地址格式问题。类似的坑还出现在SHT30的0x44地址上，这类7位地址和8位地址的混淆，几乎是所有I2C新手都会踩的坑。
第二个坑是PMS7003的数据帧解析。PMS7003的串口默认波特率是9600，但固件刷错成了115200，结果串口收到的全是乱码。一开始我还以为是传感器坏了，后来重新读了手册才想起来要初始化UART时把波特率改成9600。这类问题很好排查，串口助手直接看输出即可，如果是可读的ASCII乱码，多半就是波特率不匹配。
第三个坑是ESP8266的MQTT指纹校验。我在网络任务里启用了TLS连接，结果设备每次开机连MQTT broker都失败，日志显示证书校验失败。查到最后发现是broker的证书有效期快到了，连锁导致整个连接失败。后来我在代码里增加了证书更新时间提醒，并且把TLS模式从强制改成可选，这样即使证书验证出问题，也能退回到明文MQTT模式继续采集数据。
最后，我的一点个人体会
如果你也想做一个类似的嵌入式开源项目，我唯一的建议是别急着写代码，先把传感器买齐、把数据看懂，再决定整体架构。KLL这个项目的核心价值不在于代码多精妙，而在于每一个模块都能被其他人读懂、复现、修改。我到现在还经常收到有人反馈说换了传感器型号、改了屏幕尺寸、加了一个继电器控制新风系统，这种“被二次开发”的感觉，比项目本身跑通还让人高兴。
（全文完）
