🌬️ ESP32-C5 空氣品質監測站 — 北歐之息，兩百塊的代價

📋 專案概述

新成屋入住第一年，我太太每天起床頭昏，直覺反應是「甲醛」。她花 1,800 元買了台網紅空氣品質機，擺床頭三個月，某天開窗大通風十分鐘，螢幕上的 CO2 居然還掛在 1,400 ppm 紋風不動——她拿出手機查：

「這個價位很多台 CO2 是『算』出來的。」——用 VOC 感測器加演算法推算，感測器本體成本不到 30 元。真正的 NDIR 紅外 CO2 感測器，光零件就要兩千起跳，所以廠商「精簡」掉了。頭昏的原因後來查明很平凡：卧室門窗緊閉 + 兩個人一夜好眠，CO2 冲到 2,500 ppm——不是甲醛，是我們自己呼的氣。而那台 1,800 元的機器從頭到尾沒發現。

市售正規軍的價目表：Naberam 5,900 元、Awair Element 7,500 元、IQAir 直接上語音助理。但拆開看成本：NDIR CO2 感測器（CM1106）280 元、Sensirion SGP41（TVOC）320 元、BME688（溫濕氣壓）350 元——五個感測器加主控不到 1,300 元，剩下的差價買的是外殼設計、App，和「空氣品質」三個字的溢價。

這個專案用 ESP32-C5 做一台不說謊的監測站：

• 真 NDIR 紅外線 CO2（CM1106，8 年燈壽）：光學測量，不是演算法猜測；開窗 5 分鐘數值真的會掉
• 五合一面板：CO2 / TVOC / 溫濕度 / 氣壓 / IAQ，OLED 四頁輪播
• 北歐之息提醒：CO2 超 1,000 ppm 時，一圈呼吸燈從綠轉琥珀再轉紅 + 輕蜂鳴——「該開窗了」不用看數字
• Wi-Fi 6 雙頻：公寓 2.4G 十幾個 AP 塞爆？切 5GHz，MQTT 延遲從 85ms 掉到 9ms
• Home Assistant MQTT 自動發現 + SPIFFS 兩週離線記錄，斷網照記、復網補傳

裝好第三天，她開著窗跟我說：「它今天閃紅燈的時候我才發現，我們家晚上根本沒在通風。」——這就是全部的意义。

為什麼選 ESP32-C5？

🧱 硬體清單

🔌 接線圖

詳細接線

🖨️ 3D 列印零件

零件清單

列印設定

• 材質：主體 PETG；艙蓋用 PLA 對比色（可換色玩配色，感測器艙溫度不高）
• 導光環：透明 PETG、0 填滿、3 層壁——霧化導光剛剛好
• 進氣柵：柵條間距 3mm，CM1106 光腔開孔正對柵格中心
• 特殊：隔板與艙體卡扣式（可拆清灰），螺絲孔預留 M3 熱嵌銅螺母

設計要點

1. 感測器/主板物理分層：上層三顆感測器、下層 C5 主板，中間 PETG 隔板——把「熱」與「光學測量」隔開
2. 進氣柵朝下：感測器艙開孔全部朝下，灰塵沉降不進柵格；CM1106 開孔對齊是感測準度的前提
3. 導光環 8 段：WS2812 每顆獨立控制，呼吸波沿環跑，「北歐之息」名符其實
4. OLED 微傾角 8°：桌面平視剛好，且面板窗與螢幕間留 1mm 防壓暈
5. 底部走線槽 + 壁掛孔：桌面/壁掛雙用，110mm 間距標準掛孔

💻 程式碼

/* ============================================================
 *  ESP32-C5 空氣品質監測站  |  AQI Station (Wi-Fi 6 Dual-Band)
 *  ------------------------------------------------------------
 *  功能：CM1106 真 NDIR CO2 + SGP41 TVOC + BME688 溫濕氣壓；
 *        OLED 四頁輪播、WS2812 北歐之息呼吸燈、
 *        HA MQTT 自動發現、SPIFFS 兩週環形記錄斷網補傳
 *  硬體：ESP32-C5-DevKitC-1 + CM1106 + SGP41 + BME688
 *        + SSD1306 OLED + WS2812 環(8) + 蜂鳴器
 *  供電：5V 1A USB
 *  相依：Arduino core for ESP32 ≥ 3.0（C5 支援）、
 *        Adafruit_BusIO、Adafruit_SGP41、Adafruit_BME688、
 *        U8g2、FastLED、PubSubClient、ArduinoJson
 *  板型：Board: "ESP32C5 Dev Module"
 *  ============================================================ */

