Skip to content

CCS811

Works with

Any CircuitPython board with I2C

Discontinued

The CCS811 is no longer in production. For new projects, use the SGP40 or ENS160 instead. This page is kept for projects built with existing CCS811 hardware.

What it does

The CCS811 measures estimated CO2 (eCO2) from 400 to 8192 ppm and total volatile organic compounds (TVOC) from 0 to 1187 ppb. Note that eCO2 is a calculated estimate derived from the VOC measurement — it is not a direct CO2 measurement like a photoacoustic sensor provides. The sensor requires a ~20-minute burn-in period the first time it is used before readings become reliable. Common applications were indoor air quality monitors and CO2 level alerts.

Installing the library

Copy adafruit_ccs811.mpy from the Adafruit CircuitPython Bundle to your board's lib/ folder. Also copy adafruit_bus_device/ if it is not already present.

Quick start

import board
import busio
import adafruit_ccs811

i2c = busio.I2C(board.SCL, board.SDA)
sensor = adafruit_ccs811.CCS811(i2c)

# Wait until the sensor has valid data
while not sensor.data_ready:
    pass

print(sensor.eco2)
print(sensor.tvoc)

Key things you can do

What you want How to do it
Check if data is ready sensor.data_ready (poll before reading)
Read eCO2 (ppm) sensor.eco2
Read TVOC (ppb) sensor.tvoc
Check for errors sensor.error and sensor.error_code

Reading the official docs

https://docs.circuitpython.org/projects/ccs811/en/latest/

Always check data_ready before reading eco2 or tvoc — the sensor updates at a fixed interval (1 second by default) and reading before data is ready returns stale values.

Projects using this library