Arduino library · Sensors

Adafruit SGP30: equivalent CO2 and TVOC on Arduino

Yes. You can use the Adafruit SGP30 Sensor library online in Mokxi with nothing to install, and the sketch runs in your browser against the simulated part (Air quality sensor, SGP30). The example below, "Air quality monitor", runs on the Arduino Uno R3.

Built in on Mokxi: #include <Adafruit_SGP30.h> and it builds, with nothing to install. Free, and no account needed.

What Adafruit SGP30 Sensor does

The SGP30 is Sensirion’s metal-oxide gas sensor for indoor air monitors. It reports total volatile organic compounds (TVOC) in parts per billion and an equivalent CO2 (eCO2) in parts per million. That second figure needs care: the chip does not measure carbon dioxide. It estimates it from other gases it does sense, which follows people breathing in a closed room but also jumps for cooking, cleaning sprays or a marker pen.

begin() reads the serial number, checks the chip really is an SGP30 and starts the on-chip air quality algorithm. For the first 15 seconds after that the sensor reports a flat 400 ppm and 0 ppb while its hot plate warms. From then on it wants IAQmeasure() once a second, because the algorithm’s baseline assumes that rhythm; getIAQBaseline() and setIAQBaseline() let a sketch save the baseline and put it back after a reset.

setHumidity() makes the readings more accurate but takes absolute humidity in milligrams per cubic meter, not percent. Adafruit’s example converts with exp(), which does not link in Mokxi, so the air quality monitor below uses an SHT31 and a small lookup table instead. In Mokxi the sgp30 part sets eCO2 and TVOC on sliders, and softReset() returns true without resetting anything.

Library Manager nameAdafruit SGP30 Sensor
AuthorAdafruit
Include#include <Adafruit_SGP30.h>
Boardsevery board Mokxi compiles for but ATtiny85
In the simulatorSimulated: it runs against the part the way it does on the bench.
Parts it drivesAir quality sensor, SGP30

Install it

It builds on every board Mokxi compiles for but ATtiny85.

In Mokxi it is built in: #include <Adafruit_SGP30.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "Adafruit SGP30 Sensor" by Adafruit from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add Adafruit SGP30 Sensor to lib_deps in PlatformIO. Mokxi follows the calls of release 2.0.3, so a sketch written here builds there too.

The calls you will use

In the order a sketch meets them.

Adafruit_SGP30 sgp

Creates the driver. The sensor’s address, 0x58, cannot be changed.

sgp.begin()

Reads the serial number into sgp.serialnumber, checks the feature set and starts the algorithm. Returns false if any step fails.

sgp.IAQmeasure()

Takes one reading into sgp.eCO2 (ppm) and sgp.TVOC (ppb) and returns false when the read failed. Call it every second.

if (sgp.IAQmeasure()) {
  Serial.print(sgp.eCO2);
  Serial.print(" ppm  ");
  Serial.println(sgp.TVOC);
}

sgp.IAQmeasureRaw()

Reads the raw hydrogen and ethanol signals into sgp.rawH2 and sgp.rawEthanol, for your own analysis.

sgp.getIAQBaseline(&eco2Base, &tvocBase)

Reads the algorithm’s current baseline pair, to store in EEPROM once the sensor has been running a long while.

sgp.setIAQBaseline(eco2Base, tvocBase)

Restores a saved baseline after begin(), so the readings settle without starting the learning over.

sgp.setHumidity(8000)

Absolute humidity in mg/m3. 0 switches compensation off, and anything above 256000 is refused with false.

Example: Air quality monitor

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3
// Air quality monitor: an SGP30 gas sensor, an SHT31 thermometer and an
// HT16K33 four-digit LED display share the I2C bus, the way a home-built CO2
// monitor is made.
//
//   SGP30, SHT31, display   SDA -> A4   SCL -> A5   VIN or VCC -> 5 V   GND -> GND
//   red LED                 pin 8 through 220 ohms
//
// The SGP30 reads 400 ppm and 0 ppb for its first 15 seconds while its hot
// plate warms up, so the display counts that down after "--". Then it takes
// turns: the CO2eq in ppm for four seconds, the temperature ("23*C") and the
// humidity ("45rh") for one each. Above 1000 ppm, where a room wants a
// window opening, the red LED comes on and the display blinks.
//
// The SHT31's humidity makes the SGP30 more accurate: the sensor wants it as
// milligrams of water in a cubic meter of air, which is worked out here from
// a table of how much water air can hold, because this board has no exp().
//
// Drag the sliders on the two sensors and watch the display follow.

#include <Wire.h>
#include "Adafruit_LEDBackpack.h"
#include "Adafruit_SHT31.h"
#include "Adafruit_SGP30.h"

const int ALERT_LED = 8;
const uint16_t ALERT_PPM = 1000;

