CCS811 Arduino: Complete Guide to VOC and eCO2 Air Quality Sensing

When clients ask me about indoor air quality monitoring for smart building projects, the CCS811 Arduino combination is consistently my recommendation for serious VOC and CO2 detection. Unlike the simpler analog sensors I’ve worked with over the years, the CCS811 brings genuine digital intelligence to the table with its integrated microcontroller and calibrated algorithms.

The CCS811 from AMS (now ScioSense) represents a different approach to gas sensing. Rather than outputting a raw analog voltage that requires complex calibration math, this sensor processes readings internally and delivers actual TVOC and eCO2 values over a clean I2C interface. After integrating dozens of these into PCB designs, I can walk you through exactly what makes the CCS811 Arduino setup work reliably.

What is the CCS811 Air Quality Sensor?

The CCS811 is an ultra-low power digital gas sensor designed specifically for indoor air quality monitoring. At its core sits a metal oxide (MOX) sensing element paired with a dedicated microcontroller that handles analog-to-digital conversion, signal processing, and calibration algorithms.

What sets the CCS811 apart from sensors like the MQ-135 is its digital output. Instead of providing a voltage proportional to gas concentration that you need to interpret, the CCS811 calculates actual TVOC concentrations in parts per billion (ppb) and equivalent CO2 (eCO2) in parts per million (ppm) internally. Your Arduino simply reads these processed values over I2C.

The sensor uses a micro-hotplate technology that enables faster response times and lower power consumption compared to traditional heated-plate MOX sensors. This makes it suitable for battery-powered applications where continuous monitoring is needed without draining power quickly.

CCS811 Technical Specifications

Before designing any monitoring circuit, understanding the electrical characteristics prevents the I2C headaches I’ve encountered on more than a few prototype boards:

Parameter	Value
Supply Voltage	1.8V – 3.6V
I2C Interface	Standard/Fast Mode
I2C Address	0x5A (default) or 0x5B
Current Consumption	30mA max (active), 19µA (idle)
eCO2 Range	400 – 8192 ppm
TVOC Range	0 – 1187 ppb
Warm-up Time	20 minutes (each use)
Burn-in Time	48 hours (initial)
Operating Temperature	-5°C to 50°C

One critical specification often overlooked: the CCS811 uses I2C clock stretching. This causes compatibility issues with certain microcontrollers, particularly the Raspberry Pi and older ESP8266 firmware versions. Stick with Arduino-compatible boards for reliable operation.

Gases and Compounds Detected by CCS811

The CCS811 responds to a broad spectrum of volatile organic compounds commonly found in indoor environments:

Compound Type	Examples	Common Sources
Alcohols	Ethanol, Methanol	Sanitizers, cleaners, solvents
Aldehydes	Formaldehyde, Acetaldehyde	Building materials, furniture
Ketones	Acetone	Nail polish, paints, adhesives
Organic Acids	Acetic acid	Food, cleaning products
Amines	Ammonia compounds	Cleaning products, human breath
Hydrocarbons	Benzene, Toluene	Paints, fuels, plastics

The eCO2 output deserves clarification. The CCS811 doesn’t directly measure CO2. Instead, it calculates equivalent CO2 based on the correlation between VOC levels and CO2 in typical indoor environments where humans are the primary source of both. For applications requiring true CO2 measurement, an NDIR sensor is more appropriate.

CCS811 Module Pinout Configuration

Most CCS811 breakout boards expose these connections:

Pin	Name	Function
VIN/VCC	Power Supply	3.3V – 5V input (module has regulator)
GND	Ground	Common ground reference
SDA	I2C Data	Connect to Arduino SDA
SCL	I2C Clock	Connect to Arduino SCL
WAKE	Wake Pin	Pull LOW to enable sensor (critical!)
INT	Interrupt	Optional data-ready notification
RST	Reset	Active LOW reset input
ADD	Address Select	LOW = 0x5A, HIGH = 0x5B

The WAKE pin catches many beginners off guard. If left floating or HIGH, the CCS811 enters sleep mode and won’t respond to I2C commands. Always connect WAKE to GND for continuous operation, or control it via a GPIO if power management is required.

