# Adafruit CCS811 Air Quality Sensor

## Overview

![](https://cdn-learn.adafruit.com/assets/assets/000/098/294/medium800/adafruit_products_CCS811_top.jpg?1609367809)

Breathe easy - we finally have an I2C VOC/eCO2 sensor in the Adafruit shop! Add air quality monitoring to your project and with an **Adafruit CCS811 Air Quality Sensor Breakout**. This sensor from AMS is a gas sensor that can detect a wide range of Volatile Organic Compounds (VOCs) and is intended for indoor air quality monitoring. When connected to your microcontroller (running our library code) it will return a Total Volatile Organic Compound (TVOC) reading and an equivalent carbon dioxide reading (eCO2) over I2C.

Warning: 

Warning: 

![](https://cdn-learn.adafruit.com/assets/assets/000/044/631/medium800/sensors_3566_quarter_ORIG.jpg?1501599369)

The CCS811 has a 'standard' hot-plate MOX sensor, as well as a small microcontroller that controls power to the plate, reads the analog voltage, and provides an I2C interface to read from.

This part will measure **eCO2** (equivalent calculated carbon-dioxide) concentration within a range of 400 to 8192 parts per million (ppm), and **TVOC** (Total Volatile Organic Compound) concentration within a range of 0 to 1187 parts per billion (ppb). According to the fact sheet it can detect Alcohols, Aldehydes, Ketones, Organic Acids, Amines, Aliphatic and Aromatic Hydrocarbons.

Please note, this sensor, like all VOC/gas sensors, has variability and to get precise measurements you will want to calibrate it against known sources! That said, for general environmental sensors, it will give you a good idea of trends and comparisons.

Info: 

The CCS811 has a configurable interrupt pin that can fire when a conversion is ready and/or when a reading crosses a user-settable threshold. The CCS811 supports multiple drive modes to take a measurement every 1 second, every 10 seconds, every 60 seconds, or every 250 milliseconds.

For your convenience we've pick-and-placed the sensor on a PCB with a 3.3V regulator and some level shifting so it can be easily used with your favorite 3.3V or 5V microcontroller.

We've also prepared software libraries to get you up and running in Arduino or CircuitPython with just a few lines of code!

The breakout is made in the[  **STEMMA QT**  form factor](https://www.adafruit.com/?q=stemma%20qt%20sensor "STEMMA QT form factor"), making them easy to interface with. The [STEMMA QT connectors](https://learn.adafruit.com/introducing-adafruit-stemma-qt/what-is-stemma-qt) on either side are compatible with the [SparkFun Qwiic](https://www.sparkfun.com/qwiic) I2C connectors. This allows you to make solderless connections between your development board and the BME280 or to chain it with a wide range of other sensors and accessories using a [**compatible cable**](https://www.adafruit.com/?q=stemma%20qt%20cable).

Info: 

![](https://cdn-learn.adafruit.com/assets/assets/000/044/632/medium800/sensors_3566_kit_ORIG.jpg?1501599870)

# Adafruit CCS811 Air Quality Sensor

## Pinouts

![](https://cdn-learn.adafruit.com/assets/assets/000/098/281/medium800/adafruit_products_CCS811_pinouts_top.jpg?1609362176)

![](https://cdn-learn.adafruit.com/assets/assets/000/044/633/medium800/sensors_3566_kit_ORIG_%282%29.jpg?1501600761)

This sensor has 2 mounting holes and one header breakout strip.

## Power Pins:

- **Vin**  - this is the power pin. Since the sensor uses 3.3V, we have included an onboard voltage regulator that will take 3-5VDC and safely convert it down. To power the board, give it the same power as the logic level of your microcontroller - e.g. for a 5V micro like Arduino, use 5V
- **3Vo**  - this is the 3.3V output from the voltage regulator, you can grab up to 100mA from this if you like
- **GND**  - common ground for power and logic

## Logic pins:

- **SCL ** - this is the I2C clock pin, connect to your microcontrollers I2C clock line. There is a 10K pullup on this pin and it is level shifted so you can use 3 - 5VDC.
- **SDA ** - this is the I2C data pin, connect to your microcontrollers I2C data line. There is a 10K pullup on this pin and it is level shifted so you can use 3 - 5VDC.
- [**STEMMA QT**](https://learn.adafruit.com/introducing-adafruit-stemma-qt) ** -** These connectors allow you to connectors to dev boards with  **STEMMA QT** connectors or to other things with [various associated accessories](https://www.adafruit.com/?q=JST%20SH%204)

## Other Pins:

- **INT**  - this is the interrupt-output pin. It is 3V logic and you can use it to detect when a new reading is ready or when a reading gets too high or too low.
- **WAKE** - this is the wakeup pin for the sensor. It needs to be pulled to ground in order to communicate with the sensor. This pin is level shifted so you can use 3-5VDC logic.
- **RST** - this is the reset pin. When it is pulled to ground the sensor resets itself. This pin is level shifted so you can use 3-5VDC logic.

# Adafruit CCS811 Air Quality Sensor

## Assembly

![](https://cdn-learn.adafruit.com/assets/assets/000/044/634/medium800/sensors_3566_kit_ORIG.jpg?1501601014)

Before use, you'll need to attach headers so you can plug in this sensor into a breadboard. Soldering is essential!

Note we show images of the BME280 sensor, which looks similar - the process is the same as it would be for the CCS811

## Prepare the header strip:

Cut the strip to length if necessary. It will be easier to solder if you insert it into a breadboard - **long pins down**

![adafruit_products_DSC_3779.jpg](https://cdn-learn.adafruit.com/assets/assets/000/045/583/medium640/adafruit_products_DSC_3779.jpg?1503285786)

## Add the breakout board and Solder:

Place the breakout board over the pins so that the short pins poke through the breakout pads

 

Be sure to solder all pins for reliable electrical contact.  
  
_(For tips on soldering, be sure to check out our _[_Guide to Excellent Soldering_](http://learn.adafruit.com/adafruit-guide-excellent-soldering)_)._

![adafruit_products_DSC_3780.jpg](https://cdn-learn.adafruit.com/assets/assets/000/045/584/medium640/adafruit_products_DSC_3780.jpg?1503285807)

![adafruit_products_DSC_3782.jpg](https://cdn-learn.adafruit.com/assets/assets/000/045/585/medium640/adafruit_products_DSC_3782.jpg?1503285820)

![adafruit_products_DSC_3784.jpg](https://cdn-learn.adafruit.com/assets/assets/000/045/586/medium640/adafruit_products_DSC_3784.jpg?1503285831)

##  

You're done!

![adafruit_products_DSC_3785.jpg](https://cdn-learn.adafruit.com/assets/assets/000/045/587/medium640/adafruit_products_DSC_3785.jpg?1503285904)

# Adafruit CCS811 Air Quality Sensor

## Arduino Wiring & Test

You can easily wire this breakout to any microcontroller, we'll be using an Adafruit Metro (Arduino compatible) with the Arduino IDE. But, you can use any other kind of microcontroller as well as long as it has I2C clock and I2C data lines. Note this chip uses clock stretching so make sure your microcontroller supports that in hardware!

# I2C Wiring
- Connect **Vin (red wire on STEMMA QT version)** to the power supply, 3-5V is fine. Use the same voltage that the microcontroller logic is based off of. For most Arduinos, that is 5V
- Connect **GND (black wire on STEMMA QT version)** to common power/data ground
- Connect the **SCL (yellow wire on STEMMA QT version)** pin to the I2C clock  **SCL**  pin on your Arduino.   
On an UNO & '328 based Arduino, this is also known as  **A5** , on a Mega it is also known as  **digital 21**  and on a Leonardo/Micro,  **digital 3**
- Connect the **SDA (blue wire on STEMMA QT version)** pin to the I2C data **SDA ** pin on your Arduino.   
On an UNO & '328 based Arduino, this is also known as  **A4** , on a Mega it is also known as  **digital 20**  and on a Leonardo/Micro,  **digital 2**
- **NOT NEEDED FOR STEMMA QT VERSION:** Connect the  **WAKE** pin to ground **on the original version only.**

This sensor uses I2C address  **0x5A**.

![adafruit_products_CCS811_Arduino_I2C_STEMMA_bb.jpg](https://cdn-learn.adafruit.com/assets/assets/000/098/285/medium640/adafruit_products_CCS811_Arduino_I2C_STEMMA_bb.jpg?1609367157)

![adafruit_products_CCS811_Arduino_I2C_breadboard_bb.jpg](https://cdn-learn.adafruit.com/assets/assets/000/098/286/medium640/adafruit_products_CCS811_Arduino_I2C_breadboard_bb.jpg?1609367181)

![adafruit_products_sensors_CCS811_test_bb.png](https://cdn-learn.adafruit.com/assets/assets/000/098/287/medium640/adafruit_products_sensors_CCS811_test_bb.png?1609367208)

Warning: 

# Download Adafruit\_CCS811 library

To begin reading sensor data, you will need to download **Adafruit\_CCS811** from the Arduino library manager.

Open up the Arduino library manager:

![](https://cdn-learn.adafruit.com/assets/assets/000/084/456/medium800/adafruit_products_1library_manager_menu.png?1574045759)

Search for the  **Adafruit CCS811 ** library and install it

![](https://cdn-learn.adafruit.com/assets/assets/000/084/457/medium800/adafruit_products_ccs811.png?1574045781)

We also have a great tutorial on Arduino library installation at:  
[http://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use](http://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use)

# Load Test Example

Open up  **File-\>Examples-\>Adafruit\_CCS811-\>CCS811\_test**  and upload to your Arduino wired up to the sensor. This example connects to the sensor and starts taking readings.

![](https://cdn-learn.adafruit.com/assets/assets/000/044/728/medium800/sensors_ccs811test.png?1501706729)

Once uploaded to your Arduino, open up the serial console at 9600 baud speed to see the readings. Your sensor will take 3 zero readings while it does some internal calibration and correction things and then start outputting real data. In clean air and a typical indoor space your serial monitor will look something like this:

![](https://cdn-learn.adafruit.com/assets/assets/000/044/635/medium800/sensors_Screenshot_%2831%29.png?1501601928)

Info: 

# Library Reference

To create the object, use

```
Adafruit_CCS811 ccs;
```

initialize the sensor with:

```
if(!ccs.begin()){
    Serial.println("Failed to start sensor! Please check your wiring.");
    while(1);
  }
```

To poll the sensor for available data you can use:

```
bool dataAvailable = ccs.available(); //returns true if data is available to be read
```

Data can be read using:

```
bool error = ccs.readData(); //returns True if an error occurs during the read
```

and then the readings can be accessed with:

```
int eCO2 = ccs.geteCO2(); //returns eCO2 reading
int TVOC = ccs.getTVOC(); //return TVOC reading
```

Approximate ambient temperature can be read using:

```
float temp = ccs.calculateTemperature();
```

# Adafruit CCS811 Air Quality Sensor

## Arduino Library Docs

# Adafruit CCS811 Air Quality Sensor

## Python & CircuitPython

It's easy to use the CCS811 sensor with Python or CircuitPython, and the [Adafruit CircuitPython CCS811](https://github.com/adafruit/Adafruit_CircuitPython_CCS811) module.  This module allows you to easily write Python code that reads the eCO2, TVOC and temperature from the sensor.

You can use this sensor with any CircuitPython microcontroller board or with a computer that has GPIO and Python [thanks to Adafruit\_Blinka, our CircuitPython-for-Python compatibility library](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux).

# CircuitPython Microcontroller Wiring

First wire up a CCS811 to your board exactly as shown on the previous pages for Arduino.  Here's an example of wiring a Feather to the sensor with I2C:

- **Board 3V** to **sensor VIN (red wire on STEMMA QT version)**  
- **Board GND** to **sensor GND (black wire on STEMMA QT version)**  
- **Board SCL** to **sensor SCL (yellow wire on STEMMA QT version)**  
- **Board SDA** to **sensor SDA (blue wire on STEMMA QT version)**  
- **Board GND** to **sensor WAKE (NOT NEEDED ON STEMMA QT VERSION)**  

![adafruit_products_CCS811_Feather_I2C_STEMMA_bb.jpg](https://cdn-learn.adafruit.com/assets/assets/000/098/288/medium640/adafruit_products_CCS811_Feather_I2C_STEMMA_bb.jpg?1609367432)

![adafruit_products_CCS811_Feather_I2C_breadboard_bb.jpg](https://cdn-learn.adafruit.com/assets/assets/000/098/289/medium640/adafruit_products_CCS811_Feather_I2C_breadboard_bb.jpg?1609367592)

![adafruit_products_FeatherM0_CCS811_bb.jpg](https://cdn-learn.adafruit.com/assets/assets/000/098/290/medium640/adafruit_products_FeatherM0_CCS811_bb.jpg?1609367610)

# Python Computer Wiring

Since there's _dozens_ of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, [please visit the guide for CircuitPython on Linux to see whether your platform is supported](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux). 

Here's the Raspberry Pi wired with I2C:

- **Pi 3V3** to **sensor VIN (red wire on STEMMA QT version)**  
- **Pi GND** to **sensor GND (black wire on STEMMA QT version)**
- **Pi SCL** to **sensor SCL (yellow wire on STEMMA QT version)**  
- **Pi SDA** to **sensor SDA (blue wire on STEMMA QT version)**  
- **Pi GND** to **sensor WAKE (NOT NEEDED ON STEMMA QT VERSION)**

![adafruit_products_CCS811_RasPi_I2C_STEMMA_bb.jpg](https://cdn-learn.adafruit.com/assets/assets/000/098/291/medium640/adafruit_products_CCS811_RasPi_I2C_STEMMA_bb.jpg?1609367724)

![adafruit_products_CCS811_RasPi_I2C_breadboard_bb.jpg](https://cdn-learn.adafruit.com/assets/assets/000/098/292/medium640/adafruit_products_CCS811_RasPi_I2C_breadboard_bb.jpg?1609367741)

![adafruit_products_raspi_ccs811_i2c_bb.jpg](https://cdn-learn.adafruit.com/assets/assets/000/098/293/medium640/adafruit_products_raspi_ccs811_i2c_bb.jpg?1609367757)

# CircuitPython Installation of CCS811 Library

You'll need to install the [Adafruit CircuitPython CCS811](https://github.com/adafruit/Adafruit_CircuitPython_CCS811) library on your CircuitPython board.

First make sure you are running the [latest version of Adafruit CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython) for your board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from [Adafruit's CircuitPython library bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases).  Our CircuitPython starter guide has [a great page on how to install the library bundle](https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries).

For non-express boards like the Trinket M0 or Gemma M0, you'll need to manually install the necessary libraries from the bundle:

- **adafruit\_ccs811.mpy**
- **adafruit\_bus\_device**

Before continuing make sure your board's lib folder or root filesystem has the  **adafruit\_ccs811.mpy,** and **adafruit\_bus\_device****   **files and folders**  **copied over.

Next[ connect to the board's serial REPL](https://learn.adafruit.com/welcome-to-circuitpython/the-repl) so you are at the CircuitPython  **\>\>\>**  prompt.

# Python Installation of CCS811 Library

You'll need to install the Adafruit\_Blinka library that provides the CircuitPython support in Python. This may also require enabling I2C on your platform and verifying you are running Python 3. [Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux)!

Once that's done, from your command line run the following command:

- `sudo pip3 install adafruit-circuitpython-ccs811`

If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!

# CircuitPython & Python Usage

To demonstrate the usage of the sensor we'll initialize it and read the eCO2, TVOC, and temperature from the board's Python REPL.

If you're using an I2C connection run the following code to import the necessary modules and initialize the I2C connection with the sensor:

```
import time
import board
import busio
import adafruit_ccs811
i2c_bus = busio.I2C(board.SCL, board.SDA)
ccs811 = adafruit_ccs811.CCS811(i2c_bus)
```

Then you'll want to calibrate the thermistor:

Now you're ready to read values from the sensor using any of these properties:

- **eco2** - Equivalent Carbon Dioxide in parts per million. Clipped to 400 to 8192ppm.
- **tvoc** - Total Volatile Organic Compound in parts per billion.
- **temperature** - Temperature based on optional thermistor in Celsius.

For example to print eCO2, TVOC, and temperature:

```
print("CO2: %1.0f PPM" % ccs811.eco2)
print("TVOC: %1.0f PPM" % ccs811.tvoc)
print("Temp: %0.1f C" % ccs811.temperature)
```

![](https://cdn-learn.adafruit.com/assets/assets/000/059/217/medium800/adafruit_products_CCS811_REPL_Print_Output.png?1534357415)

That's all there is to using CCS811 with Python and CircuitPython!

# Full Example Code
https://github.com/adafruit/Adafruit_CircuitPython_CCS811/blob/main/examples/ccs811_simpletest.py

# Adafruit CCS811 Air Quality Sensor

## Python Docs

# Adafruit CCS811 Air Quality Sensor

## Downloads

# Documents

- [CCS811 Datasheet](https://cdn-learn.adafruit.com/assets/assets/000/044/636/original/CCS811_DS000459_2-00-1098798.pdf?1501602769)
- [CCS811 Fact sheet](https://cdn-learn.adafruit.com/assets/assets/000/044/737/original/Factsheet_CCS811.pdf?1501710153)
- [CCS811 Mechanical Considerations App Note](CCS811_Doc_cAppNote-Mechanical-Considerations_AN000368_v1..pdf)
- [CCS811 NTC Thermistor App Note](CCS811_Doc_cAppNote-Connecting-NTC-Thermistor_AN000372_v1..pdf)
- [CCS811 Baseline Clear/Restore App Note](CCS811_Doc_cAppNote-Clean-Air-Baseline-Save-Restore_AN000370_v2..pdf)

- [Adafruit CCS811 Arduino Driver](https://github.com/adafruit/Adafruit_CCS811)
- [CCS811 CircuitPython Driver](https://github.com/adafruit/Adafruit_CircuitPython_CCS811)
- [Fritzing object in the Adafruit Fritzing library](https://github.com/adafruit/Fritzing-Library)
- [CCS811 breakout PCB files (EAGLE format)](https://github.com/adafruit/Adafruit-CCS811-Breakout-PCB/tree/master)

# Schematic and Fab Print for STEMMA QT Version
![](https://cdn-learn.adafruit.com/assets/assets/000/098/282/medium800/adafruit_products_CCS811_sch.png?1609366142)

![](https://cdn-learn.adafruit.com/assets/assets/000/098/283/medium800/adafruit_products_CCS811_fab_print.png?1609366157)

# Schematic and Fab Print for Original Version

click to enlarge

![](https://cdn-learn.adafruit.com/assets/assets/000/044/639/medium800/sensors_schematic.png?1501604679)

![](https://cdn-learn.adafruit.com/assets/assets/000/044/638/medium800/sensors_dims.png?1501604623)

# Adafruit CCS811 Air Quality Sensor

## FAQ

### 

The initial versions of this chip had an internal thermistor. But for some reason this was removed by the vendor. They did this without revising the chip designation. The functionality basically just vanished and all mention of it removed from the revised datasheet.

We have marked the temperature function as deprecated in our libraries. If you think you can verify you have a version with a functional thermistor, then you can probably use the temperature function. But if you are getting odd or no readings when using this function, it is likely you have the newer version of the chip with no thermistor - temperature will not work.


## Featured Products

### Adafruit CCS811 Air Quality Sensor Breakout - VOC and eCO2

[Adafruit CCS811 Air Quality Sensor Breakout - VOC and eCO2](https://www.adafruit.com/product/3566)
[Discontinued - **you can grab the ** Adafruit SGP30 Air Quality Sensor Breakout - VOC and eCO2 - STEMMA QT / Qwiic  **instead! **](https://www.adafruit.com/product/3709)

Breathe easy - we finally have an I2C VOC/eCO2 sensor in the Adafruit shop! Add air...

No Longer Stocked
[Buy Now](https://www.adafruit.com/product/3566)
[Related Guides to the Product](https://learn.adafruit.com/products/3566/guides)

## Related Guides

- [Using Piezo Buzzers with CircuitPython & Arduino](https://learn.adafruit.com/using-piezo-buzzers-with-circuitpython-arduino.md)
- [Madison's NeoClock - A PIC + KiCAD + NeoPixel adventure](https://learn.adafruit.com/madisons-neoclock-a-pic-kicad-neopixel-adventure.md)
- [Monochrome OLED Breakouts](https://learn.adafruit.com/monochrome-oled-breakouts.md)
- [Black Lives Matter Education & Workshop Kit](https://learn.adafruit.com/black-lives-matter-badge.md)
- [Adafruit Si5351 Clock Generator Breakout](https://learn.adafruit.com/adafruit-si5351-clock-generator-breakout.md)
- [NeoKey Socket Breakout with NeoPixel for MX and CHOC Key Switches](https://learn.adafruit.com/neokey-breakout.md)
- [Adafruit HDC302x Precision Temperature & Humidity Sensor](https://learn.adafruit.com/adafruit-hdc3021-precision-temperature-humidity-sensor.md)
- [Mini Weather Station ESP32-S3 TFT](https://learn.adafruit.com/mini-weather-station-esp32-s2-tft.md)
- [Adafruit TE MS8607 PHT Sensor](https://learn.adafruit.com/adafruit-te-ms8607-pht-sensor.md)
- [Circle of Fifths Euclidean Synth with synthio and CircuitPython](https://learn.adafruit.com/circle-of-fifths-euclidean-synth-with-synthio-and-circuitpython.md)
- [Adafruit VL53L1X Time of Flight Distance Sensor](https://learn.adafruit.com/adafruit-vl53l1x.md)
- [CLUE Custom CircuitPython Badge](https://learn.adafruit.com/clue-custom-circuit-python-badge.md)
- [Adafruit Pixel Shifter](https://learn.adafruit.com/adafruit-pixel-shifter.md)
- [Adafruit NeoKey 1x4 QT I2C Breakout](https://learn.adafruit.com/neokey-1x4-qt-i2c.md)
- [Adafruit PyBadge and PyBadge LC](https://learn.adafruit.com/adafruit-pybadge.md)