CCS811 紫色空气质量传感器模块

CCS811TVOC / eCO2 传感器

I2CSDA / SCL 通信

0x5A默认 I2C 地址

3.3VESP32 推荐供电

1. 概述

CCS811 是一款数字空气质量传感器，通过 I2C 输出 TVOC 挥发性有机物和 eCO2 等效二氧化碳数据。它不是 NDIR 真 CO2 传感器，而是根据 VOC 气体变化估算空气质量趋势，适合做室内空气质量检测、通风提醒、空气净化器和教学演示。

紫色模块常见丝印为 VCC / GND / SCL / SDA / WAK / INT / RST / ADD。最小测试只需要接 VCC、GND、SCL、SDA、WAK 五根线。

关键点：WAK 必须接 GND，模块才会保持唤醒。很多“扫不到地址”的问题都是 WAK 没有拉低造成的。

2. 引脚定义

引脚	类型	说明
VCC	电源	ESP32 测试建议接 3.3V。部分紫色转接板可接 5V，但 3.3V 主控统一接 3.3V 更稳妥。
GND	电源	公共地。
SCL	I2C 时钟	接主控 I2C SCL。
SDA	I2C 数据	接主控 I2C SDA。
WAK / WAKE	输入	低电平唤醒，测试时直接接 GND。
INT	输出	中断脚，普通串口测试不接。
RST	输入	低电平复位，普通串口测试不接。
ADD / ADDR	输入	地址选择；不接或低电平通常为 0x5A，拉高通常为 0x5B。

3. 测试前必看

供电与电平

ESP32 是 3.3V 逻辑，CCS811 紫色模块接 ESP32 时建议 VCC 直接接 3V3，SDA/SCL 直接接 ESP32 的 I2C 引脚即可。

预热时间

CCS811 上电后需要预热，刚开始 eCO2 / TVOC 可能跳动。演示时建议等待 1-3 分钟再观察变化，长期监测时连续运行更久读数会更稳定。

注意：不要把酒精、香水、清洁剂等液体滴到传感器上。测试 VOC 变化时，只需要靠近模块即可。

4. ESP32 直接 IIC 接线与代码

接线表

CCS811 紫色模块	ESP32 DevKit	说明
VCC	3V3	推荐 3.3V 供电。
GND	GND	公共地。
SCL	GPIO22	ESP32 常用 I2C SCL。
SDA	GPIO21	ESP32 常用 I2C SDA。
WAK	GND	必须接 GND 唤醒。
INT	不接	普通测试不用。
RST	不接	普通测试不用。
ADD	不接	默认地址 0x5A。

Arduino IDE 库

打开 Arduino IDE 的库管理器，搜索并安装 Adafruit CCS811 Library，按提示安装依赖库。开发板选择对应 ESP32，串口监视器波特率选 115200。

ESP32 测试程序

#include <Wire.h>
#include "Adafruit_CCS811.h"

#define SDA_PIN 21
#define SCL_PIN 22

Adafruit_CCS811 ccs;

void setup() {
  Serial.begin(115200);
  delay(500);

  Serial.println("ESP32 CCS811 test");
  Wire.begin(SDA_PIN, SCL_PIN);

  if (!ccs.begin(0x5A)) {
    Serial.println("CCS811 not found. Try I2C scanner and check WAK -> GND.");
    while (1) {
      delay(1000);
    }
  }

  Serial.println("CCS811 found. Please wait for warm-up.");
}

void loop() {
  if (ccs.available()) {
    if (!ccs.readData()) {
      Serial.printf("eCO2: %u ppm, TVOC: %u ppb\n", ccs.geteCO2(), ccs.getTVOC());
    } else {
      Serial.println("Read error");
    }
  }

  delay(1000);
}

正常串口输出

ESP32 CCS811 test
CCS811 found. Please wait for warm-up.
eCO2: 400 ppm, TVOC: 0 ppb
eCO2: 416 ppm, TVOC: 3 ppb

5. Arduino UNO 接线

UNO 是 5V 逻辑，而 CCS811 芯片本体是低压器件。紫色转接板虽然常见带稳压，但不同批次 I2C 上拉方式可能不同。教学测试可参考下表，长期使用建议加 I2C 电平转换，或者直接用 ESP32 / STM32 这类 3.3V 主控。

CCS811	Arduino UNO
VCC	3.3V 优先；确认模块支持 5V 时可接 5V
GND	GND
SCL	A5
SDA	A4
WAK	GND
INT / RST / ADD	不接

6. I2C 扫描程序

如果主程序提示 CCS811 not found，先上传扫描程序确认总线上能否看到 0x5A。

#include <Wire.h>

void setup() {
  Serial.begin(115200);
  delay(500);
  Wire.begin(21, 22);  // ESP32: SDA=21, SCL=22
  Serial.println("I2C scanner");
}

void loop() {
  byte count = 0;

  for (byte address = 1; address < 127; address++) {
    Wire.beginTransmission(address);
    byte error = Wire.endTransmission();

    if (error == 0) {
      Serial.print("I2C device found at 0x");
      if (address < 16) Serial.print("0");
      Serial.println(address, HEX);
      count++;
    }
  }

  if (count == 0) {
    Serial.println("No I2C devices found");
  }

  delay(3000);
}

7. 读数说明

读数	单位	说明
eCO2	ppm	等效 CO2，不是真正 NDIR CO2 直接测量值。
TVOC	ppb	总挥发性有机物浓度趋势。

刚上电显示 400 ppm / 0 ppb 是常见初始值，不代表环境绝对为 400 ppm。用酒精棉片、油性笔、香水等靠近模块，TVOC 通常会上升；移开并通风后会逐渐下降。

8. 故障排查

扫不到 0x5A

检查 WAK 是否接到 GND。
检查 VCC、GND 是否接反。
检查 SDA、SCL 是否接反。
如果 ADD 被拉高，尝试把程序地址改为 0x5B。

有读数但一直不变化

预热时间太短，先等待 1-3 分钟。
环境空气比较稳定，变化不明显。
传感器被外壳挡住，空气不流通。

快速测试流程

VCC 接 ESP32 的 3V3。
GND 接 ESP32 的 GND。
SCL 接 GPIO22。
SDA 接 GPIO21。
WAK 接 GND，ADD 不接。
先上传 I2C 扫描程序。
确认串口能看到 0x5A。
上传 CCS811 测试程序。
等待预热后观察 TVOC / eCO2。