STM32驱动CCS811气体传感器：基于I2C的eCO2与tVOC测量工程实践

简介：基于STM32与CCS811气体传感器的毕业设计工程源码包，面向嵌入式、物联网方向学习者。项目以STM32F10x为主控，通过I2C接口驱动CCS811传感器，实现CO2与VOCs浓度实时采集，包含连续测量、低功耗模式切换及数据读取等核心逻辑，适合需要完成类似课设或快速上手气体传感开发的读者。资源共80个文件，以35个h头文件与33个c源码文件为主，另有Keil工程配置、hex烧录文件等，压缩包仅339KB，结构包含CORE、SYSTEM、USER、HARDWARE等模块，方便按功能阅读与移植。已有1963人学习下载。项目中包含硬件接口设计、微控制器编程、传感器应用与通信协议实现等嵌入式系统基本要素，是课程设计与毕设的完整参考。通过该工程可掌握STM32标准外设库的使用、I2C时序配置、传感器校准流程，以及数据通过串口、蓝牙或Wi-Fi发送至远程端进行展示与分析的扩展方法，对理解嵌入式软硬件联调很有帮助。

1. 手头有块 STM32 和一片 CCS811，先掂量它到底能干多少事

调试时我习惯先把编译器和 I2C 探针都接好，把传感器放桌面上通电，第一件事不是急着读 eCO2，而是把 I2C 扫描器跑一遍。CCS811 这颗气体传感器在毕业设计里的出场率比想象中高：它把 tVOC 和 eCO2 两个关键指标集成在一颗小封装里，I2C 读出 4 个字节就能直接换算出空气质量的数字化结果。但网上一搜能直接复制的代码往往只写了“初始化 + 循环读”，真正的工程闭环还缺模式切换、状态检查、环境补偿、基线校准这四个环节，这套代码的价值就在于把以上四件事做全。它适合两类人：一类是手里有 STM32 板子但没写过 I2C 气体传感器驱动，想看看完整链路的人；另一类是毕设想以空气质量监测为题、想在不重复踩坑的前提下尽快出实物结果的人。

2. 硬件连接和 I2C 通信：SCL/SDA 怎么接，地址为什么是 0x5A

2.1 引脚分配：VDD、ADDR、WAK 对应的位置

接线之前先把数据手册的引脚定义理清，我把这个项目里实际会用到的引脚列成一张表，照着接不会出错：

这里最容易出问题的就是 WAK 引脚。CCS811 的数据手册要求 WAK 保持低电平才让内部主状态机处于正常工作状态，很多开发板例程根本不碰这根引脚，芯片却经常停在待机模式里不干活。这份工程里我给 WAK 分配了一个普通 GPIO，初始化前先拉低，既保证电源上电后芯片立即可操作，又方便以后想加低功耗唤醒时只改一个引脚。

SCL、SDA 要配成开漏输出并外接上拉电阻。STM32F103 的内部上拉一般只有几十千欧，拉 I2C 总线高电平的效果并不理想，项目里建议直接焊两个 4.7kΩ 上拉电阻到 3.3V。如果不焊上拉，总线的低电平时序会很别扭，主机扫描时偶尔能看到 ACK、偶尔全部沉默，这种状态最烧时间。调试初期可以用 100kΩ 先验证通断，最后定版再换 4.7kΩ，读数稳定性会明显不一样。

2.2 设备地址和寄存器表：在没有读出数据前先把这张表理顺

CCS811 的 7 位地址由 ADDR 引脚决定：接 GND 是 0x5A，接 VDD 是 0x5B。STM32 HAL 库的 I2C 接口要的是 8 位地址，所以调用时要左移一位，写成0x5A << 1，也就是 0xB4。这个“左移一位”看着简单，实际项目里最容易翻车的就是这里填了 0x5A，然后用 I2C 扫描器怎么扫都认不出设备，又去捣鼓硬件，最后发现只是地址参数错了。

传感器的主要寄存器按地址排列如下：

多数时候初始化只会接触 0x00、0x01、0xFF，正常工作只会接触 0x02；一旦读数不合理，排错才会去查 0x0E 和 0x08。所以项目代码按这个使用频度把函数分成 init、read、calibrate 三组，对新手来说看代码能少绕弯。