Wiring CCS811 to Arduino

The I2C wiring is straightforward, but getting it right prevents the communication failures I’ve debugged on countless projects:

CCS811 Pin	Arduino UNO	Arduino Mega	Arduino Leonardo
VIN	5V	5V	5V
GND	GND	GND	GND
SDA	A4	D20	D2
SCL	A5	D21	D3
WAKE	GND	GND	GND

For 3.3V Arduino boards like the Due or boards with 3.3V logic, connect VIN directly to 3.3V. Most breakout modules from Adafruit and SparkFun include onboard voltage regulators and level shifters, making them safe for 5V operation.

A word from experience: add 4.7kΩ pull-up resistors on SDA and SCL if your breakout board doesn’t include them. While many modules have these built-in, some budget boards omit them, leading to intermittent communication failures.

Basic CCS811 Arduino Code

Here’s a tested starting point using the Adafruit library:

#include “Adafruit_CCS811.h”

Adafruit_CCS811 ccs;

void setup() {

  Serial.begin(9600);

  Serial.println(“CCS811 Air Quality Monitor”);

  if(!ccs.begin()) {

    Serial.println(“Failed to start CCS811 sensor!”);

    Serial.println(“Check wiring and WAKE pin connection.”);

    while(1);

  }

  // Wait for sensor to be ready

  while(!ccs.available());

  Serial.println(“Sensor initialized successfully”);

  Serial.println(“Warming up – wait 20 minutes for accurate readings”);

}

void loop() {

  if(ccs.available()) {

    if(!ccs.readData()) {

      int co2 = ccs.geteCO2();

      int tvoc = ccs.getTVOC();

      Serial.print(“eCO2: “);

      Serial.print(co2);

      Serial.print(” ppm, TVOC: “);

      Serial.print(tvoc);

      Serial.println(” ppb”);

    } else {

      Serial.println(“ERROR reading sensor data!”);

    }

  }

  delay(1000);

}

The initial readings will show 400 ppm eCO2 and 0 ppb TVOC as the sensor performs internal calibration. Wait the full 20-minute warm-up period before trusting the readings.

CCS811 Drive Modes and Sampling Rates

The CCS811 supports multiple measurement modes for different application requirements:

Mode	Sample Rate	Current Draw	Use Case
Mode 0	Idle	19µA	Sleep/standby
Mode 1	1 second	30mA	Constant monitoring
Mode 2	10 seconds	~2.5mA avg	Standard monitoring
Mode 3	60 seconds	~0.5mA avg	Low-power applications
Mode 4	250ms	30mA	Rapid testing only

Mode 4 (250ms) is intended for testing purposes only and will rapidly degrade the sensor if used continuously. For most indoor monitoring applications, Mode 2 (10-second intervals) provides a good balance between responsiveness and power consumption.

Setting the drive mode:

// Set drive mode during setup

ccs.setDriveMode(CCS811_DRIVE_MODE_10SEC);

Environmental Compensation for Better Accuracy

The CCS811’s accuracy improves significantly when provided with current temperature and humidity data. This is where combining the CCS811 with a BME280 sensor pays dividends.

#include “Adafruit_CCS811.h”

#include “Adafruit_BME280.h”

Adafruit_CCS811 ccs;

Adafruit_BME280 bme;

void setup() {

  Serial.begin(9600);

  if(!ccs.begin()) {

    Serial.println(“CCS811 initialization failed!”);

    while(1);

  }

  if(!bme.begin(0x76)) {

    Serial.println(“BME280 initialization failed!”);

    while(1);

  }

  while(!ccs.available());

}

void loop() {

  float temperature = bme.readTemperature();

  float humidity = bme.readHumidity();

  // Provide environmental data to CCS811

  ccs.setEnvironmentalData(humidity, temperature);

  if(ccs.available() && !ccs.readData()) {

    Serial.print(“eCO2: “);

    Serial.print(ccs.geteCO2());

    Serial.print(” ppm | TVOC: “);

    Serial.print(ccs.getTVOC());

    Serial.print(” ppb | Temp: “);

    Serial.print(temperature);

    Serial.print(“C | Humidity: “);

    Serial.print(humidity);

    Serial.println(“%”);

  }

  delay(10000);

}

