Hardware Hump Day: Air Quality Measurements with the CCS811

Wherein we seek to answer the age old question: What the heck is a VOC?

Favorited Favorite 2

If you've been keeping up with the stream of experimental products coming out of SparkX over the past several months, you may have recently seen the CCS811 Air Quality Breakout go by. The CCS811 is a tiny part that reports air quality as a function of the total Volatile Organic Compounds (VOCs) detected. We thought this was a pretty cool part, so this week it earns its wings as a full-fledged SparkFun storefront product. To celebrate, I threw together a little project and did some research on VOCs and "CO2 Equivalent Units."

alt text

What's a VOC?

Volatile organic compounds are more or less what they say they are: organic (carbon-containing) compounds that exhibit the property of volatility. Substances can be said to be volatile if they have a very low boiling point, and therefore tend to readily escape into the air at room temperature. The term encompasses a pretty huge collection of materials, including several produced by the human body — every time you exhale, you produce VOCs. Most of the scents and odors that you smell are VOCs, and although many are harmless in normal concentrations, there are also many that are harmful to people and/or the environment.

Day to day, we encounter the highest concentrations of VOCs indoors. Paint, carpets, cleaning materials, machines, people and pets all contain and release VOCs and they tend to accumulate in enclosed spaces without proper ventilation. Human-made (or anthropogenic) VOCs are regulated by law for just this reason.

The health effects of VOCs can be difficult to study because they tend to cause cumulative damage over years of moderate exposure. They don't pose a significant health risk for normal people living in homes with proper ventilation, but indoor air quality is something worth thinking about. Some specialized HVAC systems even contain sensors to detect rising VOC levels and turn on fresh-air ventilation or air scrubbers.

The legal definition of VOCs, on the other hand, can be harder to nail down. They tend to encompass only a subset of chemically-defined VOCs and vary from country to country depending on the purpose of the legislation where the definition is found. In the US, for instance, many legal definitions of VOCs are concerned specifically with environmental precursors to smog, whereas in Canada the emphasis is placed more widely on substances affecting air quality.

CO2 Equivalent Units

One measurement that causes a lot of confusion is "Equivalent CO2." The CCS811 will report equivalent CO2 in parts-per-million, but that number can be a little bit deceptive. It's important to recognize that the CCS811 cannot measure CO2 and that the "equivalent CO2" being reported by the CCS811 has nothing to do with actual CO2 present in the area. So why the heck is it called "CO2 Equivalent Units" and why would anyone need it? The answer comes down to the use of indoor air quality sensors — like the CCS811 — in HVAC control.

Building ventilation, it turns out, is all about occupancy. The more people present in a space, the more CO2 they're exhaling, and the more ventilation is required. Now, it's certainly possible to design and operate an HVAC system around the design occupancy of a building or room, in other words the number of people expected to use a space. But this means that you may be wasting energy at times when the building isn't actually occupied. To solve this problem, many HVAC systems will monitor the concentration of CO2 in a given area in order to calculate the amount of air exchange needed in a scheme called "demand-controlled ventilation."

Makers of indoor air quality sensors that don't detect CO2 (in an attempt to market their devices for demand-controlled ventilation systems) have correlated rising CO2 levels in certain environments to rising VOC levels. It's important to recognize that this is a correlation of the change in levels and not a correlation of the levels themselves: High VOC concentrations are not analogous to high CO2 concentrations. But it can be said that if the VOC concentration of a given space begins to slowly climb above baseline, it probably corresponds to room occupancy and an increase in CO2 (because humans exhale both CO2 and VOCs). Therefore, the manufacturers of these devices report the "CO2 Equivalent Units" with respect to this correlation so that their devices might fit more easily into an existing demand-controlled ventilation scheme.

In my limited research, HVAC experts tend to suggest using real IR-based CO2 sensors in situations where people's health may be at risk. This doesn't mean, however, that VOC sensors are unsafe in properly designed systems, or that they don't have a place alongside CO2 sensors in smart ventilation systems. For instance, VOC sensors can react quickly to non-occupant-related VOC sources and leaking environmental contaminants.

Pocket Air Quality Sensor

To play with this new sensor, and to put myself in the shoes of a ventilation controller, I decided to build a portable readout for the air quality sensor and take it for a walk around the office. To display the readings taken by the CCS811, I used a MicroView, which acted both as the display and the controller to talk to the sensor. The circuit for my project is essentially identical to the one outlined in this tutorial, but I exchanged the MAG3110 magnetometer for the CCS811. As for the code, I simply modified our example code for the CCS811 to include the MicroView library, and used the OLED to print the output values instead of the serial port. If you want to build your own, here's a list of the parts that I used besides the sensor itself:

SparkFun Logic Level Converter - Bi-Directional

SparkFun Logic Level Converter - Bi-Directional

Jumper Wire Kit - 140pcs

Jumper Wire Kit - 140pcs

Lithium Ion Battery - 850mAh

Lithium Ion Battery - 850mAh

SparkFun Solder-able Breadboard

SparkFun Solder-able Breadboard

Break Away Headers - Straight

Break Away Headers - Straight

SparkFun MicroView - OLED Arduino Module

SparkFun MicroView - OLED Arduino Module

SparkFun MicroView - USB Programmer

SparkFun MicroView - USB Programmer


SparkFun Power Cell - LiPo Charger/Booster

14 Retired

