Page 1
Adafruit CCS811 Air Quality Sensor
Created by Dean Miller
https://learn.adafruit.com/adafruit-ccs811-air-quality-sensor
Last updated on 2021-11-15 06:59:27 PM EST
©Adafruit Industries Page 1 of 21
Page 2
Table of Contents
Overview
Pinouts
• Power Pins:
• Logic pins:
• Other Pins:
Assembly
• Prepare the header strip:
• Add the breakout board and Solder:
•
Arduino Wiring & Test
• I2C Wiring
• Download Adafruit_CCS811 library
• LoadTest Example
• Library Reference
Arduino Library Docs
Python & CircuitPython
• CircuitPython Microcontroller Wiring
• Python Computer Wiring
• CircuitPython Installation of CCS811 Library
• Python Installation of CCS811 Library
• CircuitPython & Python Usage
• Full Example Code
3
6
6
7
7
8
8
9
9
10
10
11
11
13
13
13
14
15
16
16
17
18
Python Docs
Downloads
• Documents
• Schematic and Fab Print for STEMMA QT Version
• Schematic and Fab Print for Original Version
FAQ
18
18
18
19
19
20
©Adafruit Industries Page 2 of 21
Page 3
Overview
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
SensorBreakout. This sensor from AMSis 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 21
Page 4
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 of400 to 8192 parts per million (ppm), and TVOC (Total Volatile
Organic Compound) concentration withina range of0 to 1187 parts per billion(ppb).
According to the fact sheet it can detectAlcohols, 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.
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.
©Adafruit Industries Page 4 of 21
Page 5
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 theSTEMMA QTform factor(https://adafru.it/LBQ), making
them easy to interface with. TheSTEMMA QT connectors(https://adafru.it/JqB)on
either side are compatible with theSparkFun Qwiic(https://adafru.it/Fpw)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 acompatible cable(https://adafru.it/JnB).
There are two versions of this board - the STEMMA QT version shown above, and
the original header-only version shown below. Code works the same on both!
©Adafruit Industries Page 5 of 21
Page 6
Pinouts
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
©Adafruit Industries Page 6 of 21
Page 7
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 isthe 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://adafru.it/Ft4)- These connectors allow you to connectors to
•
dev boards withSTEMMA QT connectors or to other things withvarious
associated accessories(https://adafru.it/Ft6)
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 readinggets 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 7 of 21
Page 8
Assembly
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 Industries Page 8 of 21
Page 9
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 ourGuide to Excellent
Soldering(https://adafru.it/aTk)).
You're done!
©Adafruit Industries Page 9 of 21
Page 10
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
ConnectVin (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
ConnectGND (black wire on
•
STEMMA QT version) to common
power/data ground
Connect theSCL (yellow wire on
•
STEMMA QT version) pin to the I2C
clockSCLpin on your Arduino.
On an UNO & '328 based Arduino,
this is also known asA5, on a Mega
it is also known asdigital 21and on
a Leonardo/Micro,digital 3
Connect theSDA (blue wire on
•
STEMMA QT version) pin to the I2C
data SDApin on your Arduino.
On an UNO & '328 based Arduino,
this is also known asA4, on a Mega
it is also known asdigital 20and on
a Leonardo/Micro,digital 2
NOT NEEDED FOR STEMMA QT
•
VERSION: Connect theWAKE pin to
ground on the original version only.
This sensor uses I2C address0x5A.
©Adafruit Industries Page 10 of 21
Page 11
Don't forget to tie WAKE to Ground - this is required on the original version of
this board only!
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:
Search for theAdafruit CCS811library and install it
We also have a great tutorial on Arduino library installation at:
http://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use(https://
adafru.it/aYM)
LoadTest Example
Open upFile->Examples->Adafruit_CCS811->CCS811_testand upload to your Arduino
wired up to the sensor. This example connects to the sensor and starts taking
readings.
©Adafruit Industries Page 11 of 21
Page 12
Once uploaded to yourArduino, 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:
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 12 of 21
Page 13
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();
Arduino Library Docs
Arduino Library Docs(https://adafru.it/Au8)
Python & CircuitPython
It's easy to use the CCS811 sensor with Python or CircuitPython, and the Adafruit
CircuitPython CCS811(https://adafru.it/yaX) module. This module allows you to easily
write Python code that reads the eCO2, TVOC and temperature from the sensor.
©Adafruit Industries Page 13 of 21
Page 14
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://adafru.it/BSN).
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 Industries Page 14 of 21
Page 15
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://adafru.it/BSN).
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 Industries Page 15 of 21
Page 16
CircuitPython Installation of CCS811 Library
You'll need to install theAdafruit CircuitPython CCS811(https://adafru.it/yaX)library on
your CircuitPython board.
First make sure you are running thelatest version of Adafruit CircuitPython(https://
adafru.it/Amd)for your board.
Next you'll need to install the necessary librariesto use the hardware--carefully follow
the steps to find and install these libraries fromAdafruit's CircuitPython library bundle
(https://adafru.it/uap). Our CircuitPython starter guide has a great page on how to
install the library bundle(https://adafru.it/ABU).
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 theadafrui
t_ccs811.mpy, and adafruit_bus_devicefiles and folderscopied over.
Nextconnect to the board's serial REPL(https://adafru.it/Awz) 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
://adafru.it/BSN)!
Once that's done, from your command line run the following command:
sudo pip3 install adafruit-circuitpython-ccs811
•
©Adafruit Industries Page 16 of 21
Page 17
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)
That's all there is to using CCS811 with Python and CircuitPython!
©Adafruit Industries Page 17 of 21
Page 18
Full Example Code
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import time
import board
import adafruit_ccs811
i2c = board.I2C() # uses board.SCL and board.SDA
ccs811 = adafruit_ccs811.CCS811(i2c)
# Wait for the sensor to be ready
while not ccs811.data_ready:
pass
while True:
print("CO2: {} PPM, TVOC: {} PPB".format(ccs811.eco2, ccs811.tvoc))
time.sleep(0.5)
Python Docs
Python Docs(https://adafru.it/C46)
Downloads
Documents
CCS811 Datasheet(https://adafru.it/yaV)
•
CCS811 Fact sheet(https://adafru.it/ycv)
•
CCS811 Mechanical Considerations App Note(https://adafru.it/ycw)
•
CCS811 NTC Thermistor App Note(https://adafru.it/ycx)
•
CCS811 Baseline Clear/Restore App Note(https://adafru.it/ycy)
•
Adafruit CCS811 Arduino Driver(https://adafru.it/yaW)
•
CCS811 CircuitPython Driver(https://adafru.it/yaX)
•
Fritzing object in the Adafruit Fritzing library(https://adafru.it/aP3)
•
CCS811 breakout PCB files (EAGLE format)(https://adafru.it/yaY)
•
©Adafruit Industries Page 18 of 21
Page 19
Schematic and Fab Print for STEMMA QT Version
Schematic and Fab Print for Original Version
click to enlarge
©Adafruit Industries Page 19 of 21
Page 20
FAQ
©Adafruit Industries Page 20 of 21
Page 21
My sensor is not reporting temperature correctly.
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.
©Adafruit Industries Page 21 of 21
Loading...