ESP32-S3 驅動 GC9A01 圓屏 + MQ135 製作空氣品質儀表板完整教學(LVGL v9 + SPI 介面 + Arduino C++)
用 ESP32-S3 + MQ135 氣體感測器 + GC9A01 1.28 吋圓屏,搭配 LVGL v9 做一個帶動態弧形錶盤、即時趨勢折線、呼吸發光效果的空氣品質儀表板,含完整接線、程式碼和踩坑紀錄。

難度:⭐⭐☆☆☆(幾根杜邦線就能上手) 預計時間:45 分鐘 測試環境:Arduino IDE 2.3.8 · ESP32 Arduino Core 3.3.10 · lvgl v9.5.0 · Arduino_GFX_Library v1.6.5
TL;DR(只想跑起來?看這裡)
期望管理: 本專案僅供入門、桌面擺件和純粹的視覺享受。千萬別拿它去測真正的有害氣體洩漏! 它的準頭基本屬於「玄學」。
- 接線:MQ135 A0 → GPIO 13;GC9A01 按下表接 GPIO 7 / 9 / 10 / 11 / 12 / 18
- 裝庫:Arduino 函式庫管理器搜
lvgl(選 v9.x)+Arduino_GFX_Library- 配置 lv_conf.h:開啟
LV_FONT_MONTSERRAT_14和LV_FONT_MONTSERRAT_28(改 0 → 1)- 燒錄 → 圓屏亮起,儀表板開始轉動
前言
在我那堆吃灰的感測器中又找到一個專門檢測空氣品質的感測器——MQ135模組。想著看看工作室的空氣品質吧,就連接上測試了一番,看說明文件告訴我這模組預熱要24小時,感覺只能玩玩。不過,這模組對一堆氣體是敏感的,雖然不一定準,但數值升高,相對來說就存在某些氣體,可能是二氧化碳,氨氣,苯,酒精,煙霧。用來做房間是否需要通風的相對數值判斷,應該是可以的。
於是就有了這個專案:ESP32-S3 + MQ135 氣體感測器 + GC9A01 1.28 吋圓屏,搭配大名鼎鼎的 LVGL v9 圖形函式庫,做一個有弧形錶盤、即時趨勢折線、還會「呼吸」變色的空氣品質儀表板。
本文目標:從零接線到燒錄成功,完整重現這個效果。
實驗效果
圓屏即時顯示當前空氣品質 ADC 數值、狀態等級(EXCELLENT / GOOD / FAIR / MODERATE / POOR / DANGER)和歷史趨勢折線;錶盤顏色隨空氣品質從綠漸變到紅,外圈帶節奏感「呼吸」光效。螢幕左下角同時記錄本次上電後的最低值和最高值。
元件說明
開發板(ESP32-S3)本文不做介紹,以下只說新手可能沒接觸過的兩個模組。
MQ135 氣體感測器
MQ135 是一款氣敏感測器,負責檢測空氣中 CO₂、氨氣、苯等有害氣體的濃度變化,用在本專案裡的作用是輸出 0~4095 的類比 ADC 數值,反映當前環境的空氣品質等級。
用大白話說:它是一個化學「鼻子」,空氣越渾濁,輸出電壓越高,ADC 數值越大。
| 參數 | 值 |
|---|---|
| 標準工作電壓 | 5V(加熱絲)/ 類比輸出相容 3.3V |
| 輸出介面 | 類比(A0)+ 數位(D0) |
| 預熱時間 | 24~48 小時(滿精度)/ 約 3 分鐘(趨勢參考) |
| 可檢測氣體 | CO₂、NH₃、NOₓ、苯、酒精、煙霧 |
關於 3.3V 供電: MQ135 標準電壓是 5V,用 3.3V 供電時加熱絲功率約為標準的 44%,靈敏度下降、讀數偏低,但夠用於趨勢展示和相對變化檢測。如果追求絕對精度,建議單獨用 5V 給 VCC,A0 類比輸出不超過 3.3V,無需分壓可直接接 ESP32-S3。
選它的原因:便宜(5 塊錢以內)、模組化、直接接線就能用,對這個「顏值向」專案足夠了。
使用 MQ135 做室內判斷的正確姿勢
✅ 適合做:
- 空氣品質變化趨勢監測(相對值)
- 觸發通風/警報的閾值判斷
- 多種有害氣體「綜合污染」指示
❌ 不適合做:
- 精確的單一氣體濃度測量
- 醫療/工業級安全合規檢測
- CO₂ 精確值(誤差可達 ±300ppm 以上)
GC9A01 1.28 吋圓形 TFT 顯示屏
GC9A01 是一款 1.28 吋圓形 TFT LCD 顯示屏,透過 SPI 介面接收圖像資料並渲染,用在本專案裡的作用是顯示帶動畫效果的儀表板 UI 介面。
類比:就是智慧手錶上那種可以隨便畫內容的圓形錶盤。
| 參數 | 值 |
|---|---|
| 螢幕尺寸 | 1.28 吋 |
| 解析度 | 240 × 240 像素 |
| 介面 | SPI(最高 80 MHz) |
| 驅動晶片 | GC9A01 |
| 工作電壓 | 3.3V |
| 背光控制 | 支援(BL 接腳,可 PWM 調光) |
選它的原因:圓形外觀獨特、尺寸小巧、3.3V 直用、Arduino_GFX_Library 原生支援,搭 LVGL 做錶盤視覺效果拔群。
BOM 表
| 元件 | 型號 / 規格 | 數量 |
|---|---|---|
| 主控開發板 | ESP32-S3(帶 USB-C) | 1 |
| 圓形 TFT 屏 | GC9A01 1.28“ 240×240 | 1 |
| 氣體感測器 | MQ135 模組 | 1 |
| 連接線 | 杜邦線 | 若干 |
元件接腳說明
MQ135 模組接腳
| 接腳 | 說明 |
|---|---|
| VCC | 供電(本專案接 3.3V,標準為 5V) |
| GND | 接地 |
| A0 | 類比信號輸出,接 ESP32-S3 ADC 接腳 |
| D0 | 數位輸出(本專案不使用)輸出高低電位(HIGH / LOW) |
GC9A01 模組接腳
| 接腳標註 | 說明 |
|---|---|
| VCC | 3.3V 供電 |
| GND | 接地 |
| SCL / CLK | SPI 時鐘 |
| SDA / MOSI | SPI 資料 |
| CS | 片選(低電位啟動) |
| DC | 資料/命令切換 |
| RST | 重置(低電位重置) |
| BL | 背光控制(HIGH = 亮)(可選,不一定每個模組都引出) |
接線方式
MQ135 → ESP32-S3
| MQ135 | ESP32-S3 |
|---|---|
| VCC | 5V |
| GND | GND |
| A0 | GPIO 13 |
GC9A01 → ESP32-S3
| GC9A01 接腳 | ESP32-S3 GPIO |
|---|---|
| VCC | 3.3V |
| GND | GND |
| SCL / CLK | GPIO 12 |
| SDA / MOSI | GPIO 11 |
| CS | GPIO 9 |
| DC | GPIO 10 |
| RST | GPIO 18 |
| BL(背光) | GPIO 7 (如果沒有可以不接) |
實用提醒: 接完線後,對著上面兩張表逐行核對一遍,能省掉 80% 的排錯時間。最容易接反的是 DC 和 CS——這兩根線位置一換,螢幕要麼全白要麼全黑,看著很像「螢幕壞了」,其實只是線插錯了。
需要安裝的函式庫
開啟 Arduino IDE → 工具 → 管理函式庫,搜尋並安裝以下兩個:
| 函式庫名稱 | 作者 | 本文測試通過版本 |
|---|---|---|
lvgl |
LVGL | v9.5.0 |
Arduino_GFX_Library |
Moon On Our Nation | v1.6.5 |
安裝完 lvgl 之後,還有一步必須做:
- 找到 lvgl 函式庫目錄(通常在
文件/Arduino/libraries/lvgl/) - 把裡面的
lv_conf_template.h複製一份,重新命名為lv_conf.h,放到lvgl/的同級目錄下 - 開啟
lv_conf.h,找到下面兩行,把0改成1:#define LV_FONT_MONTSERRAT_14 1 #define LV_FONT_MONTSERRAT_28 1 - 開啟
lv_conf.h,找到最開投的#if 0改為#if 1
忘記這一些步,直接燒錄的話,編譯會報
lv_font_montserrat_28 undeclared。別問我怎麼知道的。
完整程式碼
/*
* ESP32-S3 + GC9A01 圓屏空氣品質儀表板 v3.1
* "極簡科技風" - 弧形進度條 + 即時趨勢折線 + 呼吸發光
*
* 測試環境:Arduino IDE 2.3.8 / ESP32 Core 3.3.10
* 依賴函式庫:lvgl v9.5.0 + Arduino_GFX_Library v1.6.5
*/
#include <Arduino.h>
#include <lvgl.h>
#include <Arduino_GFX_Library.h>
#include <math.h>
// ===================== 接腳定義 =====================
#define TFT_SCK 12 // SPI 時鐘
#define TFT_MOSI 11 // SPI 資料
#define TFT_CS 9 // 片選
#define TFT_DC 10 // 資料/命令切換(接反了螢幕會全白)
#define TFT_RST 18 // 重置
#define TFT_BL 7 // 背光——HIGH 才亮,這根線忘了接等於白做
#define MQ135_PIN 13 // MQ135 類比輸入(ADC2 通道,無 Wi-Fi 時正常使用)
#define SCREEN_WIDTH 240
#define SCREEN_HEIGHT 240
// ===================== 初始化顯示驅動 =====================
Arduino_ESP32SPI bus = Arduino_ESP32SPI(TFT_DC, TFT_CS, TFT_SCK, TFT_MOSI, -1);
Arduino_GC9A01 gfx = Arduino_GC9A01(&bus, TFT_RST, 0, true);
// ===================== LVGL 繪製緩衝區 =====================
// 40 行緩衝在 ESP32-S3 上記憶體佔用約 19KB,速度和記憶體比較均衡
#define DRAW_BUF_LINES 40
alignas(4) static uint16_t draw_buf[SCREEN_WIDTH * DRAW_BUF_LINES];
// ===================== 趨勢歷史資料 =====================
#define TREND_POINTS 40 // 保留最近 40 個採樣點(× 300ms ≈ 12 秒一屏歷史)
static int trendData[TREND_POINTS] = {0};
static int trendIdx = 0;
static bool trendFull = false;
static lv_point_precise_t trendLinePoints[TREND_POINTS];
// ===================== LVGL UI 物件句柄 =====================
static lv_obj_t *arc_bg; // 弧形軌道背景(暗色)
static lv_obj_t *arc_main; // 主弧形 + 末端 knob 小圓點
static lv_obj_t *glow_circle; // 外發光邊框圈(會呼吸)
static lv_obj_t *center_circle; // 中心圓盤底板
static lv_obj_t *label_value; // 中心大數字(ADC 值)
static lv_obj_t *label_unit; // 單位標籤 "ADC"
static lv_obj_t *label_status; // 狀態文字(EXCELLENT / GOOD...)
static lv_obj_t *dot_status; // 狀態小圓點
static lv_obj_t *label_title; // 頂部標題 "AIR QUALITY"
static lv_obj_t *label_score; // 底部潔淨度評分
static lv_obj_t *label_minmax; // 最低/最高值
static lv_obj_t *trend_line; // 趨勢折線
static lv_obj_t *trend_container; // 折線裁切容器
// ===================== 感測器狀態 =====================
static float smoothedValue = 0.0f; // 指數加權平均後的平滑值
static bool firstSample = true; // 第一幀標誌,避免從 0 開始動畫
static int minValue = 4095; // 本次上電最低 ADC 值
static int maxValue = 0; // 本次上電最高 ADC 值
static float displayValue = 0.0f; // UI 動畫插值用
// ===================== LVGL 時鐘回調 =====================
static uint32_t my_tick_cb(void) { return millis(); }
// ===================== 重新整理回調:LVGL 渲染完一塊區域後推給螢幕 =====================
void my_disp_flush(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map) {
uint32_t w = area->x2 - area->x1 + 1;
uint32_t h = area->y2 - area->y1 + 1;
gfx.draw16bitRGBBitmap(area->x1, area->y1, (uint16_t *)px_map, w, h);
lv_display_flush_ready(disp); // 告訴 LVGL:這塊畫完了,可以繼續下一塊
}
// ===================== 顏色系統:ADC 值 → 狀態色 =====================
// 數值越高 = 空氣越差 = 顏色越紅,六個檔位對應六種狀態
uint32_t getColorHex(int v) {
if (v < 600) return 0x00E5A0; // EXCELLENT:清新綠
if (v < 1200) return 0x22C55E; // GOOD:淺綠
if (v < 2000) return 0xA3E635; // FAIR:黃綠
if (v < 2800) return 0xEAB308; // MODERATE:黃
if (v < 3500) return 0xF97316; // POOR:橙
return 0xFF3355; // DANGER:紅(快開窗吧)
}
lv_color_t getColor(int v) {
return lv_color_hex(getColorHex(v));
}
// 弧形軌道底色(狀態色的深色版,配合深色背景)
uint32_t getDimColorHex(int v) {
if (v < 600) return 0x0A2A20;
if (v < 1200) return 0x0A2A15;
if (v < 2000) return 0x1A2A10;
if (v < 2800) return 0x2A2208;
if (v < 3500) return 0x2A1808;
return 0x2A0A10;
}
const char* getStatusText(int v) {
if (v < 600) return "EXCELLENT";
if (v < 1200) return "GOOD";
if (v < 2000) return "FAIR";
if (v < 2800) return "MODERATE";
if (v < 3500) return "POOR";
return "DANGER";
}
// ADC 值轉潔淨度百分比(ADC 越低 = 越乾淨 = 分數越高)
int adcToScore(int adc) {
adc = constrain(adc, 0, 4095);
return constrain(100 - (adc * 100 / 4095), 0, 100);
}
// ===================== 建立 UI 介面 =====================
void create_ui() {
lv_obj_t *scr = lv_screen_active();
// 第一步:深色背景
lv_obj_set_style_bg_opa(scr, LV_OPA_COVER, 0);
lv_obj_set_style_bg_color(scr, lv_color_hex(0x050810), 0);
// 第二步:最外圈發光邊框(顏色跟隨狀態,有呼吸動畫)
glow_circle = lv_obj_create(scr);
lv_obj_remove_style_all(glow_circle);
lv_obj_set_size(glow_circle, 234, 234);
lv_obj_center(glow_circle);
lv_obj_set_style_radius(glow_circle, LV_RADIUS_CIRCLE, 0);
lv_obj_set_style_bg_opa(glow_circle, LV_OPA_TRANSP, 0);
lv_obj_set_style_border_width(glow_circle, 2, 0);
lv_obj_set_style_border_opa(glow_circle, LV_OPA_20, 0);
lv_obj_set_style_border_color(glow_circle, lv_color_hex(0x00E5A0), 0);
lv_obj_set_style_shadow_width(glow_circle, 30, 0);
lv_obj_set_style_shadow_spread(glow_circle, 2, 0);
lv_obj_set_style_shadow_opa(glow_circle, LV_OPA_30, 0);
lv_obj_set_style_shadow_color(glow_circle, lv_color_hex(0x00E5A0), 0);
lv_obj_clear_flag(glow_circle, LV_OBJ_FLAG_SCROLLABLE);
// 第三步:弧形軌道底色(顯示「還沒到達」的暗色區域)
arc_bg = lv_arc_create(scr);
lv_obj_remove_style_all(arc_bg);
lv_obj_set_size(arc_bg, 210, 210);
lv_obj_center(arc_bg);
lv_arc_set_range(arc_bg, 0, 100);
lv_arc_set_bg_angles(arc_bg, 135, 45);
lv_arc_set_value(arc_bg, 0);
lv_obj_set_style_arc_width(arc_bg, 18, LV_PART_MAIN);
lv_obj_set_style_arc_color(arc_bg, lv_color_hex(0x0A2A20), LV_PART_MAIN);
lv_obj_set_style_arc_rounded(arc_bg, true, LV_PART_MAIN);
lv_obj_set_style_arc_width(arc_bg, 0, LV_PART_INDICATOR);
lv_obj_set_style_arc_opa(arc_bg, LV_OPA_TRANSP, LV_PART_INDICATOR);
lv_obj_set_style_bg_opa(arc_bg, LV_OPA_TRANSP, LV_PART_KNOB);
lv_obj_clear_flag(arc_bg, LV_OBJ_FLAG_CLICKABLE);
// 第四步:主弧形(即時數值 + 末端 knob 小圓點)
arc_main = lv_arc_create(scr);
lv_obj_remove_style_all(arc_main);
lv_obj_set_size(arc_main, 210, 210);
lv_obj_center(arc_main);
lv_arc_set_range(arc_main, 0, 4095);
lv_arc_set_bg_angles(arc_main, 135, 45);
lv_arc_set_value(arc_main, 0);
lv_obj_set_style_arc_width(arc_main, 18, LV_PART_MAIN);
lv_obj_set_style_arc_opa(arc_main, LV_OPA_TRANSP, LV_PART_MAIN);
lv_obj_set_style_arc_width(arc_main, 18, LV_PART_INDICATOR);
lv_obj_set_style_arc_color(arc_main, lv_color_hex(0x00E5A0), LV_PART_INDICATOR);
lv_obj_set_style_arc_rounded(arc_main, true, LV_PART_INDICATOR);
// knob = 末端小亮點,白色邊框 + 內部填狀態色 + 發光陰影
lv_obj_set_style_bg_color(arc_main, lv_color_hex(0x00E5A0), LV_PART_KNOB);
lv_obj_set_style_bg_opa(arc_main, LV_OPA_COVER, LV_PART_KNOB);
lv_obj_set_style_pad_all(arc_main, 5, LV_PART_KNOB);
lv_obj_set_style_radius(arc_main, LV_RADIUS_CIRCLE, LV_PART_KNOB);
lv_obj_set_style_border_width(arc_main, 3, LV_PART_KNOB);
lv_obj_set_style_border_color(arc_main, lv_color_hex(0xFFFFFF), LV_PART_KNOB);
lv_obj_set_style_border_opa(arc_main, LV_OPA_COVER, LV_PART_KNOB);
lv_obj_set_style_shadow_width(arc_main, 18, LV_PART_KNOB);
lv_obj_set_style_shadow_color(arc_main, lv_color_hex(0x00E5A0), LV_PART_KNOB);
lv_obj_set_style_shadow_opa(arc_main, LV_OPA_70, LV_PART_KNOB);
lv_obj_set_style_shadow_spread(arc_main, 2, LV_PART_KNOB);
lv_obj_clear_flag(arc_main, LV_OBJ_FLAG_CLICKABLE);
// 第五步:中心圓盤(放數值、趨勢線、狀態文字)
center_circle = lv_obj_create(scr);
lv_obj_remove_style_all(center_circle);
lv_obj_set_size(center_circle, 140, 140);
lv_obj_center(center_circle);
lv_obj_set_style_radius(center_circle, LV_RADIUS_CIRCLE, 0);
lv_obj_set_style_bg_opa(center_circle, LV_OPA_COVER, 0);
lv_obj_set_style_bg_color(center_circle, lv_color_hex(0x080E1A), 0);
lv_obj_set_style_bg_grad_color(center_circle, lv_color_hex(0x0C1628), 0);
lv_obj_set_style_bg_grad_dir(center_circle, LV_GRAD_DIR_VER, 0);
lv_obj_set_style_border_width(center_circle, 1, 0);
lv_obj_set_style_border_color(center_circle, lv_color_hex(0x1A3050), 0);
lv_obj_set_style_border_opa(center_circle, LV_OPA_60, 0);
lv_obj_set_style_pad_all(center_circle, 0, 0);
lv_obj_clear_flag(center_circle, LV_OBJ_FLAG_SCROLLABLE);
// 中心大數字
label_value = lv_label_create(center_circle);
lv_label_set_text(label_value, "0");
lv_obj_set_style_text_font(label_value, &lv_font_montserrat_28, 0);
lv_obj_set_style_text_color(label_value, lv_color_hex(0x00E5A0), 0);
lv_obj_align(label_value, LV_ALIGN_CENTER, 0, -26);
// 單位標籤
label_unit = lv_label_create(center_circle);
lv_label_set_text(label_unit, "ADC");
lv_obj_set_style_text_font(label_unit, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(label_unit, lv_color_hex(0x506878), 0);
lv_obj_align(label_unit, LV_ALIGN_CENTER, 0, -6);
// 趨勢折線容器(負責裁切,防止折線越界)
trend_container = lv_obj_create(center_circle);
lv_obj_remove_style_all(trend_container);
lv_obj_set_size(trend_container, 110, 30);
lv_obj_align(trend_container, LV_ALIGN_CENTER, 0, 16);
lv_obj_set_style_bg_opa(trend_container, LV_OPA_TRANSP, 0);
lv_obj_set_style_pad_all(trend_container, 0, 0);
lv_obj_set_style_clip_corner(trend_container, true, 0);
lv_obj_set_style_radius(trend_container, 4, 0);
lv_obj_clear_flag(trend_container, LV_OBJ_FLAG_SCROLLABLE);
// 折線底部參考基線
static lv_point_precise_t refPts[2] = {{0, 28}, {110, 28}};
lv_obj_t *refLine = lv_line_create(trend_container);
lv_line_set_points(refLine, refPts, 2);
lv_obj_set_style_line_color(refLine, lv_color_hex(0x1A2535), 0);
lv_obj_set_style_line_width(refLine, 1, 0);
// 趨勢折線(初始化所有點到底部)
for (int i = 0; i < TREND_POINTS; i++) {
trendLinePoints[i].x = (int32_t)(i * 110 / (TREND_POINTS - 1));
trendLinePoints[i].y = 28;
}
trend_line = lv_line_create(trend_container);
lv_line_set_points(trend_line, trendLinePoints, TREND_POINTS);
lv_obj_set_style_line_color(trend_line, lv_color_hex(0x00E5A0), 0);
lv_obj_set_style_line_width(trend_line, 2, 0);
lv_obj_set_style_line_rounded(trend_line, true, 0);
lv_obj_set_style_line_opa(trend_line, LV_OPA_70, 0);
// 狀態小圓點
dot_status = lv_obj_create(center_circle);
lv_obj_remove_style_all(dot_status);
lv_obj_set_size(dot_status, 8, 8);
lv_obj_set_style_radius(dot_status, LV_RADIUS_CIRCLE, 0);
lv_obj_set_style_bg_opa(dot_status, LV_OPA_COVER, 0);
lv_obj_set_style_bg_color(dot_status, lv_color_hex(0x00E5A0), 0);
lv_obj_set_style_shadow_width(dot_status, 8, 0);
lv_obj_set_style_shadow_color(dot_status, lv_color_hex(0x00E5A0), 0);
lv_obj_set_style_shadow_opa(dot_status, LV_OPA_50, 0);
lv_obj_align(dot_status, LV_ALIGN_CENTER, -42, 42);
// 狀態文字
label_status = lv_label_create(center_circle);
lv_label_set_text(label_status, "EXCELLENT");
lv_obj_set_style_text_font(label_status, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(label_status, lv_color_hex(0x00E5A0), 0);
lv_obj_align(label_status, LV_ALIGN_CENTER, 3, 42);
// 頂部標題
label_title = lv_label_create(scr);
lv_label_set_text(label_title, "AIR QUALITY");
lv_obj_set_style_text_font(label_title, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(label_title, lv_color_hex(0x4A6070), 0);
lv_obj_set_style_text_letter_space(label_title, 3, 0);
lv_obj_align(label_title, LV_ALIGN_TOP_MID, 0, 60);
// 底部評分
label_score = lv_label_create(scr);
lv_label_set_text(label_score, "100% CLEAN");
lv_obj_set_style_text_font(label_score, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(label_score, lv_color_hex(0x00E5A0), 0);
lv_obj_align(label_score, LV_ALIGN_BOTTOM_MID, 0, -8);
// MIN/MAX 記錄(底部評分上方)
label_minmax = lv_label_create(scr);
lv_label_set_text(label_minmax, "L:-- H:--");
lv_obj_set_style_text_font(label_minmax, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(label_minmax, lv_color_hex(0x3A4A5A), 0);
lv_obj_align(label_minmax, LV_ALIGN_BOTTOM_MID, 0, -24);
}
// ===================== 更新趨勢折線資料 =====================
void updateTrend(int value) {
trendData[trendIdx] = value;
trendIdx = (trendIdx + 1) % TREND_POINTS;
if (trendIdx == 0) trendFull = true;
int count = trendFull ? TREND_POINTS : trendIdx;
if (count < 2) return;
// 找資料範圍,用於歸一化到折線高度
int vMin = 4095, vMax = 0;
for (int i = 0; i < count; i++) {
if (trendData[i] < vMin) vMin = trendData[i];
if (trendData[i] > vMax) vMax = trendData[i];
}
// 保證最小波動幅度——不然空氣太穩定時折線是一條死平線
if (vMax - vMin < 50) vMax = vMin + 50;
int chartW = 110;
int chartH = 26;
for (int i = 0; i < TREND_POINTS; i++) {
int x = i * chartW / (TREND_POINTS - 1);
int y;
if (i < count) {
int dataIdx = trendFull ? (trendIdx + i) % TREND_POINTS : i;
int normalized = (trendData[dataIdx] - vMin) * chartH / (vMax - vMin);
y = chartH - normalized + 1; // y 軸反轉:值越大,點越靠上
} else {
y = chartH + 1; // 沒資料的位置先放底部
}
trendLinePoints[i].x = x;
trendLinePoints[i].y = y;
}
lv_line_set_points(trend_line, trendLinePoints, TREND_POINTS);
}
// ===================== 更新 UI 顯示 =====================
void update_ui(int value, int raw) {
value = constrain(value, 0, 4095);
raw = constrain(raw, 0, 4095);
// 平滑動畫:每幀向目標值逼近 18%,數字變化平滑不突兀
float diff = (float)value - displayValue;
displayValue += diff * 0.18f;
int dispVal = (int)(displayValue + 0.5f);
lv_color_t c = getColor(dispVal);
uint32_t dimC = getDimColorHex(dispVal);
int score = adcToScore(dispVal);
// 更新 min/max 記錄
if (raw < minValue) minValue = raw;
if (raw > maxValue) maxValue = raw;
// 主弧形 + knob 顏色跟隨狀態
lv_arc_set_value(arc_main, dispVal);
lv_obj_set_style_arc_color(arc_main, c, LV_PART_INDICATOR);
lv_obj_set_style_bg_color(arc_main, c, LV_PART_KNOB);
lv_obj_set_style_shadow_color(arc_main, c, LV_PART_KNOB);
// 軌道底色
lv_obj_set_style_arc_color(arc_bg, lv_color_hex(dimC), LV_PART_MAIN);
// 外發光圈:顏色跟隨狀態 + sin 函數模擬呼吸透明度
lv_obj_set_style_border_color(glow_circle, c, 0);
lv_obj_set_style_shadow_color(glow_circle, c, 0);
static uint32_t breathCount = 0;
breathCount++;
float sinVal = sinf((breathCount * 6) % 360 * 3.14159f / 180.0f);
lv_opa_t breathOpa = (lv_opa_t)(LV_OPA_20 + (int)(sinVal * 25.0f));
lv_obj_set_style_shadow_opa(glow_circle, breathOpa, 0);
lv_opa_t borderOpa = (lv_opa_t)(LV_OPA_10 + (int)(sinVal * 15.0f));
lv_obj_set_style_border_opa(glow_circle, borderOpa, 0);
// 中心數值
lv_label_set_text_fmt(label_value, "%d", dispVal);
lv_obj_set_style_text_color(label_value, c, 0);
// 狀態文字 + 小圓點(小圓點陰影也跟著呼吸)
lv_label_set_text(label_status, getStatusText(dispVal));
lv_obj_set_style_text_color(label_status, c, 0);
lv_obj_set_style_bg_color(dot_status, c, 0);
lv_obj_set_style_shadow_color(dot_status, c, 0);
lv_opa_t dotOpa = (lv_opa_t)(LV_OPA_30 + (int)(sinVal * 40.0f));
lv_obj_set_style_shadow_opa(dot_status, dotOpa, 0);
// 趨勢線顏色
lv_obj_set_style_line_color(trend_line, c, 0);
// MIN/MAX
lv_label_set_text_fmt(label_minmax, "L:%d H:%d", minValue, maxValue);
// 底部潔淨度評分
const char *statusWord;
if (score >= 80) statusWord = "CLEAN";
else if (score >= 60) statusWord = "FAIR";
else if (score >= 40) statusWord = "HAZY";
else if (score >= 20) statusWord = "DIRTY";
else statusWord = "TOXIC";
lv_label_set_text_fmt(label_score, "%d%% %s", score, statusWord);
lv_obj_set_style_text_color(label_score, c, 0);
}
// ===================== setup =====================
void setup() {
Serial.begin(115200);
delay(200);
// 第一步:背光拉高,不做這步螢幕永遠黑
pinMode(TFT_BL, OUTPUT);
digitalWrite(TFT_BL, HIGH);
// 第二步:配置 ADC(12 位精度,0-3.3V 量程)
// 註:ADC_11db 在 ESP32 Core 3.x 中等同於 ADC_ATTEN_DB_12,相容舊寫法
pinMode(MQ135_PIN, INPUT);
analogReadResolution(12);
analogSetAttenuation(ADC_11db);
// 第三步:啟動顯示屏,SPI 頻率 40MHz
gfx.begin(40000000);
// 第四步:初始化 LVGL
lv_init();
lv_tick_set_cb(my_tick_cb);
lv_display_t *disp = lv_display_create(SCREEN_WIDTH, SCREEN_HEIGHT);
lv_display_set_color_format(disp, LV_COLOR_FORMAT_RGB565);
lv_display_set_buffers(disp, draw_buf, NULL, sizeof(draw_buf), LV_DISPLAY_RENDER_MODE_PARTIAL);
lv_display_set_flush_cb(disp, my_disp_flush);
// 第五步:建構介面,初始化為 0 值
create_ui();
displayValue = 0;
update_ui(0, 0);
Serial.println("[SYS] Gauge v3.1 Ready!");
}
// ===================== loop =====================
void loop() {
static uint32_t lastSensorMs = 0;
static uint32_t lastTrendMs = 0;
static uint32_t lastLogMs = 0;
uint32_t now = millis();
// 每 50ms:讀感測器 + 重新整理 UI(約 20fps,流暢無卡頓感)
if (now - lastSensorMs >= 50) {
int raw = analogRead(MQ135_PIN);
raw = constrain(raw, 0, 4095);
if (firstSample) {
// 第一幀直接賦值,跳過從 0 開始的動畫過渡
smoothedValue = raw;
displayValue = raw;
firstSample = false;
} else {
// 指數加權平均:新值占 12%,舊值保留 88%,平滑但不遲鈍
smoothedValue = smoothedValue * 0.88f + raw * 0.12f;
}
update_ui((int)smoothedValue, raw);
lastSensorMs = now;
}
// 每 300ms:推一個資料點到趨勢折線(40 點 × 300ms ≈ 12 秒覆蓋一屏歷史)
if (now - lastTrendMs >= 300) {
updateTrend((int)smoothedValue);
lastTrendMs = now;
}
// 每 1s:串口輸出除錯日誌(查問題時開啟串口監視器看)
if (now - lastLogMs >= 1000) {
Serial.printf("SCORE=%d%% ADC=%d SMOOTH=%d L=%d H=%d [%s]\n",
adcToScore((int)smoothedValue),
analogRead(MQ135_PIN),
(int)smoothedValue,
minValue, maxValue,
getStatusText((int)smoothedValue));
lastLogMs = now;
}
lv_timer_handler(); // LVGL 內部任務調度,必須週期性呼叫,不能漏
delay(5);
}
程式碼說明
幾個關鍵設計說一下,不然看程式碼容易一頭霧水:
① 為什麼用指數加權平均,不直接顯示原始 ADC?
MQ135 的類比輸出帶一定雜訊,直接顯示數字會不停跳變。指數加權平均(EMA)公式:
新平滑值 = 舊平滑值 × 0.88 + 原始值 × 0.12
0.12 的權重意味著新資料影響較小,數值變化平緩但跟得上趨勢。想讓回應更靈敏,把 0.12f 調大(上限 1.0 = 完全不平滑);想更穩定,把 0.88f 調大。
② 呼吸效果怎麼實現的?
update_ui() 裡用 sinf() 生成一個 −1 到 +1 週期變化的值,映射到透明度範圍(LV_OPA_20 ~ LV_OPA_45),每次呼叫時計數器遞增。外圈邊框和陰影的透明度就這樣週期性淡入淡出,像在「呼吸」。
③ 趨勢折線為什麼有時是平的?
當環境非常穩定,歷史資料最大最小值差距很小時,折線被強制拉到至少 50 ADC 的波動範圍:
if (vMax - vMin < 50) vMax = vMin + 50;
這樣即便空氣沒變化,折線也不會變成一條死平線,還能看出微小波動。
常見問題排查
別慌,80% 的問題出在這幾個地方:
螢幕全黑,毫無反應
第一件事:檢查 BL 接腳是否接到 GPIO 7,程式碼裡 digitalWrite(TFT_BL, HIGH) 有沒有執行。背光沒開,螢幕肯定黑——這不是屏壞了,是背光沒拉高。
螢幕全白或全紅(有顏色但沒內容) 九成機率是 DC 和 CS 接腳接反了。對照接線表把這兩根線檢查一遍,或者直接交換試試。
編譯報錯:lv_font_montserrat_28 undeclared
lv_conf.h 沒有正確配置,或者放錯了位置。回頭看「需要安裝的函式庫」章節,按步驟把字體選項從 0 改為 1。
ADC 讀數一直是 0 或 4095 不變化 用萬用電表量 MQ135 的 A0 接腳輸出電壓,正常應在 0.5V~2.5V 之間波動。如果是 0V 檢查 VCC 接線;如果是滿量程(3.3V),感測器可能沒預熱夠——新感測器剛通電讀數不穩定,等 3 分鐘再看。
數值顯示抖動厲害
把程式碼裡的平滑係數 0.88f 改大(比如 0.95f),平滑程度增加,代價是回應變慢。
LVGL 編譯提示記憶體不足或運行時卡死
把 DRAW_BUF_LINES 從 40 改小(比如 20),減少緩衝區佔用。ESP32-S3 標配 RAM 足夠,如果用的是 RAM 較小的板子才會遇到這個問題。
FAQ
Q:GPIO 13 是固定的嗎?可以換成別的 ADC 接腳嗎? A:可以換。ESP32-S3 上 GPIO 1~10 屬於 ADC1,GPIO 11~20 屬於 ADC2。本專案不使用 Wi-Fi,ADC2 接腳(含 GPIO 13)沒有衝突,正常可用。如果後續要加 Wi-Fi,建議把感測器換到 ADC1 接腳(GPIO 1~10),避免 Wi-Fi 佔用 ADC2 時讀數出錯。
Q:MQ135 接 3.3V 供電,讀數到底準不准? A:不夠精準,但做趨勢展示完全夠用。MQ135 額定電壓 5V,用 3.3V 供電時加熱絲功率約為標準的 44%,靈敏度下降、絕對值偏低。如果要換算成 ppm 濃度,建議用 5V 單獨給 VCC,A0 類比輸出不超過 3.3V,不需要額外分壓電路。
Q:LVGL 必須用 v9 嗎?v8 能不能跑?
A:v8 不能直接跑本程式碼。v9 引入了 lv_display_t、lv_display_create 等新 API,v8 裡沒有這些結構體,直接編譯會報大量錯誤。強烈建議安裝 v9.2.x 起步的版本,不要降級。
Q:圓屏四個角有黑色「缺口」,是不是焊壞了? A:正常現象,不是問題。GC9A01 是圓形顯示區域,底層 buffer 是 240×240 方形,四角是螢幕物理遮光結構,沒有實際像素點,不顯示內容是正確的。
Q:感測器剛通電時數值跳得很厲害,要等多久才穩?
A:MQ135 需要預熱。新感測器建議連續通電 24~48 小時後讀數才穩定;已經用過的感測器通電約 3 分鐘後趨於平穩。可以在 setup() 末尾加 delay(180000)(3 分鐘),或者在 UI 上加一個「預熱中」狀態提示,到時間後再正式開始採集。
Q:螢幕重新整理有點卡,怎麼提速?
A:兩個方向:① 把 gfx.begin(40000000) 裡的 SPI 頻率改到 80MHz(GC9A01 最大支援 80MHz,但部分板子佈線質量差時不穩定,建議先測試);② 增大 DRAW_BUF_LINES(如改為 60),減少 LVGL 分塊重新整理的次數,代價是多佔約 9KB RAM。
延伸玩法
跑起來之後,可以往這幾個方向繼續擴展:
- 接 BME280,加一路溫濕度,儀表板多顯示一行資料
- 透過 Wi-Fi 把 ADC 資料上報 Home Assistant,做長期歷史曲線
- 加按鍵切換顯示模式(儀表板 / 大字模式 / 純折線)
- 換 MQ-7 感測器,專門監測一氧化碳濃度
- 加蜂鳴器,空氣品質進入 DANGER 區時觸發告警