One caveat worth noting: the CCS811’s internal heater generates heat that affects nearby temperature sensors. If mounting the BME280 on the same board, expect temperature readings 5-15°C higher than ambient. Position the temperature sensor away from the CCS811, or apply a correction factor.

Understanding eCO2 and TVOC Readings

Interpreting the sensor output correctly matters for practical applications:

eCO2 Reference Levels

eCO2 (ppm)	Air Quality	Action
400-600	Excellent	Normal outdoor/fresh air
600-800	Good	Typical indoor with good ventilation
800-1000	Moderate	Consider increasing ventilation
1000-1500	Poor	Ventilation needed
1500-2000	Very Poor	Immediate ventilation required
>2000	Hazardous	Evacuate and ventilate

TVOC Reference Levels

TVOC (ppb)	Air Quality	Typical Sources
0-50	Excellent	Clean outdoor air
50-100	Good	Well-ventilated spaces
100-200	Moderate	Normal occupied spaces
200-300	Poor	Check for pollution sources
300-500	Very Poor	Identify and eliminate sources
>500	Hazardous	Ventilate immediately

CCS811 Arduino Libraries

Two well-maintained libraries support CCS811 Arduino development:

Library	Developer	Features
Adafruit_CCS811	Adafruit	Simple API, good documentation
SparkFun_CCS811	SparkFun	Advanced features, interrupt support

Both libraries work with standard CCS811 breakout boards. The SparkFun library offers more advanced features like baseline storage and restoration, which helps maintain calibration across power cycles.

Installing via Arduino Library Manager:

1. Open Arduino IDE
2. Navigate to Sketch → Include Library → Manage Libraries
3. Search for “CCS811”
4. Install your preferred library

Baseline Calibration and Storage

The CCS811 performs automatic baseline calibration, adjusting its reference point based on the lowest readings observed over time. For consistent readings across power cycles, store and restore the baseline:

#include “SparkFunCCS811.h”

#include <EEPROM.h>

CCS811 ccs(0x5A);

void setup() {

  Serial.begin(9600);

  ccs.begin();

  // Restore saved baseline from EEPROM

  unsigned int baseline;

  EEPROM.get(0, baseline);

  if(baseline != 0xFFFF) {

    ccs.setBaseline(baseline);

    Serial.println(“Baseline restored from EEPROM”);

  }

}

void loop() {

  if(ccs.dataAvailable()) {

    ccs.readAlgorithmResults();

    // Periodically save baseline (every hour)

    static unsigned long lastSave = 0;

    if(millis() – lastSave > 3600000) {

      unsigned int baseline = ccs.getBaseline();

      EEPROM.put(0, baseline);

      lastSave = millis();

      Serial.println(“Baseline saved to EEPROM”);

    }

  }

  delay(10000);

}

Troubleshooting Common CCS811 Issues

From debugging numerous CCS811 installations, these problems appear most frequently:

Sensor Returns Error or Won’t Initialize: Check that the WAKE pin is connected to GND. This is the most common mistake. Also verify I2C address (0x5A default) matches your code.

Readings Stay at 400 ppm eCO2 and 0 ppb TVOC: The sensor needs 20 minutes of warm-up time each power cycle. For a new sensor, the initial 48-hour burn-in period is essential for stable readings.

I2C Communication Failures on ESP8266: The CCS811 uses clock stretching, which the ESP8266 handles poorly. Update to ESP8266 core version 2.6.0 or later, which includes fixes for this issue.

Inconsistent or Erratic Readings: Environmental compensation improves stability significantly. Add a BME280 or similar sensor to provide temperature and humidity data. Also ensure adequate ventilation around the sensor.

Readings Drift Over Time: Store and restore the baseline calibration across power cycles. The automatic baseline algorithm needs clean air exposure periodically to maintain accuracy.

Practical Applications for CCS811 Arduino Projects

Based on my deployment experience, these applications work well with the CCS811:

Smart HVAC Control

Trigger ventilation systems when eCO2 levels exceed thresholds. The 10-second sampling mode provides responsive control without excessive sensor wear.

Office Air Quality Monitoring