2.3 上电顺序与 I2C 总线电平的坑

上电顺序这件事在数据手册里写得很隐蔽：CCS811 要求 VDD 稳定后至少等待 10ms 再发起 I2C 操作，如果上电后立刻读寄存器，前几次读回的 STATUS 经常是 0x00，看起来像设备不存在。工程里的初始化函数在复位命令后加了 100ms 延时再读 STATUS，这个延时是给传感器内部电源轨和振荡器留出的裕量。

我在某实验室调多块模块并联时遇到过另一个奇怪现象：两个模块并联在一条总线上，只保留了一组上拉电阻，高电平却只有 1.2V 左右，两个设备都识别不了。原因是模块板内部自带 10kΩ 上拉，两块板子并联后等效上拉只有 5kΩ，加上 STM32 GPIO 驱动能力有限，SCL 高电平被拉到临界区。解决方式是只保留一组 4.7kΩ 上拉，另一块模块板的上拉电阻焊掉，这也是为什么网上总说“I2C 多设备只留一组上拉”的原因。

3. 软件结构拆解：驱动层、服务层和应用层怎么分

3.1 工程目录和文件职责

这份代码把工程分成了三层：

Project ├─ Core │ ├─ Src │ │ ├─ main.c # 应用层：初始化、主循环、串口打印 │ │ └─ i2c.c # HAL I2C 硬件层 │ └─ Inc ├─ CCS811 │ ├─ Inc │ │ ├─ ccs811.h # 寄存器宏、错误码、数据结构 │ │ └─ ccs811_i2c.h # I2C 读写接口声明 │ └─ Src │ ├─ ccs811.c # 驱动层：初始化、读取、校准逻辑 │ └─ ccs811_i2c.c # I2C 读写封装 └─ BSP ├─ bsp_delay.c # 延时服务 └─ bsp_printf.c # printf 重定向

为什么把 I2C 单独抽一层而不是直接在 ccs811.c 里调 HAL 函数：第一，HAL 函数签名太长，每个寄存器读写都要重复写设备地址和 mem size，两层封装之后驱动代码一行一次读写，可读性好很多。第二，后续如果要把 CCS811 挂到 I2C2 上，或者换成 GPIO 模拟 I2C，只要改 ccs811_i2c.c 一个文件，驱动层逻辑完全不用动。我给别的平台移植这套驱动时，就是把HAL_I2C_Mem_Read替换成软件时序函数，一个下午就能跑通。

3.2 数据结构：把一次测量结果装进一个结构体

CCS811 的读寄存器操作一次可以读 8 个字节，但实际有意义的数据是前 4 字节：eCO2 两个字节、tVOC 两个字节。为了让上层调用的时候不碰寄存器裸数据，驱动里定义了一个结果结构体：

typedef struct { uint16_t co2; /* eCO2 浓度，单位 ppm */ uint16_t tvoc; /* tVOC 浓度，单位 ppb */ uint8_t ready; /* 数据就绪标志，1 表示本次数据有效 */ uint8_t err; /* 错误 ID，从 0x06 寄存器读回 */ } ccs811_data_t;

这里的参数含义要说明白：co2 和 tvoc 是驱动层已经把字节翻转、拼好的最终数值；ready 字段为了让应用层不重复读状态寄存器就能判断本次数据是否新鲜；err 字段保留错误 ID，打印出来方便调试。用一个结构体而不是三个全局变量的好处是，后续接 OLED、串口、Wi-Fi 模块时，传递参数只需要传一个指针；结构体还可以塞进环形队列，做多帧缓存分析变化趋势。

3.3 主流程调用链与启动时序

主函数里体现的就是完整的调用链：

int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_I2C1_Init(); BSP_Init_Uart(); /* 串口重定向，printf 可用 */ if (CCS811_Init() != CCS811_OK) { printf("CCS811 init failed\r\n"); while (1); } printf("CCS811 init ok\r\n"); while (1) { ccs811_data_t d; if (CCS811_Read(&d) == CCS811_OK && d.ready) { printf("eCO2: %u ppm, tVOC: %u ppb\r\n", d.co2, d.tvoc); } HAL_Delay(100); } }