// Segments for the units: A is bit 0, G is bit 6.
const uint8_t DEGREE = 0x63;
const uint8_t LETTER_C = 0x39;
const uint8_t LETTER_R = 0x50;
const uint8_t LETTER_H = 0x74;

Adafruit_7segment display = Adafruit_7segment();
Adafruit_SHT31 sht31 = Adafruit_SHT31();
Adafruit_SGP30 sgp;

// How much water saturated air holds, in mg per cubic meter, at 0, 5, 10 ...
// 50 degrees Celsius.
const uint32_t SATURATION[] = {4847, 6797, 9399, 12830, 17300, 23050,
                               30380, 39630, 51120, 65330, 82770};

uint32_t absoluteHumidity(int32_t centiC, int32_t centiRh) {
  if (centiC < 0) centiC = 0;
  if (centiC > 4999) centiC = 4999;
  uint8_t i = centiC / 500;
  uint32_t frac = centiC % 500;
  uint32_t sat = SATURATION[i] + (SATURATION[i + 1] - SATURATION[i]) * frac / 500;
  return sat * (uint32_t)centiRh / 10000;
}

// Two digits on the left, two unit segments on the right.
void showWithUnit(int32_t value, uint8_t left, uint8_t right) {
  display.print(value * 100, DEC);
  display.writeDigitRaw(3, left);
  display.writeDigitRaw(4, right);
}

unsigned long started;
uint8_t tick = 0;
bool alarm = false;

void setup() {
  pinMode(ALERT_LED, OUTPUT);
  display.begin(0x70);
  display.setBrightness(10);
  if (!sht31.begin(0x44) || !sgp.begin()) {
    // "Err": a sensor did not answer.
    display.writeDigitRaw(0, 0x79);
    display.writeDigitRaw(1, LETTER_R);
    display.writeDigitRaw(3, LETTER_R);
    display.writeDisplay();
    while (1) delay(10);
  }
  started = millis();
}

void loop() {
  bool climate = sht31.measure();
  int32_t centiC = sht31.getTemperatureCentis();
  int32_t centiRh = sht31.getHumidityCentis();
  if (climate) sgp.setHumidity(absoluteHumidity(centiC, centiRh));
  if (!sgp.IAQmeasure()) {
    delay(1000);
    return;
  }

  unsigned long seconds = (millis() - started) / 1000;
  tick = (tick + 1) % 6;
  if (seconds < 15) {
    display.print(15 - seconds, DEC);
    display.writeDigitRaw(0, 0x40);
    display.writeDigitRaw(1, 0x40);
  } else if (tick == 4) {
    showWithUnit((centiC + 50) / 100, DEGREE, LETTER_C);
  } else if (tick == 5) {
    showWithUnit((centiRh + 50) / 100, LETTER_R, LETTER_H);
  } else {
    display.print(sgp.eCO2, DEC);
  }
  display.writeDisplay();

  bool high = seconds >= 15 && sgp.eCO2 >= ALERT_PPM;
  if (high != alarm) {
    alarm = high;
    display.blinkRate(alarm ? HT16K33_BLINK_1HZ : HT16K33_BLINK_OFF);
  }
  digitalWrite(ALERT_LED, alarm ? HIGH : LOW);

  // One measurement a second, as the SGP30's baseline algorithm wants.
  delay(1000 - 70);
}

Open it in the editor, wired and ready to run · Air quality monitor: the project page

Common errors and how to fix them

eCO2 stays at 400 and TVOC at 0

For the first 15 seconds after begin() that is the warm-up and expected. If it lasts longer, IAQmeasure() is not being called every second, and the algorithm only advances with each measurement.

Sensor not found :(

Nothing answered at 0x58, or the chip there reported a different feature set. An SGP40 or SGP41 uses other commands and needs its own library; check the module’s marking and the bus wires.

Adafruit’s getAbsoluteHumidity() helper will not build in Mokxi

It calls exp(), which the Mokxi build does not link. Copy the integer table from the air quality monitor project, or pass a fixed value to setHumidity() if the room’s humidity barely changes.

eCO2 shoots up when someone sprays deodorant, with nobody breathing nearby

That is the chip working as designed: alcohol counts as a volatile compound and pushes the estimate up. For carbon dioxide itself use a sensor that measures it, such as the SCD40 or SCD41.

Questions and answers

Is the SGP30’s eCO2 a real CO2 measurement?

No. It is an estimate from the gases a metal-oxide plate reacts to. It tracks a stuffy room well enough to prompt opening a window, but it is not a CO2 reading.

Why does the air quality monitor wait about a second between readings?

The SGP30’s baseline algorithm is designed around one measurement a second, so the sketch delays the rest of each second after its work is done.

Try Adafruit SGP30 Sensor without installing anything

Open the example, change the sketch, and keep your version in a free account.