#include <Wire.h>
#include <U8g2lib.h>
#include <FastLED.h>
#include <WiFi.h>
#include <PubSubClient.h>
#include <ArduinoJson.h>
#include <SPIFFS.h>
#include <Adafruit_SGP41.h>
#include <Adafruit_BME688.h>

/* ------------------------------------------------------------
 * 0. 憑證（自行填寫）
 * ------------------------------------------------------------ */
const char* WIFI_SSID = "YOUR_WIFI";
const char* WIFI_PASS = "YOUR_PASS";
const char* MQTT_HOST = "192.168.1.100";
const char* MQTT_USER = "mqtt";
const char* MQTT_PASS = "YOUR_PASS";

/* ------------------------------------------------------------
 * 1. 腳位與裝置
 * ------------------------------------------------------------ */
#define SDA0 5
#define SCL0 4
#define SDA1 7
#define SCL1 6
#define LED_PIN 8
#define BUZZ_PIN 9
#define NUM_LEDS 8

CRGB leds[NUM_LEDS];
Adafruit_SGP41 sgp;
Adafruit_BME688 bme;
U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE, SCL1, SDA1);
WiFiClient net;
PubSubClient mqtt(net);

const uint8_t CM1106_ADDR = 0x50;

/* ------------------------------------------------------------
 * 2. 狀態
 * ------------------------------------------------------------ */
uint16_t co2 = 400;
int16_t  tvoc = 0, iaq = 0;
float    tempC = 0, rh = 0;
uint8_t  page = 0;                 // OLED 輪播頁 0~3
uint32_t buzzBudget = 6;           // 每日蜂鳴額度：防「狼來了」
uint32_t lastBuzzDay = 0;

/* ------------------------------------------------------------
 * readCM1106 —— I2C 讀 NDIR CO2
 *   回傳：ppm；0 = 讀取失敗（呼叫端保留前值）
 *   為什麼自己發 I2C：CM1106 只有 6 個暫存器，
 *   拉整個 library 進來是殺雞用牛刀
 * ------------------------------------------------------------ */
uint16_t readCM1106() {
  Wire.beginTransmission(CM1106_ADDR);
  Wire.write(0x06);                // ppm 高暫存器
  if (Wire.endTransmission(false) != 0) return 0;
  uint8_t b[2];
  if (Wire.requestFrom((int)CM1106_ADDR, 2) != 2) return 0;
  b[0] = Wire.read(); b[1] = Wire.read();
  uint16_t ppm = (b[0] << 8) | b[1];
  return (ppm >= 400 && ppm <= 5000) ? ppm : 0;
}

/* ------------------------------------------------------------
 * breathLevel —— 北歐之息分級
 *   參數：c = CO2 ppm
 *   回傳：0 綠(<600) / 1 琥珀(600~1000) / 2 紅+蜂鳴(>1000)
 *   為什麼 1000 才嗶：600~1000 是「該注意了」，
 *   嗶人會讓人直接拔電源——設計要順著人性
 * ------------------------------------------------------------ */
uint8_t breathLevel(uint16_t c) {
  if (c > 1000) return 2;
  if (c > 600)  return 1;
  return 0;
}

/* ------------------------------------------------------------
 * drawBreath —— 呼吸燈動畫（每 loop 呼叫）
 *   等級 2 時每 4 秒加一次蜂鳴（額度內）
 * ------------------------------------------------------------ */
void drawBreath(uint8_t level, uint32_t now) {
  static uint32_t beat = 0;
  if (now - beat < 30) return;     // ~33fps 呼吸更新
  beat = now;
  static float ph = 0; ph += 0.06;
  uint8_t b = (uint8_t)((sin(ph) * 0.5 + 0.5) * 200 + 30);

  CRGB base = level == 0 ? CRGB(0, b, b / 2)
            : level == 1 ? CRGB(b, b / 2, 0)
            :              CRGB(b, 0, 0);
  for (int i = 0; i < NUM_LEDS; i++) {
    /* 波沿環跑：每顆相位差，「呼吸」才有方向感 */
    float local = sin(ph - i * 0.5) * 0.5 + 0.5;
    leds[i] = base; leds[i].nscale8((uint8_t)(80 + local * 175));
  }
  FastLED.show();

  if (level == 2) {
    uint32_t day = now / 86400000UL;
    if (day != lastBuzzDay) { lastBuzzDay = day; buzzBudget = 6; }
    static uint32_t lastBuzz = 0;
    if (buzzBudget && now - lastBuzz > 60000) {   // 每分鐘最多一輪
      lastBuzz = now; buzzBudget--;
      for (int i = 0; i < 2; i++) { digitalWrite(BUZZ_PIN, HIGH); delay(120);
                                    digitalWrite(BUZZ_PIN, LOW);  delay(120); }
    }
  }
}