主循环只做两件事：调 CCS811_Read，读成功且 ready 为真就打印。HAL_Delay(100) 是节流用的，因为如果配置的是 250ms 测量模式，主循环跑太勤会把旧数据重复打印，加一个小延时既省串口带宽，又避免反复触发 I2C 总线上无谓的读操作。如果读到的不是新数据，就静默等待下一轮，不打印任何内容，这样串口输出里每一行都有实际意义。

4. 核心模块实现：初始化、测量与校准的源码逐段拆

4.1 I2C 读写封装：设备地址与寄存器地址别混

ccs811_i2c.c 里是面向寄存器的读写操作：

/* ccs811_i2c.c */ #define CCS811_ADDR 0x5A uint8_t ccs811_i2c_write(uint8_t reg, uint8_t *buf, uint8_t len) { return HAL_I2C_Mem_Write(&hi2c1, (uint16_t)(CCS811_ADDR << 1), (uint16_t)reg, I2C_MEMADD_SIZE_8BIT, buf, len, 100); } uint8_t ccs811_i2c_read(uint8_t reg, uint8_t *buf, uint8_t len) { return HAL_I2C_Mem_Read(&hi2c1, (uint16_t)(CCS811_ADDR << 1), (uint16_t)reg, I2C_MEMADD_SIZE_8BIT, buf, len, 100); }

这段代码的要点在于参数：HAL_I2C_Mem_Read的第二个参数DevAddress要求是 8 位地址，也就是 0x5A 左移后得到 0xB4；第三个参数MemAddress是寄存器地址，这里是 8 位寄存器地址，所以I2C_MEMADD_SIZE_8BIT必须写对，写错成 16BIT 会多出一个非法字节；最后一个参数是超时时间 100ms，如果总线被拉死，函数会在 100ms 后返回超时错误，不会把整个主循环堵死。

4.2 初始化函数：软复位、APP 校验、模式选择

初始化是整个驱动里最容易写错的一段，以下代码按顺序执行复位、检查、配置模式三件事：

uint8_t CCS811_Init(void) { uint8_t status; uint8_t mode = 0x20; /* 每秒测量一次 */ /* 1. 软复位：依序写 4 个字节 */ uint8_t rst[4] = {0x11, 0xE5, 0x72, 0x8A}; ccs811_i2c_write(0xFF, rst, 4); HAL_Delay(100); /* 2. 检查固件应用是否有效 */ ccs811_i2c_read(0x00, &status, 1); if ((status & 0x10) == 0) { return 0x81; /* 错误码：APP 无效 */ } /* 3. 配置测量模式 */ ccs811_i2c_write(0x01, &mode, 1); HAL_Delay(100); return 0; }

检查固件有效位的作用是区分两种情况：芯片出厂带引导程序但不一定带应用固件，只有 STATUS 寄存器 bit4 置 1 时算法才存在。如果这里检查失败，后续读 0x02 寄存器只会得到全零。我这里返回 0x81 作为错误码，应用层看到非 0 就停止初始化流程并打印错误，测试时能直接看出是哪一步卡住。

4.3 按状态位轮询，解析 eCO2 和 tVOC

测量模式下传感器按设定周期更新内部结果，读取时必须先看 STATUS 的 bit3 是否为 1，再读 0x02 寄存器，否则可能拿到上一帧的重复数据或者中间态数据：

uint8_t CCS811_Read(ccs811_data_t *d) { uint8_t status; uint8_t raw[8]; ccs811_i2c_read(0x00, &status, 1); d->err = 0; d->ready = 0; /* 状态寄存器 bit3 = 数据就绪 */ if ((status & 0x08) == 0) { return 0x82; /* 错误码：暂无新数据 */ } /* 读 8 字节原始结果，只用前 4 字节 */ ccs811_i2c_read(0x02, raw, 8); d->co2 = (uint16_t)((raw[0] << 8) | raw[1]); /* 高字节在前 */ d->tvoc = (uint16_t)((raw[2] << 8) | raw[3]); d->ready = 1; return 0; }

