How to Build a CO2 Room Monitor with ESP32

/*
 * CO2 Room Monitor
 * ESP32 + SCD41 (Sensirion I2C SCD4x driver) + SSD1306 OLED
 * Shared I2C bus on GPIO21 (SDA) / GPIO22 (SCL)
 *
 * Reads CO2, temperature, and humidity every 5 seconds.
 * Three status levels:
 *   < CO2_WARN_PPM   → "Air looks good"
 *   >= CO2_WARN_PPM  → "Air getting stale"
 *   >= CO2_ALERT_PPM → "OPEN A WINDOW" (inverted highlight)
 *
 * SCD41 needs ~2 minutes to stabilise after power-on;
 * a warm-up screen is shown until valid data arrives.
 */

#include <Wire.h>
#include <SensirionI2cScd4x.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

// ── Pin definitions (must match pin_definitions.json) ──────────────────────
#define SDA_PIN 21
#define SCL_PIN 22

// ── Display ────────────────────────────────────────────────────────────────
#define OLED_ADDRESS  0x3C
#define SCREEN_WIDTH  128
#define SCREEN_HEIGHT 64

// ── CO2 thresholds (ppm) — edit these for your space ──────────────────────
#define CO2_WARN_PPM  1000   // "stale" warning starts here
#define CO2_ALERT_PPM 1500   // stronger ventilation prompt

// ── Timing ─────────────────────────────────────────────────────────────────
#define READ_INTERVAL_MS  5000UL   // poll every 5 s (SCD41 cycle is 5 s)
#define WARMUP_MS        120000UL  // 2-minute sensor warm-up period

// ── Objects ────────────────────────────────────────────────────────────────
SensirionI2cScd4x sensor;
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);

// ── State ──────────────────────────────────────────────────────────────────
uint16_t co2        = 0;
float    tempC      = 0.0f;
float    humidity   = 0.0f;
bool     haveReading = false;

unsigned long lastReadMs = 0;

// ── Forward declarations ───────────────────────────────────────────────────
void drawWarmup();
void drawMonitorScreen();
void haltWithMessage(const char* serial_msg, const char* line1, const char* line2);

// ───────────────────────────────────────────────────────────────────────────

void setup() {
  Serial.begin(115200);
  delay(100);
  Serial.println("CO2 Room Monitor starting...");

  Wire.begin(SDA_PIN, SCL_PIN);

  // ── Init OLED ─────────────────────────────────────────────────────────
  if (!display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDRESS)) {
    // Can't show anything — just report on Serial and halt
    Serial.println("SSD1306 not found. Check OLED wiring and I2C address 0x3C.");
    while (true) delay(1000);
  }

  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.setTextSize(1);
  display.setCursor(0, 0);
  display.println("Starting CO2 sensor...");
  display.display();

  // ── Init SCD41 ────────────────────────────────────────────────────────
  sensor.begin(Wire, SCD41_I2C_ADDR_62);

  // Stop any in-progress measurement before reconfiguring
  uint16_t err = sensor.stopPeriodicMeasurement();
  if (err) {
    // Non-fatal: sensor may have just powered on with no active measurement
    Serial.print("stopPeriodicMeasurement warning: ");
    Serial.println(err);
  }
  delay(500); // brief settle after stop

  err = sensor.startPeriodicMeasurement();
  if (err) {
    char msg[64];
    snprintf(msg, sizeof(msg),
             "SCD41 not found — check wiring on GPIO%d/%d (err %u)",
             SDA_PIN, SCL_PIN, err);
    haltWithMessage(msg, "SCD41 not found", "Check I2C wiring");
  }

  Serial.println("SCD41 started. Warming up (~2 min)...");
  drawWarmup();
}

