CCS811 Air Quality Breakout Hookup Guide

Contributors: MTaylor
Favorited Favorite 3

Example: Basic Reading

After you’ve got pins attached to your breakout board, the first example to use should be BasicReadings. Select it from examples or copy from below.

Connect the sensor as follows as a starting place for the examples.

alt text

Wiring diagram showing basic connection to RedBoard. Click for a closer look.

For this example, only 3.3V, GND, SDA and SCL are needed. The jumpers on the board are left in the default positions.


  Marshall Taylor @ SparkFun Electronics
  Nathan Seidle @ SparkFun Electronics

  April 4, 2017

  Read the TVOC and CO2 values from the SparkFun CSS811 breakout board

  This is the simplest example.  It throws away most error information and
  runs at the default 1 sample per second.

  A new sensor requires at 48-burn in. Once burned in a sensor requires
  20 minutes of run in before readings are considered good.

  Hardware Connections (Breakoutboard to Arduino):
  3.3V to 3.3V pin
  GND to GND pin
  SDA to A4
  SCL to A5

  Uses Wire.h for i2c operation

  Development environment specifics:
  Arduino IDE 1.8.1

  This code is released under the [MIT License](

  Please review the file included with this example. If you have any questions
  or concerns with licensing, please contact

  Distributed as-is; no warranty is given.
#include "SparkFunCCS811.h"

#define CCS811_ADDR 0x5B //Default I2C Address
//#define CCS811_ADDR 0x5A //Alternate I2C Address

CCS811 mySensor(CCS811_ADDR);

void setup()
  Serial.println("CCS811 Basic Example");

  //It is recommended to check return status on .begin(), but it is not
  CCS811Core::status returnCode = mySensor.begin();
  if (returnCode != CCS811Core::SENSOR_SUCCESS)
    Serial.println(".begin() returned with an error.");
    while (1); //Hang if there was a problem.

void loop()
  //Check to see if data is ready with .dataAvailable()
  if (mySensor.dataAvailable())
    //If so, have the sensor read and calculate the results.
    //Get them later

    //Returns calculated CO2 reading
    Serial.print("] tVOC[");
    //Returns calculated TVOC reading
    Serial.print("] millis[");
    //Simply the time since program start

  delay(10); //Don't spam the I2C bus

At the beginning, an object is created in the global space CCS811 mySensor(CCS811_ADDR); and is constructed with the address as a parameter. During the setup phase, the library is told to configure with CCS811Core::status returnCode = mySensor.begin(); Using the return parameter to check for errors is optional, and in this example if the return code is not valid, the program enters a captive while loop.

To get data from the sensor, mySensor.dataAvailable() is checked until a new reading is ready, mySensor.readAlgorithmResults(); is called to have the sensor process the reading, then mySensor.getCO2() and mySensor.getTVOC() are used to retrieve the calculated values for gas levels.

alt text

Example terminal output

If everything is connected correctly, the serial window will report gas levels every second. Remember the sensor takes 20 minutes to properly warm up, so values reported will rise up in the early stages of operation!


To get data from the CCS811, these minimum requirements must be met:

  • Create a CCS811 object in the global space
  • Run .begin() of your object (Return type monitoring optional)
  • Check for the availability of new data with .dataAvailable()
  • Use .readAlgorithmResults() to perform a measurement
    • .getCO2() to get the last equivalent CO2 reading (no I2C bus operation)
    • .getTVOC() to get the last TVOC reading (no I2C bus operation)