注意原始数据是大端结构，高字节在前。STM32 是小端单片机，所以不能直接拿内存指针强转成 uint16_t，必须手动移位拼接。一次读 8 字节而不是读 4 字节，是考虑到寄存器数据区是连续排列的，整块读比两次单独读更省总线时间，也不会出现两次读之间数据更新的缝隙。这样的轮询方式是 I2C 气体传感器最常见的做法，不需要中断，也不用额外引脚。

4.4 温湿度补偿与基线校准：让读数不漂的两种手段

CCS811 内部算法依赖环境温度和湿度做补偿，不写补偿数据时传感器会用默认的 25℃、50% RH，读数误差在温度偏离较大时会明显变大。补偿代码通过 0x08 寄存器写入环境数据，格式比较特殊：

/* hum: 百分比 RH，temp: 摄氏度，只支持整数 */ void CCS811_SetEnv(uint8_t hum, uint8_t temp) { uint8_t env[4]; uint16_t h = (uint16_t)(hum * 500); /* 50% RH 表示为 25000 */ uint16_t t = (uint16_t)(temp * 1000); /* 25℃ 表示为 25000 */ env[0] = (uint8_t)(h >> 8); env[1] = (uint8_t)(h & 0xff); env[2] = (uint8_t)(t >> 8); env[3] = (uint8_t)(t & 0xff); ccs811_i2c_write(0x08, env, 4); }

湿度单位不是简单的百分比，而是千分之 RH：50% RH 换算成 50000 存进两个字节，所以代码里乘 500。温度是摄氏度乘以 1000 后拆成高、低字节。这套格式写错过一次就会导致补偿值差得离谱，数据一会跳到 900ppm，一会跌回 300ppm。

基线校准则解决长期漂移问题。传感器在长时间运行后，测量基准会发生缓慢偏移，需要在已知良好环境下读取 0x0E 寄存器拿到基线值，存到 Flash 或 EEPROM，下次上电再写回：

void CCS811_SaveBaseline(uint16_t bl) { uint8_t b[2] = { (uint8_t)(bl >> 8), (uint8_t)(bl & 0xff) }; ccs811_i2c_write(0x0E, b, 2); } uint16_t CCS811_GetBaseline(void) { uint8_t b[2] = {0, 0}; ccs811_i2c_read(0x0E, b, 2); return (uint16_t)((b[0] << 8) | b[1]); }

调用时机很关键：保存基线要在传感器连续运行一段时间、数据稳定之后再做，而不是刚上电就读；写入基线则在上电初始化完成后马上做，这样可以省掉很长一段重新自校准的时间。整个项目的校准思路就是“环境补偿消除温湿度干扰 + 基线校准消除长期漂移”，这两件事做齐了，数据才具备参考价值。

5. 避坑指南：把 CCS811 调通路上最容易翻车的五个细节

5.1 现象：I2C 扫描不到 0x5A，看到的全是 0xFF

I2C 扫描器跑完一个地址周期，列表里没有 0x5A，全部回 0xFF。原因一般是三个：HAL 参数里地址没左移、WAK 引脚悬空、总线上没上拉电阻。排查顺序先看代码里的地址是不是0x5A << 1，再看 WAK 有没有被拉低，最后用万用表量 SCL 和 SDA 对地电压，正常空闲时都应该接近 3.3V。如果量出来只有 1V 左右，基本是上拉电阻阻值太小或缺失，焊上 4.7kΩ 再试。

5.2 现象：初始化返回成功，主循环里 forever 都等不到 ready 位

代码检查 STATUS 寄存器 bit4 通过了，但 bit3 一直为 0，说明测量模式没有真正生效。常见原因有两种：写入 0x01 的 mode 值写错了，比如写了 0x20 之外的非法值；或者写模式之后没有给传感器留出内部处理时间，紧接着就进入 while 循环疯狂读状态。解决方式是在写模式后固定延时 100ms 以上，再进入轮询；同时用单步调试确认 0x01 寄存器读回的值就是你写进去的值。

5.3 现象：刚上电 eCO2 显示 400ppm，二十分钟后飘到 1200ppm

