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 name | Adafruit SGP30 Sensor |
|---|---|
| Author | Adafruit |
| Include | #include <Adafruit_SGP30.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | Air 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.
- ESP32-C3
- Arduino Uno
- Arduino Nano
- Arduino Mega 2560
- Arduino Leonardo
- SparkFun Pro Micro
- Arduino Micro
- ESP32-C6
- WCH CH32V003
- Raspberry Pi Pico
- Raspberry Pi Pico W
- Seeed XIAO SAMD21
- STM32
- STM32 Nucleo-F411RE
- STM32 Blue Pill
- micro:bit V2
- Arduino Uno R4
- ESP32 DevKit
- ESP32-S3-DevKitC-1
- ESP8266 NodeMCU
- Arduino Pro Mini 3.3 V
- Seeed XIAO ESP32-C3
- ESP32-C3 SuperMini
- Seeed XIAO ESP32-C6
- ESP32-DevKitC V4
- LOLIN32 Lite
- Wemos D1 R32
- Cheap Yellow Display
- TTGO T-Display
- Seeed XIAO ESP32-S3
- ESP32-S3-CAM
- Arduino Nano ESP32
- Arduino Nano RP2040 Connect
- Seeed XIAO RP2040
- Waveshare RP2040-Zero
- Arduino Uno R4 WiFi
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.
// 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.
Keep going
Learn
Try Adafruit SGP30 Sensor without installing anything
Open the example, change the sketch, and keep your version in a free account.