Monitor meeting rooms and open offices where occupancy fluctuates. Network multiple CCS811 nodes via ESP32 for building-wide coverage.

Home Automation Integration

Connect to Home Assistant or similar platforms for automated alerts and historical logging. The I2C interface works cleanly with ESP8266/ESP32 (with updated firmware).

Classroom Ventilation

Schools benefit from CO2 monitoring to maintain student alertness. High eCO2 directly correlates with decreased cognitive performance.

VOC Detection in Workshops

Detect solvent vapors, adhesive off-gassing, and paint fumes in maker spaces and workshops.

Useful Resources and Downloads

Datasheets and Documentation

• AMS/ScioSense CCS811 Datasheet: Complete electrical specifications and register descriptions
• SparkFun CCS811 Hookup Guide: Detailed wiring and code examples
• Adafruit CCS811 Learning Guide: Step-by-step tutorial with troubleshooting

Arduino Libraries

• Adafruit CCS811 Library: Available via Arduino Library Manager
• SparkFun CCS811 Library: GitHub repository with advanced examples
• Maarten Pennings CCS811 Library: Alternative with detailed error handling

Breakout Boards

• Adafruit CCS811 Breakout (STEMMA QT version): Includes level shifting and Qwiic connectors
• SparkFun CCS811 Breakout: BME280 combo version available
• CJMCU-811 Module: Budget option, requires careful voltage management

Frequently Asked Questions

How long does the CCS811 need to warm up before readings are accurate?

The CCS811 requires 20 minutes of warm-up time each time power is applied before readings stabilize. For a brand new sensor, AMS recommends a 48-hour continuous burn-in period to condition the sensing element. During warm-up, readings will show 400 ppm eCO2 and 0 ppb TVOC as the internal algorithms calibrate.

Can the CCS811 measure actual CO2 concentration?

The CCS811 measures equivalent CO2 (eCO2), not actual CO2. It calculates eCO2 based on the correlation between VOC levels and CO2 in typical occupied indoor spaces. For applications requiring true CO2 measurement, such as industrial safety monitoring or greenhouse control, use an NDIR (Non-Dispersive Infrared) sensor like the MH-Z19 or SCD30 instead.

Why does my CCS811 fail to initialize with “Failed to start” errors?

The most common cause is leaving the WAKE pin unconnected. The WAKE pin must be pulled LOW (connected to GND) for the sensor to respond to I2C commands. Other causes include incorrect I2C address (check if your module uses 0x5A or 0x5B), missing pull-up resistors on the I2C lines, or clock stretching issues with certain microcontrollers.

Can I use CCS811 with Raspberry Pi or ESP8266?

The CCS811 uses I2C clock stretching, which causes compatibility issues with Raspberry Pi (hardware limitation) and older ESP8266 firmware. For Raspberry Pi, consider alternative sensors like the SGP30. For ESP8266, update to core version 2.6.0 or later which includes clock stretching fixes. Arduino boards and ESP32 work without issues.

How do I improve CCS811 reading accuracy?

Provide environmental compensation by feeding current temperature and humidity data to the sensor using the setEnvironmentalData() function. This requires an additional sensor like the BME280. Also, store and restore the baseline calibration across power cycles, ensure the sensor is exposed to clean outdoor air periodically for automatic baseline adjustment, and allow the full 20-minute warm-up period before trusting readings.

Final Thoughts

The CCS811 Arduino combination delivers genuine indoor air quality monitoring capability that analog sensors simply cannot match. The integrated signal processing eliminates the complex calibration math required with MQ-series sensors, while the I2C interface keeps wiring clean and simple.

Success with the CCS811 comes down to patience during the burn-in and warm-up periods, proper WAKE pin handling, and ideally pairing it with a temperature/humidity sensor for environmental compensation. Get these fundamentals right, and you’ll have a reliable air quality monitoring system that provides meaningful TVOC and eCO2 data for your smart building, HVAC control, or environmental monitoring projects.

The sensor has limitations, particularly around true CO2 measurement and compatibility with clock-stretching-challenged platforms. But within its intended application space of indoor air quality monitoring, the CCS811 remains one of the most practical digital VOC sensors available for Arduino-based projects.