And here's what the code looks like after modification:

  CCS811 Air Quality Sensor Example Code
  By: Nathan Seidle
  SparkFun Electronics
  Date: February 7th, 2017
  Modified By: Nick Poole (for use with MicroView)
  License: This code is public domain but you buy me a beer if you use this 
  and we meet someday (Beerware license).

  Works with SparkFun CCS811 board https://www.sparkfun.com/products/14181
  Or Combo board https://www.sparkfun.com/products/14241
  Enjoy this code? Buy a board and help support SparkFun! 

  Read the TVOC values from the SparkFun CSS811 breakout board and display 
  them on the MicroView.

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


#include <MicroView.h>    
#include <Wire.h>

//These are the air quality values obtained from the sensor
unsigned int tVOC = 0;
unsigned int CO2 = 0;

void setup()
  uView.begin();        // start MicroView
  uView.clear(PAGE);      // clear page
  uView.print("CCS811 Read Example");


  if (configureCCS811() == false)
    uView.print("Problem with CCS811");
    uView.print("CCS811 online");

void loop()
  if (dataAvailable())
    readAlgorithmResults(); //Calling this function updates the global tVOC and CO2 variables

    uView.print("tVOC: ");

  else if (checkForError())

  delay(1000); //Wait for next reading

And what did we learn?

Well, the obvious, really. But before I show you the few readings that I took, there's something I want to point out. You may have noticed in the comments of the code above that this sensor requires a 48-hour "burn in" period when it's first installed. Beyond that, every time the sensor is powered on, it requires 20 minutes of "run-in" before the readings are considered usable. At the time that these pictures were taken, the sensor had only burned in for about 15 hours so the readings aren't necessarily accurate. That said, the relationship of the readings to one another is still pretty telling.

Here's the sensor sitting inside our office, actually in our production area. I found that readings within the building didn't vary that widely, probably due to the ventilation system.

A picture of the sensor display in our production area

It may be hard to make out but we're reading 532 ppb here. Again, that's probably not accurate, so this number on its own isn't that interesting until we compare it to the sensor outside just moments later:

A picture of the sensor display outdoors

Here you can see that we're reading only 179 ppb just outside the building. That's about a third of what we measured inside. Pretty cool! But what can we do to push the sensor in the other direction? Oh wait, I know a place chock full of VOCs...

A picture of the sensor display in a paint cabinet

What you're looking at now is the sensor sitting inside the open door of the Flammable Materials cabinet under my desk. This cabinet has become a storage place for "smelly" materials, flammable or not, and contains things like paints, glues, stains, resins and cleaners... basically all of the household products that contain high concentrations of VOCs. What the sensor says is 1156 ppb, but it hit 1156 and stayed there, taking a minute to recover even after being removed from the cabinet. Referring to the datasheet, we can see that the sensor is supposed to measure concentrations up to around 1187, so it's probably safe to assume that we saturated the heck out of this sensor. After all, the range of the CCS811 is calibrated to the typical VOC mixture of an indoor environment and my paint cabinet is not a typical indoor environment.


I really enjoyed playing with the CCS811 and I think it's probably useful for a lot of applications from quantified living to home automation. It's easy to use and takes very little power to operate. The only downside is the long run-in period, but that's common for sensors of this type. If you're interested in measuring indoor air quality, I definitely recommend picking up one of these breakouts, which you can do Friday, and playing with them. Thanks for reading and feel free to reach out in the comments with any questions or suggestions!

Comments 8 comments

  • Member #501876 / about 6 years ago / 1

    How could the readings be integrated to a building automation system? What is the readout data protocol? Could the reading be converted to a 0 to 10v reading?

  • Member #322125 / about 7 years ago / 1

    Couple questions - 1 - What was the example code you changed to use the OLED? 2 - Is there code to run the OLED with the BME280Compensated?

    I picked these parts up since I have severe sensitivities to VOCs and wanted something to put on my desk to watch for the air quality at work to worsen. Sometimes there is chemical usage in other parts of the building and I wanted to catch it rising at my desk before I wind up in the ER again.

    However, this is only my second venture into Arduinoland and I'm a little lost. I have a bit of C# experience but it doesn't seem to be helping here.


  • MysterELane / about 7 years ago / 1

    Hi Nick -

    In some of the breakout guide info, it describes hooking the Sensor up to the SCL and SDA pins on the Arduino. It talks about how you can then put this sensor in series with the BME atmospheric sensor (which I have on order) to get readings from both.

    However, the code provided, the sensor needs to be on Analog pins. Will the BME still work in series with the CCS811 if its on the analog ports?

  • tinkergirl / about 7 years ago / 1

    I love this. Any chance of Sparkfun selling a separate formaldehyde sensor that can be added on to this setup? Sometimes it's handy to separate formaldehyde from TVOC.

  • Member #403238 / about 7 years ago / 1

    A few other areas that might be of interest: - New car smell - Starbucks lobby - Area near the perfume counter in a department store

  • xsk8rat / about 7 years ago / 1

    Nice post! This sensor (and the SparkX cousin) did look to be of interest. Keep in mind that high VoCs can also affect resistive humidity sensors. The VOC compounds can bind to the coated elements in the detector.

    Some commercial humidity probes become saturated with acetone in our production area at work (at levels of ten+ of parts per million). An hour in that environment and i had to redo run-in and calibration. We plan to try capacitive sensors in that room now.


  • ameyring / about 7 years ago / 1

    Interesting sensor. I wonder how the VOC readings would compare to those of the Grove gas sensors by Seeedstudio or Adafruit's MiCS5524 gas sensor. It's nice to have many options.

Related Posts

Recent Posts

Why L-Band?


All Tags