CCS811 on OLED: eCO2 & TVOC Air Quality
Overview & Wiring
What it is: The CCS811 is a digital air-quality sensor that outputs an equivalent CO2 (eCO2, 400–8192 ppm) and total volatile organic compounds (TVOC, 0–1187 ppb). Unlike the MQ sensors, it gives real digital numbers over I2C.
How it works: An onboard metal-oxide sensor plus a microcontroller compute eCO2 and TVOC and expose them over I2C at address 0x5A. Shares SDA/SCL with the OLED.
Wiring (shared I2C bus with the OLED):
CCS811 SDA -> GPIO4
CCS811 SCL -> GPIO5
CCS811 VCC -> 3V3
CCS811 GND -> GND
CCS811 WAKE -> GND (many boards need WAKE tied low to enable I2C)
OLED VCC=3V3, GND=GND, SDA=GPIO4, SCL=GPIO5
Libraries: "Adafruit CCS811 Library" (installs "Adafruit BusIO"), plus "Adafruit SSD1306" and "Adafruit GFX Library".
On screen / Serial: eCO2 in ppm and TVOC in ppb.
Gotchas: The CCS811 needs ~20 minutes of run-in on first use and a few minutes each start-up before numbers settle. Remember to tie WAKE to GND. It self-heats, so keep it away from your temperature sensors.
Circuit Diagram
Parts You Need
Source Code (Arduino / ESP32)
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#include <Adafruit_CCS811.h>
Adafruit_SSD1306 display(128, 64, &Wire, -1);
Adafruit_CCS811 ccs;
void setup() {
Serial.begin(115200);
Wire.begin(4, 5);
display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
if (!ccs.begin(0x5A)) {
Serial.println("CCS811 not found");
display.setTextColor(SSD1306_WHITE);
display.setCursor(0, 28); display.println("CCS811 not found");
display.display();
while (1) delay(10);
}
while (!ccs.available()) delay(10); // wait for first data
}
void loop() {
if (ccs.available() && !ccs.readData()) {
int eco2 = ccs.geteCO2();
int tvoc = ccs.getTVOC();
display.clearDisplay();
display.setTextColor(SSD1306_WHITE);
display.setTextSize(1);
display.setCursor(0, 0); display.println("CCS811");
display.setTextSize(2);
display.setCursor(0, 16); display.printf("%d", eco2);
display.setTextSize(1);
display.setCursor(0, 36); display.print("eCO2 ppm");
display.setCursor(0, 50); display.printf("TVOC %d ppb", tvoc);
display.display();
Serial.printf("eCO2 %d ppm TVOC %d ppb\n", eco2, tvoc);
}
delay(1000);
}