CCS811 Air Quality Sensor Guide Datasheet by Adafruit Industries LLC

View All Related Products | Download PDF Datasheet
adafruit learning system
Adafruit CCS811 Air Quality Sensor
Created by Dean Miller
Last updated on 2019-07-17 06:48:41 PM UTC
* adafruit learning system
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.
This sensor is not well supported on Raspberry Pi. This is because it uses I2C clock stretching which the Pi
cannot do without drastically slowing down the I2C speed. CircuitPython and Arduino are supported.
This chip USED to support a thermistor for temperature sensing, but it no longer does. Please use an external
temperature sensor!
© Adafruit Industries Page 3 of 25
HCX Gas Sensor“ UiDIStSUDC Ulogicz3-5UDB E487316 KX—D
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.
AMS recommends that you run this sensor for 48 hours when you first receive it to "burn it in", and then 20
minutes in the desired mode every time the sensor is in use. This is because the sensitivity levels of the
sensor will change during early use.
© Adafruit Industries Page 4 of 25
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
© Adafruit Industries Page 5 of 25
* adafruit learning system
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.
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 Industries Page 6 of 25
MMMM i’ i? H U H H T‘ V ===:; ==::: :== aaaa uuuuuuuuuuuuuuuuuuuuuu uuuuuuuuuuuuuuuuuuuuuu uuuuuuuuuuuuuuuuuuuuuu uuuuuuuuuuuuuuuuuuuuuu uuuuuuuuuuuuuuuuuuuuuu uuuuuuuuuuuuuuuuuuuuuuuuu
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
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 Industries Page 7 of 25
:I E.- 2- «- am 8| 2' 2.- Cl En 2- SI 2' 9' ._l SI ml wl ”I N I Illl’l‘l Illtll .Illlll Ilnl Int-mum IIIIIII‘ IIIIII CCSSll Gr. Sensur sun SCL 3
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
© Adafruit Industries Page 8 of 25
mum z.- SI SI in SI 2- 2.- :- en El 3‘ 2.. N—U :- 3' at cl “I a. IIII’I‘I‘I Illrllv In N. I. ll II It [I'll-I‘ll a: ma I2
You're done!
© Adafruit Industries Page 9 of 25
* adafrult learning system fritzfing
Arduino Wiring &
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 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 to common power/data ground
Connect the SCL 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 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
Connect the WAKE pin to ground.
This sensor uses I2C address 0x5A.
Download Adafruit_CCS811 library
To begin reading sensor data, you will need to download Adafruit_CCS811 from our github repository. You can do that
Don't forget to tie WAKE to Ground - this is required!
© Adafruit Industries Page 10 of 25
S nk| And m 132 —E Emmvookndp cm‘w Sm Cal‘s Sm AS... cm‘sn'ms Plgnsdup cwsnmw pm cum: pm cwcamma mm ’ CMoQ
by visiting the github repo and manually downloading or, easier, just click this button to download the zip
Rename the uncompressed folder Adafruit_CCS811 and check that the Adafruit_CCS811 folder contains
Adafruit_CCS811 .cpp and Adafruit_CCS811 .h
Place the Adafruit_CCS811 library folder your arduinosketchfolder/libraries/ folder.
You may need to create the libraries subfolder if its your first library. Restart the IDE.
We also have a great tutorial on Arduino library installation at: (
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.
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:
© Adafruit Industries Page 11 of 25
@com! — D X \ H in! \ ocsan can 002: app-a, Ivoc: nppb Ienp:25.12 002: um. Ivoc: Bwb Im:z5.12 ooz: uppn, TVOC nppb mumzmu 002: 400mm. WOC: nwb Inn 5.12 wappn, Tvoc flppb Imp 5.45 wow-I. TVDC. nwb raw. 5.65 Inm- —m--: V;
Library Reference
To create the object, use
initialize the sensor with:
To poll the sensor for available data you can use:
Data can be read using:
and then the readings can be accessed with:
AMS recommends that you run this sensor for 48 hours when you first receive it to "burn it in", and then 20
minutes in the desired mode every time the sensor is in use. This is because the sensitivity levels of the
sensor will change during early use.
Adafruit_CCS811 ccs;
Serial.println("Failed to start sensor! Please check your wiring.");
bool dataAvailable = ccs.available(); //returns true if data is available to be read
bool error = ccs.readData(); //returns True if an error occurs during the read
© Adafruit Industries Page 12 of 25
Approximate ambient temperature can be read using:
int eCO2 = ccs.geteCO2(); //returns eCO2 reading
int TVOC = ccs.getTVOC(); //return TVOC reading
float temp = ccs.calculateTemperature();
© Adafruit Industries Page 13 of 25
* adafruit learning system
Arduino Library Docs
Arduino Library Docs (
© Adafruit Industries Page 14 of 25
* adafruit learning system on... mixing a...
Python &
It's easy to use the CCS811 sensor with Python or CircuitPython, and the 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 (
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 M0 to the sensor with I2C:
Board 3V to sensor VIN
Board GND to sensor GND
Board SCL to sensor SCL
Board SDA to sensor SDA
Board GND to sensor WAKE
Python Computer Wiring
Since there's
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 (
Here's the Raspberry Pi wired with I2C:
Pi 3V3 to sensor VIN
Pi GND to sensor GND
Pi SCL to sensor SCL
Pi SDA to sensor SDA
Pi GND to sensor WAKE
CircuitPython Installation of CCS811 Library
You'll need to install the Adafruit CircuitPython CCS811 ( library on your CircuitPython board.
First make sure you are running the latest version of Adafruit 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 ( Our CircuitPython starter guide has a great
© Adafruit Industries Page 15 of 25
page on how to install the library bundle (
For non-express boards like the Trinket M0 or Gemma M0, you'll need to manually install the necessary libraries from
the bundle:
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 ( 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 (!
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:
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:
import time
import board
import busio
import adafruit_ccs811
i2c_bus = busio.I2C(board.SCL, board.SDA)
ccs811 = adafruit_ccs811.CCS811(i2c_bus)
© Adafruit Industries Page 16 of 25
That's all there is to using CCS811 with Python and CircuitPython!
Full Example Code
print("CO2: %1.0f PPM" % ccs811.eco2)
print("TVOC: %1.0f PPM" % ccs811.tvoc)
print("Temp: %0.1f C" % ccs811.temperature)
import time
import board
import busio
import adafruit_ccs811
i2c = busio.I2C(board.SCL, board.SDA)
ccs811 = adafruit_ccs811.CCS811(i2c)
# Wait for the sensor to be ready
while not ccs811.data_ready:
while True:
print("CO2: {} PPM, TVOC: {} PPM"
.format(ccs811.eco2, ccs811.tvoc)
© Adafruit Industries Page 17 of 25
* adafruit learning system
Python Docs
Python Docs (
© Adafruit Industries Page 18 of 25
* adafruit learning system
Raspberry Pi Wiring &
The Raspberry Pi also has an I2C interface that can be used to communicate with this sensor.
Install Python Software
Once your Pi is all set up, and you have internet access set up, lets install the software we will need. First make sure
your Pi package manager is up to date
Next, we will install the Raspberry Pi library and Adafruit_GPIO which is our hardware interfacing layer
Next install the adafruit CCS811 python library.
Enable I2C
We need to enable the I2C bus so we can communicate with the sensor.
select Advanced options, enable I2C, and then
sudo apt-get update
sudo apt-get install -y build-essential python-pip python-dev python-smbus git
git clone
cd Adafruit_Python_GPIO
sudo python install
sudo pip install Adafruit_CCS811
sudo raspi-config
© Adafruit Industries Page 19 of 25
Once I2C is enabled, we need to slow the speed way down due to constraints of this particular sensor.
add this line to the file
sudo nano /boot/config.txt
© Adafruit Industries Page 20 of 25
press Ctrl+X, then Y, then enter to save and exit. Then run sudo shutdown -h now to turn off the Pi and prepare for
Wiring Up Sensor
With the Pi powered off, we can wire up the sensor to the Pi Cobbler like this:
Connect Vin to the 3V or 5V power supply (either is fine)
Connect GND to the ground pin on the Cobbler
Connect SDA to SDA on the Cobbler
Connect SCL to SCL on the Cobbler
Connect Wake to the ground pin on the Cobbler
You can also use direct wires, we happen to have a Cobbler ready. remember you can plug the cobbler into the
bottom of the PiTFT to get access to all the pins!
Now you should be able to verify that the sensor is wired up correctly by asking the Pi to detect what addresses it can
see on the I2C bus:
sudo i2cdetect -y 1
© Adafruit Industries Page 21 of 25
It should show up under it's default address (0x5A). If you don't see 5A, check your wiring, did you install I2C support,
Run example code
At long last, we are finally ready to run our example code
If everything is set up correctly, you should see it print out a few 0 readings, and then every few seconds it will print out
another reading
cd ~/
git clone
cd Adafruit_CCS811_python/examples
sudo python
© Adafruit Industries Page 22 of 25
* adafruit learning system e a o o mm mm" Nuusmxzs mm. w m: m M. a a 51% z m H? WW 1212m- m mm ma; use“ a" a Imz: m 4
CCS811 Datasheet (
CCS811 Fact sheet (
CCS811 Mechanical Considerations App Note (
CCS811 NTC Thermistor App Note (
CCS811 Baseline Clear/Restore App Note (
Adafruit CCS811 Arduino Driver (
CCS811 CircuitPython Driver (
Fritzing object in the Adafruit Fritzing library (
CCS811 breakout PCB files (EAGLE format) (
click to enlarge
in inches. Click to enlarge
© Adafruit Industries Page 23 of 25
008811 Gas Sensor
© Adafruit Industries Page 24 of 25
© Adafruit Industries Last Updated: 2019-07-17 06:48:41 PM UTC Page 25 of 25

Products related to this Datasheet