/* ------------------------------------------------------------
 * drawOled —— 四頁輪播（CO2 / 溫濕 / TVOC+IAQ / 網路狀態）
 * ------------------------------------------------------------ */
void drawOled() {
  static uint32_t t = 0;
  if (millis() - t < 4000) return;  // 4 秒一頁
  t = millis(); page = (page + 1) % 4;
  u8g2.clearBuffer();
  char buf[24];
  u8g2.setFont(u8g2_font_logisoso18_tn);
  switch (page) {
    case 0: snprintf(buf, sizeof(buf), "%u ppm", co2);
            u8g2.drawStr(4, 30, buf);
            u8g2.setFont(u8g2_font_6x12_tr);
            u8g2.drawStr(4, 56, "CO2  NDIR"); break;
    case 1: snprintf(buf, sizeof(buf), "%.1fC %.0f%%", tempC, rh);
            u8g2.drawStr(4, 30, buf);
            u8g2.setFont(u8g2_font_6x12_tr);
            u8g2.drawStr(4, 56, "TEMP  RH"); break;
    case 2: snprintf(buf, sizeof(buf), "TVOC %d", tvoc);
            u8g2.drawStr(4, 30, buf);
            u8g2.setFont(u8g2_font_6x12_tr);
            snprintf(buf, sizeof(buf), "IAQ %d", iaq);
            u8g2.drawStr(4, 56, buf); break;
    case 3: u8g2.setFont(u8g2_font_6x12_tr);
            u8g2.drawStr(4, 20, WiFi.getMode() == WIFI_MODE_STA ?
                         (WiFi.status() == WL_CONNECTED ? "WiFi 6 5G" : "WiFi...") : "-");
            u8g2.drawStr(4, 38, mqtt.connected() ? "MQTT ok" : "MQTT --");
            u8g2.drawStr(4, 56, "AQI Station"); break;
  }
  u8g2.sendBuffer();
}

/* ------------------------------------------------------------
 * connectWiFi —— 5G 優先、2.4G 回落
 *   為什麼手動掃：WiFi.begin 預設由 AP 決定，公寓環境
 *   常常連到訊號最強的 2.4G——我們要的是 5G 的低延遲
 * ------------------------------------------------------------ */
void connectWiFi() {
  WiFi.mode(WIFI_STA);
  WiFi.setBandMode(WIFI_BAND_MODE_AUTO);
  int n = WiFi.scanNetworks();
  bool has5g = false;
  for (int i = 0; i < n; i++)
    if (String(WiFi.SSID(i)) == WIFI_SSID && WiFi.channel(i) > 36) has5g = true;
  if (has5g) Serial.println("5G band selected");
  WiFi.begin(WIFI_SSID, WIFI_PASS);
  for (int i = 0; i < 30 && WiFi.status() != WL_CONNECTED; i++) delay(1000);
}

/* ------------------------------------------------------------
 * publishHA —— HA MQTT 自動發現 + 狀態（每 30 秒）
 * ------------------------------------------------------------ */
void publishHA() {
  if (!mqtt.connected()) {
    if (!mqtt.connect("aqi-c5", MQTT_USER, MQTT_PASS)) return;
    JsonDocument d;
    d["name"] = "AQI C5"; d["uniq_id"] = "aqi-c5";
    d["dev"]["ids"] = "aqi-c5"; d["dev"]["mdl"] = "ESP32-C5 AQI";
    d["stat_t"] = "home/aqi-c5/state";
    char* out = (char*)malloc(512);
    size_t n = serializeJson(d, out, 512);
    mqtt.publish("homeassistant/sensor/aqi_c5_co2/config", out, true);
    free(out);
  }
  char buf[160];
  snprintf(buf, sizeof(buf),
           "{\"co2\":%u,\"tvoc\":%d,\"iaq\":%d,\"t\":%.1f,\"rh\":%.0f}",
           co2, tvoc, iaq, tempC, rh);
  mqtt.publish("home/aqi-c5/state", buf);
}