void loop() {
  unsigned long now = millis();

  // Show warm-up screen until the 2-minute stabilisation period is over
  // and we have at least one valid reading.
  if (!haveReading && now < WARMUP_MS) {
    drawWarmup();
    delay(1000);
    return;
  }

  // Poll on 5-second interval
  if (now - lastReadMs < READ_INTERVAL_MS) {
    return;
  }
  lastReadMs = now;

  // Check whether a new measurement is ready
  bool dataReady = false;
  uint16_t err = sensor.getDataReadyStatus(dataReady);
  if (err) {
    Serial.print("getDataReadyStatus error: ");
    Serial.println(err);
    return;
  }
  if (!dataReady) {
    return; // not ready yet — wait for the next poll
  }

  uint16_t newCo2   = 0;
  float    newTemp  = 0.0f;
  float    newHumid = 0.0f;

  err = sensor.readMeasurement(newCo2, newTemp, newHumid);
  if (err) {
    Serial.print("readMeasurement error: ");
    Serial.println(err);
    return;
  }
  // SCD41 returns 0 ppm if calibration hasn't finished; skip it
  if (newCo2 == 0) {
    return;
  }

  co2       = newCo2;
  tempC     = newTemp;
  humidity  = newHumid;
  haveReading = true;

  Serial.print("CO2: ");
  Serial.print(co2);
  Serial.print(" ppm  Temp: ");
  Serial.print(tempC, 1);
  Serial.print(" C  Humidity: ");
  Serial.print(humidity, 0);
  Serial.println(" %RH");

  drawMonitorScreen();
}

// ── Display helpers ─────────────────────────────────────────────────────────

void drawWarmup() {
  unsigned long elapsed  = millis() / 1000;
  int           remaining = max(0L, (long)(WARMUP_MS / 1000) - (long)elapsed);

  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);

  display.setTextSize(1);
  display.setCursor(0, 0);
  display.println("Room CO2 monitor");
  display.drawLine(0, 11, 127, 11, SSD1306_WHITE);

  display.setCursor(0, 18);
  display.println("Sensor warming up...");

  display.setCursor(0, 34);
  display.print("Ready in ~");
  display.print(remaining);
  display.println(" s");

  display.setCursor(0, 50);
  display.setTextSize(1);
  display.println("Keep room aired out");

  display.display();
}

void drawMonitorScreen() {
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);

  // ── Header ──────────────────────────────────────────────────────────
  display.setTextSize(1);
  display.setCursor(0, 0);
  display.println("Room CO2 monitor");
  display.drawLine(0, 11, 127, 11, SSD1306_WHITE);

  // ── CO2 reading (large) ─────────────────────────────────────────────
  display.setTextSize(2);
  display.setCursor(0, 14);
  display.print(co2);
  display.println(" ppm");

  // ── Temp + humidity (small) ──────────────────────────────────────────
  display.setTextSize(1);
  display.setCursor(0, 38);
  display.print(tempC, 1);
  display.print((char)247); // degree symbol
  display.print("C  ");
  display.print(humidity, 0);
  display.println("%RH");

  // ── Status line ──────────────────────────────────────────────────────
  display.setCursor(0, 54);
  if (co2 >= CO2_ALERT_PPM) {
    // Inverted highlight to grab attention
    display.fillRect(0, 52, 128, 12, SSD1306_WHITE);
    display.setTextColor(SSD1306_BLACK);
    display.setCursor(4, 54);
    display.print("Open a window now!");
    display.setTextColor(SSD1306_WHITE);
  } else if (co2 >= CO2_WARN_PPM) {
    display.print("Getting stale - crack a window");
  } else {
    display.print("Air is fresh");
  }

  display.display();
}

/*
 * Show an error on both Serial and the OLED, then halt.
 * line1 / line2: short OLED strings (<=21 chars each).
 */
void haltWithMessage(const char* serial_msg,
                     const char* line1,
                     const char* line2) {
  Serial.println(serial_msg);
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.setTextSize(1);
  display.setCursor(0, 0);
  display.println(line1);
  display.setCursor(0, 14);
  display.println(line2);
  display.display();
  while (true) delay(1000);
}

// Run this and build other cool things at schematik.io