这个现象不是故障，是 CCS811 算法特有的热机过程。传感器内部算法启动后需要一段时间完成自校准，期间读数会从 400ppm 附近快速爬升并逐渐稳定，具体时间取决于环境变化幅度。如果一上电就把数据送给上位机画曲线，曲线前段会有明显的急升急降，容易被误判。处理方式是在工程里加一个预热丢弃机制：初始化完成后 20 分钟内只打印状态不存储数据，或者把这段时间的数据打上“未稳定”标记。

5.4 现象：断电重连之后，整体读数比断电前偏高或偏低一大截

这是基线没保存导致的。CCS811 断电后内部基线清零，再次上电要重新进入自校准阶段，期间读数会整体偏移。如果项目需要长时间监测，必须在上电初始化的某个时间点读取 BASELINE 寄存器并存入 Flash，下次启动时写回。我的习惯是每隔一小时自动读一次基线并刷新存储，这样即使断电恢复，也能从最新基线继续工作，而不是用一个几星期前的旧基线。

5.5 现象：换了块开发板，同样的代码读数完全不规律

不同开发板 I2C 引脚的 GPIO 配置可能不一样，有的例程把 SCL/SDA 配成了推挽输出，这在 STM32 HAL 下会导致总线电平冲突，偶尔能读到数据、偶尔卡死。正确配置是开漏输出模式、速度设为 HIGH，启用内部上拉与否都可以，但外部最好还是保留 4.7kΩ 上拉。另外，如果总线上另外挂了 EEPROM 或其他 I2C 设备，地址冲突也会产生类似症状，可以用 I2C 扫描器把整个总线的设备地图打印出来逐一核对。

6. 二次开发：把单传感器读值升级成能直接用的空气质量仪

6.1 加 OLED 显示和阈值报警

读值流程稳定之后，最常见的改造是接一块 OLED 屏幕和蜂鸣器。OLED 显示部分应该在主循环里复用 ccs811_data_t 结构体，把温度、湿度、CO2、tVOC 四个值分两屏滚动显示：

if (CCS811_Read(&d) == CCS811_OK && d.ready) { OLED_ShowNum(0, 0, d.co2, 4); /* 第一行显示 ppm */ OLED_ShowNum(2, 0, d.tvoc, 3); /* 第二行显示 ppb */ if (d.co2 > 1000) { Buzzer_On(); /* 超阈值报警 */ } else { Buzzer_Off(); } }

阈值的修改应该做成宏定义放在头文件里，比如#define CO2_WARN_THRESHOLD 1000，不要散落在主函数各处的魔法数里。报警逻辑注意加一个去抖判断，连续两帧超过阈值才触发蜂鸣器，避免瞬时尖刺造成误报。

6.2 把校准过程做成菜单可调

如果还想往工程方向做，可以把基线保存、环境补偿、预热时间都暴露成串口命令。比如收baseline save就把当前基线写入 Flash，收baseline load就执行一次写回。这样一来，设备装到不同环境时，维护人员不需要改代码重新烧录，直接在终端敲两条命令就能完成校准。这个功能对毕业设计验收时现场演示特别有用，因为在密闭演示房间里数据一定会偏高，提前用命令重置一次基线，展示效果会平稳很多。

6.3 驱动层再抽一遍，方便接下一个传感器

做一个多传感器空气质量平台是这类项目最自然的延伸。改造方向是把 ccs811_data_t 改成通用结构体，给每个传感器实现同一组接口：init、read、calibrate、sleep，然后在应用层用一张函数指针表管理多个设备。这样后续接风速、粉尘传感器时，只需要照着 ccs811.c 再写一套驱动文件，主循环几乎不用动。

从那以后我每次拿到新的传感器芯片，都会先把硬件层、驱动层、应用层建好三个目录，再写最简单的读寄存器代码，跑通之后再逐步加补偿和校准逻辑。这个习惯帮我避开过好几次“能出数据但数据不可信”的尴尬状况。CCS811 这套工程如果第一次跑不顺，大部分问题都出在地址和上拉电阻上，而不是代码本身。希望帮到你。

本文还有配套的精品资源，点击获取