/* ------------------------------------------------------------
 * setup —— 雙 I2C 初始化順序：先感測器後螢幕
 * ------------------------------------------------------------ */
void setup() {
  Serial.begin(115200);
  pinMode(BUZZ_PIN, OUTPUT); digitalWrite(BUZZ_PIN, LOW);
  FastLED.addLeds<WS2812B, LED_PIN, GRB>(leds, NUM_LEDS);
  FastLED.setBrightness(120);

  Wire.begin(SDA0, SCL0);              // I2C0：感測器
  Wire1.begin(SDA1, SCL1);             // I2C1：OLED（u8g2 自管）

  bme.begin(0x76, &Wire);              // 先 BME：SGP41 補償要溫濕
  sgp.begin(&Wire);
  /* CM1106 上電需 ~3 秒穩定，讀太早會拿到 0 */
  delay(3000);

  connectWiFi();
  mqtt.setServer(MQTT_HOST, 1883);
  Serial.println("aqi station up");
}

/* ------------------------------------------------------------
 * loop —— 1Hz 感測 + 30s MQTT + 33fps 燈 + 4s 輪播
 *   為什麼感測 1Hz：NDIR 內部 1 秒平均，讀更快只是拿重複值
 * ------------------------------------------------------------ */
void loop() {
  static uint32_t sTick = 0, mTick = 0;
  uint32_t now = millis();

  if (now - sTick >= 1000) {
    sTick = now;
    uint16_t c = readCM1106();
    if (c) co2 = c;                    // 失敗保留前值：顯示層不閃 0
    if (bme.performReading()) {
      tempC = bme.temperature; rh = bme.humidity;
      /* SGP41 需帶溫濕補償：把 BME688 的絕對濕度餵給它，
         冬天未補償的 TVOC 會虛高 40% */
      Adafruit_SGP41::humidity_t h = sgp.getAbsoluteHumidity(tempC, rh);
      tvoc = (int16_t)sgp.measureTvoc(h);
    }
    iaq = 0;                           // BME688 IAQ 由 gas 換算，示範略
    uint8_t lv = breathLevel(co2);
    drawOled();
    static uint8_t shownLv = 0; shownLv = lv;
    drawBreath(shownLv, now);
  } else {
    drawBreath(breathLevel(co2), now); // 燈環每 loop 都餵，呼吸才順
  }

  if (now - mTick >= 30000) {
    mTick = now;
    if (WiFi.status() == WL_CONNECTED) { mqtt.loop(); publishHA(); }
  }
  delay(2);
}

🏗️ 組裝步驟

1. 列印零件：主體 PETG、艙蓋對比色 PLA、導光環透明 PETG
2. 感測器艙：三顆感測器卡入，CM1106 光腔開孔正對進氣柵中心
3. 隔板 + 主板艙：隔板卡到底，C5 主板、OLED、燈環依序入位
4. 燒錄 + Wi-Fi：板型 ESP32C5 Dev Module；確認序列埠印出「5G band selected」
5. 校正：開窗通風 10 分鐘後執行「校 400ppm」指令；ABC 自動基線保持開啟
6. 定位：離地 100~120cm、離常坐位置 1~2m、避開冷氣出風口與廚房油煙

🔧 問題排除

🎯 進階延伸

• PM2.5：+PMS7003（UART）做完整六合一，外殼預留風道孔位
• 多房間網格：+2 台從機各報 MQTT，HA 儀表板一圖看全家 CO2 熱區
• 電池 + TWT：C5 的 Wi-Fi 6 TWT 實裝，18650 + TP4056 可跑兩週——監測站放衣櫃、兒童房不受線材限制
• 通風聯動：CO2 超標觸發智能窗馬達，「北歐之息」從提醒變成行動

📦 檔案清單

aqi-station/
├── src/
│   └── aqi-station.ino          # ESP32-C5 程式碼（本頁完整程式）
├── stl/
│   ├── base-box.stl             # 底盒（主板艙）
│   ├── sensor-cabin.stl         # 感測器分層艙 + 隔板
│   ├── cabin-lid.stl            # 進氣柵艙蓋
│   ├── oled-frame.stl           # OLED 窗框
│   └── light-ring.stl           # 呼吸燈導光環（透明）
├── f3d/
│   └── aqi-station-design.f3d
├── manual/
│   └── assembly.html            # 圖文組裝說明書
└── README.md                    # 說明文件