Parts

CCS811 air quality sensor

The ams CCS811 on the CJMCU-811 board reports equivalent CO2 (eCO2) and TVOC over I2C at 0x5A.

Aliases: CJMCU-811, CCS811 breakout, Adafruit CCS811, SparkFun CCS811, eCO2 sensor, TVOC sensor. A tiny metal-oxide gas sensor with its own microcontroller inside. It heats a sensing layer, watches its resistance change as volatile organic compounds (VOCs) drift past, and works out two numbers: TVOC, the total VOCs in parts per billion, and eCO2, the carbon dioxide level in parts per million that people breathing would produce along with them. It does not measure CO2 itself: for that you need an NDIR sensor such as the SCD40.

Pins

Pin What it does
VCC Supply, 3.3 V. The chip runs from 1.8 to 3.6 V and this board has no regulator.
GND Ground.
SCL, SDA I2C. The board carries the pull-ups.
WAK nWAKE, active low. The chip only listens while it is low: tie it to GND, or to a pin you hold low while you talk to it. Left unwired, nothing answers.
INT nINT, an open-drain output that goes low when a sample is ready (or crosses a threshold), if the sketch asks.
RST nRESET, active low; pulled up inside the chip, so it can stay unwired.
ADD The address: low (the board's pull-down) is 0x5A, high is 0x5B.

Properties

eco2 (ppm, 400 to 8192) and tvoc (ppb, 0 to 1187) are the air, the chip's output range. The two sliders change them while the circuit runs, and the next sample reports them.

Reading it on an Arduino

With Adafruit's library, which Mokxi ships as Adafruit_CCS811.h:

#include <Wire.h>
#include "Adafruit_CCS811.h"

Adafruit_CCS811 ccs;

void setup() {
  Serial.begin(9600);
  if (!ccs.begin()) {           // 0x5A; begin(0x5B) with ADD high
    Serial.println("No CCS811");
    while (1) {}
  }
  while (!ccs.available()) {}   // the first sample, a second later
}

void loop() {
  if (ccs.available() && ccs.readData() == 0) {
    Serial.print(ccs.geteCO2());
    Serial.print(" ppm eCO2, ");
    Serial.print(ccs.getTVOC());
    Serial.println(" ppb TVOC");
  }
  delay(250);
}

readData() returns 0 when it worked. The gallery's CCS811 air quality example prints both every second.

How it talks

  • After power on the chip answers in 20 ms, in boot mode: STATUS (0x00) reads 0x10 (a valid application is loaded) and HW_ID (0x20) reads 0x81.
  • Writing the register address 0xF4 (APP_START) and nothing else starts the application: STATUS gains FW_MODE and reads 0x90.
  • MEAS_MODE (0x01) picks the drive mode: 0 idle, 1 a sample every second, 2 every 10 s, 3 every 60 s, 4 raw data every 250 ms. Bit 3 asks for nINT on each sample, and bit 2 only when eCO2 moves into another range set in THRESHOLDS (0x10).
  • At each sample DATA_READY (bit 3 of STATUS) is set. ALG_RESULT_DATA (0x02) is eight bytes: eCO2 and TVOC, high byte first, then STATUS, ERROR_ID and the raw data. Reading it clears DATA_READY and lets nINT go.
  • Registers are mailboxes: the address does not step on, so a burst read gets the bytes of one register in order.
  • ENV_DATA (0x05) takes the humidity and temperature for compensation, BASELINE (0x11) saves and restores the baseline, and SW_RESET (0xFF with 11 E5 72 8A) goes back to boot mode.
  • A bad register, or a drive mode above 4, sets ERROR in STATUS and a bit in ERROR_ID (0xE0).

What it does not model

The gas chemistry. The readings are the sliders, sample by sample; the 48 hour burn-in, the 20 minute run-in, the automatic baseline correction and the temperature and humidity compensation are not simulated (ENV_DATA and BASELINE keep what is written). RAW_DATA is a fixed stand-in, NTC reads zero, and the heater faults, the firmware download and the ten minutes of idle the datasheet asks for before a slower mode are not checked. Too much voltage on VCC does no damage here.

Common mistakes

Leaving WAK unwired: the chip ignores the bus until nWAKE is low. Powering it from 5 V: the CJMCU-811 has no regulator, and the chip's limit is 3.6 V. Reading as fast as the loop goes: there is a new sample once a second in mode 1, so wait for available(). Trusting the first readings on a real sensor: it needs 20 minutes to settle, and 48 hours when it is new.