ESP32-S3 驱动 4.2 寸墨水屏(SSD1683)|接入 AQICN 做一个空气质量看板(GxEPD2 + SPI)
用 ESP32-S3 + GxEPD2 驱动 4.2 寸黑白墨水屏(GDEY042A87 / SSD1683),接入 AQICN 空气质量 API,做一个断电也不花屏的桌面空气质量看板,含接线、完整 Arduino C++ 代码、分区方案与排错全流程。

一句话摘要:用一块十几块淘来的二手 4.2 寸黑白墨水屏和 ESP32-S3,接入 AQICN 空气质量 API,做一个不用掏手机、瞥一眼就知道今天能不能冲去爬白云山的桌面空气质量看板。
难度:⭐⭐☆☆☆(新手可上手) 预计时间:30 分钟 测试环境:Arduino IDE 2.3.8 + ESP32 Arduino Core 3.3.10 + GxEPD2 v1.6.9 + Adafruit GFX Library v1.12.6 + ArduinoJson v7.4.3(建议装库时对照这个版本,太新太旧都可能踩坑)
TL;DR(快速上手):
- 接线:GPIO11 → SDI/MOSI,GPIO12 → SCL/SCK,GPIO10 → CS,GPIO9 → DC,GPIO8 → RES,GPIO7 → BUSY,VCC 接 3.3V,GND 共地
- 安装库:ArduinoJson、GxEPD2、Adafruit GFX Library、U8g2_for_Adafruit_GFX(作者 olikraus)
- 把代码里的
WIFI_SSID、WIFI_PASS、API_TOKEN改成自己的(Token 申请方法见下方「申请 AQICN 免费 API Token」一节)- 烧录,等 WiFi 连上,屏幕会自动刷新出空气质量数据
前言
十几块钱在二手市场淘了一块黑白墨水屏,说实话下单的时候心里是有点打鼓的——万一是块坏屏,这钱就打水漂了。还好上电测试一切正常,没翻车,但有一条竖线坏了,不过影响不大。趁着屏还热乎,干脆做一个能一直显示、不用手机 App、瞥一眼就知道今天白云山空气好不好的小看板,天气好就冲去爬白云山。这篇文章记录完整的接线、代码和踩过的坑,跟着做基本能一次点亮。
实验效果
一块 ESP32-S3 定时从 AQICN.ORG 拉取空气质量数据,刷新到墨水屏上,画面包含 AQI 大数字、12 项细分指标(PM2.5、PM10、温湿度、风速等)以及 PM2.5 和紫外线的七日预测柱状图,断电也不花屏,放桌上就是个“电子风水表”,很好的桌搭。
元件说明
ESP32-S3 开发板 是一颗带 WiFi 的 SoC 开发板,负责联网拉数据、跑逻辑、通过 SPI 把画面推给屏幕,是整个项目的大脑。选它是因为引脚多、算力够、自带 WiFi,不用额外配网络模块。
墨水屏驱动板(自制)负责把 ESP32 发来的 SPI 指令翻译成屏幕能懂的电平信号,本质上就是个“翻译官”。选择自己画板是因为好玩。引出的接口和市面上的一样的,所以你有其他的墨水屏驱动板亦可一试。
4.2 寸黑白电子墨水屏 是一种靠电场翻转微胶囊里黑白粒子来显示画面的屏幕,特点是断电也能保持画面,适合做这种“看一眼就走”的信息看板。它不像 LCD 那样费电,唯一的代价是刷新慢,不适合做动画。
BOM 表
| 元件 | 型号/规格 | 数量 |
|---|---|---|
| ESP32 开发板 | ESP32-S3(带足够 SPI 引脚的型号均可) | 1 |
| 墨水屏驱动板 | 自制 PCB,引脚定义与市面主流墨水屏驱动板一致 | 1 |
| 电子墨水屏 | 4.2 寸黑白,兼容 GxEPD2_420_GYE042A87 驱动 | 1 |
| 杜邦线 | 若干 |
元件引脚说明
| 引脚 | 全称 | 作用 |
|---|---|---|
| VCC | 电源正极 | 供电输入,接 ESP32-S3 的 3V3 输出 |
| GND | 电源地 | 参考地,接 ESP32-S3 的 GND,形成回路 |
| SDI/MOSI | 主机输出从机输入 | SPI 数据线,ESP32 往屏幕发数据 |
| SCL/SCK | 串行时钟 | SPI 时钟线,控制数据传输节奏 |
| CS | 片选 | 告诉屏幕“接下来的数据是发给你的” |
| DC | 数据/命令切换 | 区分当前传的是画面数据还是控制命令 |
| RES/RST | 复位 | 拉低一下让屏幕重新初始化 |
| BUSY | 忙状态指示 | 刷新中会拉低,ESP32 靠它判断“能不能发下一条指令” |
接线方式
| 墨水屏引脚 | 接 ESP32-S3 引脚 |
|---|---|
| SDI/MOSI | GPIO11 |
| SCL/SCK | GPIO12 |
| CS | GPIO10 |
| DC | GPIO9 |
| RES | GPIO8 |
| BUSY | GPIO7 |
| VCC | 3.3V |
| GND | GND |
建议接完逐一核对,能省 80% 排错时间——墨水屏最坑的地方是接错线不会报错,只会一直花屏或者白屏,肉眼很难第一时间判断是代码问题还是接线问题。
需要安装的库
在 Arduino IDE 的库管理器里搜索安装以下几个(测试通过版本仅供参考,实际以库管理器最新稳定版为准):
| 库名 | 作用 | 测试版本 |
|---|---|---|
| ArduinoJson | 解析 AQICN API 返回的 JSON | v7.4.3 |
| GxEPD2 | 墨水屏驱动核心库 | v1.6.9 |
| Adafruit GFX Library | 图形绘制基础库,GxEPD2 依赖它 | v1.12.6 |
| U8g2_for_Adafruit_GFX | 桥接 U8g2 中文字库到 Adafruit GFX,用于显示中文 | v1.8.0(作者 olikraus) |
WiFi.h、HTTPClient.h、SPI.h 是 ESP32 核心自带,不用单独安装,只要装好了 ESP32 开发板支持包就有。
烧录配置:分区方案(重要)
这里有个坑要先踩明白:本项目用到了 U8g2_for_Adafruit_GFX 的完整中文字库(代码里引用了 u8g2_font_wqy16_t_gb2312、wqy14、wqy12 三套),这些 GB2312 字库加起来快 500KB。而 ESP32 默认的分区方案给程序区只留了 1MB,编译时会报「空间不足(region `app’ overflowed)」直接烧不进去。
解决办法:上传前把分区方案调大。
操作路径:Arduino IDE 顶部菜单 → 工具 (Tools) → Partition Scheme → 选 Huge APP (3MB No OTA/1MB SPIFFS)
我用的就是这个 Huge APP,给程序区一口气分了 3MB,字库和代码都能舒舒服服塞进去,编译烧录一路畅通。
💡 几点补充:
- 为什么字库这么大? GB2312 收录了六七千个汉字,每套 wqy 字体都是一两百 KB 的点阵数据,没办法像西文字库那样小。
- No OTA 的代价:选了 No OTA 就没法用「空中升级」刷固件,只能老老实实用 USB 线烧录。对桌面小摆件来说毫无影响,反正就放桌上插着电。
- 大 Flash 板子的更优解:如果你的 ESP32-S3 是 ≥8MB Flash 的版本,可以选更宽松的方案(如
8M with SPIFFS),既不卡 OTA,又能多出空间存数据。- 改完分区方案记得重新编译,别只点「上传」用旧配置。
申请 AQICN 免费 API Token
代码里的 API_TOKEN 和城市编号(如 @14370)都来自 AQICN(aqicn.org),免费申请,照下面四步就能拿到。
第一步:找到你的城市
打开 aqicn.org,在右上角搜索框输入想监控的城市或监测站名称(比如「Guangzhou」「Baiyun Mountain」),点进对应的空气质量页面。
第二步:进入 API 数据平台
在该城市页面向下滚动,找到标着「json: api」的链接,点进去,会跳转到 AQICN 数据平台。
第三步:注册并激活账户
填邮箱注册一个账号,去收件箱点激活链接完成验证。登录之后,在控制台里就能看到你专属的 Token(一串随机字符串,注意保密,别直接传到公开仓库里)。
第四步:拼接 API 地址并填进代码
把 Token 填进代码里的 API_TOKEN 宏,再把 API_URL 中的 @14370 换成你想要的监测站编号(也可以直接用城市英文名或经纬度坐标,写法见 AQICN API 文档),完整格式如下:
https://api.waqi.info/feed/@14370/?token=你的Token
想确认地址配对没问题,把上面这串粘进浏览器地址栏直接打开,能看到返回 "status":"ok" 的 JSON 就说明通了。
AQICN 个人 Token 完全免费、无需绑卡,额度够个人项目随便用,不用担心收费。
完整代码 + 说明
/*
* ============================================================
* ESP32-S3 + 4.2" 墨水屏 空气质量监测站 (v2.1 横屏优化版)
* Air Quality Monitor using AQICN API
* ============================================================
*
* 本版本相对上一版做了如下修改:
* 1. 彻底删除了底部显示不全的 PM10 预测表格及其标题。
* 2. 将上方的 AQI 方块和 12项指标网格高度从 128 扩大至 141,行高更宽松。
* 3. 将 PM2.5 和紫外线预测图表的高度从 52 扩大至 64,画面更舒展。
* 4. 重新计算了所有垂直坐标,底部保留少许清爽留白。
*
* 硬件连接 (不变):
* EPD_CS -> GPIO 10
* EPD_DC -> GPIO 9
* EPD_RST -> GPIO 8
* EPD_BUSY -> GPIO 7
* EPD_MOSI -> GPIO 11
* EPD_CLK -> GPIO 12
* ============================================================
*/
#include <WiFi.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>
#include <SPI.h>
#include <GxEPD2_BW.h>
#include <Adafruit_GFX.h>
#include <U8g2_for_Adafruit_GFX.h>
// 粗体数字字体 (Adafruit GFX 自带)
#include <Fonts/FreeSansBold9pt7b.h>
#include <Fonts/FreeSansBold12pt7b.h>
#include <Fonts/FreeSansBold24pt7b.h>
// ==================== 配置区 ====================
#define WIFI_SSID "YOUR_WIFI_SSID"
#define WIFI_PASS "YOUR_WIFI_PASSWORD"
#define API_TOKEN "YOUR_WIFI_AQI_API_TONKEN"
#define API_URL "https://api.waqi.info/feed/@14370/?token=" API_TOKEN
#define UPDATE_INTERVAL_MS (30 * 60 * 1000) // 30分钟更新一次
// 如果画面上下颠倒,把这里改成 1
#define ROTATION_FLIP 0
// ==================== 引脚定义 ====================
#define EPD_CS 10
#define EPD_DC 9
#define EPD_RST 8
#define EPD_BUSY 7
#define EPD_MOSI 11
#define EPD_CLK 12
// ==================== 墨水屏驱动 ====================
GxEPD2_BW<GxEPD2_420_GYE042A87, GxEPD2_420_GYE042A87::HEIGHT> display(
GxEPD2_420_GYE042A87(EPD_CS, EPD_DC, EPD_RST, EPD_BUSY)
);
// U8g2 中文渲染桥接对象
U8G2_FOR_ADAFRUIT_GFX u8f;
// ==================== 数据结构 ====================
struct ForecastDay {
char day[6]; // "07-08"
int avg;
int maxVal;
int minVal;
};
struct AqiData {
int aqi;
char city[32];
char timeStr[20];
char timeShort[12]; // 精简时间 "07-08 14:00"
char dominentpol[8];
float lat, lon;
float co, dew, h, no2, o3, p, pm10, pm25, so2, t, w, wg;
ForecastDay pm25Forecast[8];
int pm25ForecastCount;
ForecastDay pm10Forecast[8];
int pm10ForecastCount;
ForecastDay uviForecast[8];
int uviForecastCount;
};
AqiData aqiData;
// ==================== 辅助函数: AQI 等级 ====================
const char* getAqiLevel(int aqi) {
if (aqi <= 50) return "Good";
if (aqi <= 100) return "Moderate";
if (aqi <= 150) return "Unhealthy-S";
if (aqi <= 200) return "Unhealthy";
if (aqi <= 300) return "V.Unhealthy";
return "Hazardous";
}
const char* getAqiLevelCN(int aqi) {
if (aqi <= 50) return "优";
if (aqi <= 100) return "良";
if (aqi <= 150) return "轻度污染";
if (aqi <= 200) return "中度污染";
if (aqi <= 300) return "重度污染";
return "严重污染";
}
// ==================== WiFi 连接 ====================
void connectWiFi() {
Serial.printf("Connecting to WiFi: %s", WIFI_SSID);
WiFi.begin(WIFI_SSID, WIFI_PASS);
int retries = 0;
while (WiFi.status() != WL_CONNECTED && retries < 40) {
delay(500);
Serial.print(".");
retries++;
}
if (WiFi.status() == WL_CONNECTED) {
Serial.printf("\nConnected! IP: %s\n", WiFi.localIP().toString().c_str());
} else {
Serial.println("\nWiFi connection FAILED!");
}
}
// ==================== 解析预报数组 ====================
int parseForecastArray(JsonArray arr, ForecastDay* out, int maxCount) {
int count = 0;
for (JsonObject item : arr) {
if (count >= maxCount) break;
const char* dayStr = item["day"];
if (dayStr && strlen(dayStr) >= 10) {
strncpy(out[count].day, dayStr + 5, 5);
out[count].day[5] = '\0';
}
out[count].avg = item["avg"] | 0;
out[count].maxVal = item["max"] | 0;
out[count].minVal = item["min"] | 0;
count++;
}
return count;
}
// ==================== API 请求与解析 ====================
bool fetchAqiData() {
if (WiFi.status() != WL_CONNECTED) {
Serial.println("WiFi not connected, skipping fetch.");
return false;
}
HTTPClient http;
http.begin(API_URL);
http.setTimeout(15000);
int httpCode = http.GET();
if (httpCode != 200) {
Serial.printf("HTTP GET failed, code: %d\n", httpCode);
http.end();
return false;
}
String payload = http.getString();
http.end();
JsonDocument doc;
DeserializationError err = deserializeJson(doc, payload);
if (err) {
Serial.printf("JSON parse error: %s\n", err.c_str());
return false;
}
const char* status = doc["status"];
if (!status || strcmp(status, "ok") != 0) {
Serial.println("API status not OK");
return false;
}
JsonObject data = doc["data"];
aqiData.aqi = data["aqi"] | 0;
const char* cityName = data["city"]["name"];
if (cityName) {
const char* comma = strchr(cityName, ',');
if (comma) {
int len = comma - cityName;
if (len > 31) len = 31;
strncpy(aqiData.city, cityName, len);
aqiData.city[len] = '\0';
} else {
strncpy(aqiData.city, cityName, 31);
aqiData.city[31] = '\0';
}
}
const char* timeS = data["time"]["s"];
if (timeS) {
strncpy(aqiData.timeStr, timeS, 19);
aqiData.timeStr[19] = '\0';
if (strlen(timeS) >= 16) {
memcpy(aqiData.timeShort, timeS + 5, 11);
aqiData.timeShort[11] = '\0';
} else {
aqiData.timeShort[0] = '\0';
}
}
const char* dpol = data["dominentpol"];
if (dpol) {
strncpy(aqiData.dominentpol, dpol, 7);
aqiData.dominentpol[7] = '\0';
}
aqiData.lat = data["city"]["geo"][0] | 0.0f;
aqiData.lon = data["city"]["geo"][1] | 0.0f;
JsonObject iaqi = data["iaqi"];
aqiData.co = iaqi["co"]["v"] | 0.0f;
aqiData.dew = iaqi["dew"]["v"] | 0.0f;
aqiData.h = iaqi["h"]["v"] | 0.0f;
aqiData.no2 = iaqi["no2"]["v"] | 0.0f;
aqiData.o3 = iaqi["o3"]["v"] | 0.0f;
aqiData.p = iaqi["p"]["v"] | 0.0f;
aqiData.pm10 = iaqi["pm10"]["v"] | 0.0f;
aqiData.pm25 = iaqi["pm25"]["v"] | 0.0f;
aqiData.so2 = iaqi["so2"]["v"] | 0.0f;
aqiData.t = iaqi["t"]["v"] | 0.0f;
aqiData.w = iaqi["w"]["v"] | 0.0f;
aqiData.wg = iaqi["wg"]["v"] | 0.0f;
JsonObject forecast = data["forecast"]["daily"];
aqiData.pm25ForecastCount = parseForecastArray(
forecast["pm25"].as<JsonArray>(), aqiData.pm25Forecast, 8);
aqiData.pm10ForecastCount = parseForecastArray(
forecast["pm10"].as<JsonArray>(), aqiData.pm10Forecast, 8);
aqiData.uviForecastCount = parseForecastArray(
forecast["uvi"].as<JsonArray>(), aqiData.uviForecast, 8);
Serial.printf("Data parsed OK! AQI=%d, City=%s\n", aqiData.aqi, aqiData.city);
return true;
}
// ==================== 绘图小工具 ====================
void drawCN(int x, int y, const char* utf8, bool whiteOnBlack, const uint8_t* font) {
u8f.setFont(font);
if (whiteOnBlack) {
u8f.setForegroundColor(GxEPD_WHITE);
u8f.setBackgroundColor(GxEPD_BLACK);
} else {
u8f.setForegroundColor(GxEPD_BLACK);
u8f.setBackgroundColor(GxEPD_WHITE);
}
int baselineY = y + u8f.getFontAscent();
u8f.setCursor(x, baselineY);
u8f.print(utf8);
}
void drawCNCentered(int cx, int y, const char* utf8, bool whiteOnBlack, const uint8_t* font) {
u8f.setFont(font);
uint16_t w = u8f.getUTF8Width(utf8);
drawCN(cx - w / 2, y, utf8, whiteOnBlack, font);
}
void drawCNRight(int rightX, int y, const char* utf8, bool whiteOnBlack, const uint8_t* font) {
u8f.setFont(font);
uint16_t w = u8f.getUTF8Width(utf8);
drawCN(rightX - w, y, utf8, whiteOnBlack, font);
}
void drawBold(const GFXfont* font, const char* text, int x, int baselineY) {
display.setFont(font);
display.setTextColor(GxEPD_BLACK);
display.setCursor(x, baselineY);
display.print(text);
display.setFont(NULL);
}
void drawBoldCentered(const GFXfont* font, const char* text, int cx, int baselineY) {
display.setFont(font);
int16_t x1, y1; uint16_t w, h;
display.getTextBounds(text, 0, 0, &x1, &y1, &w, &h);
display.setFont(NULL);
drawBold(font, text, cx - w / 2 - x1, baselineY);
}
// ==================== 绘制 UI (横屏 400x300优化版) ====================
void drawUI() {
int W = display.width();
int H = display.height();
display.firstPage();
do {
display.fillScreen(GxEPD_WHITE);
// ---------- 顶部标题栏 (0-20) ----------
display.fillRect(0, 0, W, 20, GxEPD_BLACK);
drawCN(6, 6, "空气质量监测站", true, u8g2_font_wqy14_t_gb2312);
drawCNRight(W - 6, 5, aqiData.timeShort, true, u8g2_font_wqy12_t_gb2312);
// ---------- 位置行 (20-34) ----------
drawCN(6, 24, aqiData.city, false, u8g2_font_wqy14_t_gb2312);
char levelLine[24];
snprintf(levelLine, sizeof(levelLine), "%s · 主要污染: %s", getAqiLevelCN(aqiData.aqi), aqiData.dominentpol);
drawCNRight(W - 6, 24, levelLine, false, u8g2_font_wqy12_t_gb2312);
display.drawFastHLine(4, 36, W - 8, GxEPD_BLACK);
// ---------- AQI 大方块 (左, 40-181) [高度增加到141] ----------
int aqiBoxX = 6, aqiBoxY = 40, aqiBoxW = 118, aqiBoxH = 141;
display.drawRoundRect(aqiBoxX, aqiBoxY, aqiBoxW, aqiBoxH, 6, GxEPD_BLACK);
display.drawRoundRect(aqiBoxX + 1, aqiBoxY + 1, aqiBoxW - 2, aqiBoxH - 2, 5, GxEPD_BLACK);
drawCNCentered(aqiBoxX + aqiBoxW / 2, aqiBoxY + 12, "AQI 指数", false, u8g2_font_wqy12_t_gb2312);
char aqiStr[8];
snprintf(aqiStr, sizeof(aqiStr), "%d", aqiData.aqi);
drawBoldCentered(&FreeSansBold24pt7b, aqiStr, aqiBoxX + aqiBoxW / 2, aqiBoxY + 98);
drawCNCentered(aqiBoxX + aqiBoxW / 2, aqiBoxY + 114, getAqiLevelCN(aqiData.aqi), false, u8g2_font_wqy16_t_gb2312);
// ---------- 指标网格 (右, 40-181) [高度增加到141] ----------
int gridX = 130, gridY = 40, gridW = 264, gridH = 141;
int cols = 4, rows = 3;
int cellW = gridW / cols; // 66
int cellH = gridH / rows; // 47 (刚好整除)
struct Metric {
const char* label;
float value;
const char* unit;
int decimals;
};
Metric metrics[] = {
{"PM2.5", aqiData.pm25, "ug/m3", 0},
{"PM10", aqiData.pm10, "ug/m3", 0},
{"温度", aqiData.t, "C", 0},
{"湿度", aqiData.h, "%", 0},
{"O3", aqiData.o3, "ppb", 0},
{"NO2", aqiData.no2, "ppb", 0},
{"SO2", aqiData.so2, "ppb", 1},
{"CO", aqiData.co, "mg/m3", 1},
{"风速", aqiData.w, "m/s", 1},
{"阵风", aqiData.wg, "m/s", 1},
{"露点", aqiData.dew, "C", 1},
{"气压", aqiData.p, "hPa", 0},
};
for (int i = 0; i < 12; i++) {
int col = i % cols;
int row = i / cols;
int x = gridX + col * cellW;
int y = gridY + row * cellH;
int h = cellH;
display.drawRect(x, y, cellW, h, GxEPD_BLACK);
// 标签 (稍微靠下一两像素,居中感更好)
drawCN(x + 3, y + 4, metrics[i].label, false, u8g2_font_wqy12_t_gb2312);
// 数值 (粗体)
char valStr[12];
if (metrics[i].decimals == 0)
snprintf(valStr, sizeof(valStr), "%.0f", metrics[i].value);
else
snprintf(valStr, sizeof(valStr), "%.1f", metrics[i].value);
drawBold(&FreeSansBold9pt7b, valStr, x + 3, y + h - 8);
// 单位
display.setFont(NULL);
display.setTextSize(1);
int16_t tx, ty; uint16_t tw, th;
display.getTextBounds(metrics[i].unit, 0, 0, &tx, &ty, &tw, &th);
display.setCursor(x + cellW - tw - 3, y + h - 11);
display.print(metrics[i].unit);
}
// 中间分割线
display.drawFastHLine(4, 183, W - 8, GxEPD_BLACK);
// ---------- 预报区 (190-282) [高度由52增加至64,排版更宽松] ----------
drawCN(6, 190, "PM2.5 七日预测", false, u8g2_font_wqy12_t_gb2312);
drawCNRight(W - 6, 190, "紫外线预测", false, u8g2_font_wqy12_t_gb2312);
int barStartX = 6;
int barStartY = 204;
int barAreaW = 258;
int barAreaH = 64;
int barCount = min(aqiData.pm25ForecastCount, 7);
int barGap = 4;
int barW = (barCount > 0) ? (barAreaW - (barCount - 1) * barGap) / barCount : barAreaW;
int maxPm25 = 1;
for (int i = 0; i < barCount; i++)
if (aqiData.pm25Forecast[i].maxVal > maxPm25) maxPm25 = aqiData.pm25Forecast[i].maxVal;
for (int i = 0; i < barCount; i++) {
ForecastDay& f = aqiData.pm25Forecast[i];
int x = barStartX + i * (barW + barGap);
int maxH = (int)((float)f.maxVal / maxPm25 * (barAreaH - 14));
int avgH = (int)((float)f.avg / maxPm25 * (barAreaH - 14));
display.drawRect(x, barStartY + barAreaH - 14 - maxH, barW, max(maxH, 1), GxEPD_BLACK);
display.fillRect(x, barStartY + barAreaH - 14 - avgH, barW, max(avgH, 1), GxEPD_BLACK);
char dayLabel[3];
strncpy(dayLabel, f.day + 3, 2);
dayLabel[2] = '\0';
display.setFont(NULL);
display.setTextSize(1);
int16_t tx, ty; uint16_t tw, th;
display.getTextBounds(dayLabel, 0, 0, &tx, &ty, &tw, &th);
display.setCursor(x + (barW - tw) / 2, barStartY + barAreaH - 10);
display.print(dayLabel);
}
// PM2.5 图例
display.fillRect(barStartX, barStartY + barAreaH + 2, 6, 5, GxEPD_BLACK);
drawCN(barStartX + 9, barStartY + barAreaH + 1, "均值", false, u8g2_font_wqy12_t_gb2312);
display.drawRect(barStartX + 60, barStartY + barAreaH + 2, 6, 5, GxEPD_BLACK);
drawCN(barStartX + 69, barStartY + barAreaH + 1, "最大", false, u8g2_font_wqy12_t_gb2312);
// ---------- UV 紫外线小图表 ----------
int uvX = 272, uvY = 204, uvW = W - uvX - 6, uvH = barAreaH;
display.drawRect(uvX, uvY, uvW, uvH, GxEPD_BLACK);
int uvCount = min(aqiData.uviForecastCount, 6);
int uvBarGap = 3;
int uvBarW = (uvCount > 0) ? (uvW - 6 - (uvCount - 1) * uvBarGap) / uvCount : uvW;
int maxUvi = 1;
for (int i = 0; i < uvCount; i++)
if (aqiData.uviForecast[i].maxVal > maxUvi) maxUvi = aqiData.uviForecast[i].maxVal;
for (int i = 0; i < uvCount; i++) {
ForecastDay& u = aqiData.uviForecast[i];
int x = uvX + 3 + i * (uvBarW + uvBarGap);
int mH = (int)((float)u.maxVal / maxUvi * (uvH - 16));
int aH = (int)((float)u.avg / maxUvi * (uvH - 16));
if (mH > 0) display.drawRect(x, uvY + uvH - 12 - mH, uvBarW, mH, GxEPD_BLACK);
if (aH > 0) display.fillRect(x, uvY + uvH - 12 - aH, uvBarW, aH, GxEPD_BLACK);
char dayL[3];
strncpy(dayL, u.day + 3, 2);
dayL[2] = '\0';
display.setFont(NULL);
display.setTextSize(1);
display.setCursor(x, uvY + uvH - 10);
display.print(dayL);
}
// ---------- 最底部状态栏 (286-300) [上方留出少许清爽白边] ----------
display.fillRect(0, H - 14, W, 14, GxEPD_BLACK);
display.setFont(NULL);
display.setTextSize(1);
display.setTextColor(GxEPD_WHITE);
display.setCursor(6, H - 11);
display.print("aqicn.org | ESP32-S3");
char geoBot[24];
snprintf(geoBot, sizeof(geoBot), "%.2fN %.2fE", aqiData.lat, aqiData.lon);
int16_t tx, ty; uint16_t tw, th;
display.getTextBounds(geoBot, 0, 0, &tx, &ty, &tw, &th);
display.setCursor(W - tw - 6, H - 11);
display.print(geoBot);
} while (display.nextPage());
}
// ==================== 显示错误信息 ====================
void drawError(const char* msg) {
display.firstPage();
do {
display.fillScreen(GxEPD_WHITE);
display.drawRect(5, 5, display.width() - 10, display.height() - 10, GxEPD_BLACK);
display.setFont(NULL);
display.setTextColor(GxEPD_BLACK);
display.setTextSize(2);
display.setCursor(20, 40);
display.print("ERROR");
display.setTextSize(1);
display.setCursor(20, 80);
display.print(msg);
display.setCursor(20, 100);
display.print("Will retry in 30s...");
} while (display.nextPage());
}
// ==================== 自动选择横屏方向 ====================
void chooseLandscapeRotation() {
int candidates[4] = {1, 3, 0, 2};
int chosen = 1;
for (int i = 0; i < 4; i++) {
display.setRotation(candidates[i]);
if (display.width() > display.height()) {
chosen = candidates[i];
break;
}
}
if (ROTATION_FLIP) {
chosen = (chosen + 2) % 4;
display.setRotation(chosen);
}
Serial.printf("Rotation = %d -> W=%d H=%d\n", chosen, display.width(), display.height());
}
// ==================== SETUP ====================
void setup() {
Serial.begin(115200);
delay(1000);
Serial.println("\n=== ESP32-S3 Air Quality Monitor (v2.1) ===");
SPI.begin(EPD_CLK, -1, EPD_MOSI, EPD_CS);
display.init(115200, true, 2, false);
chooseLandscapeRotation();
u8f.begin(display);
u8f.setFontMode(1);
u8f.setFontDirection(0);
// 启动画面
display.firstPage();
do {
display.fillScreen(GxEPD_WHITE);
drawCNCentered(display.width() / 2, 90, "空气质量监测站", false, u8g2_font_wqy16_t_gb2312);
drawCNCentered(display.width() / 2, 130, "正在连接 WiFi...", false, u8g2_font_wqy14_t_gb2312);
} while (display.nextPage());
connectWiFi();
if (fetchAqiData()) {
drawUI();
} else {
drawError("Failed to fetch data");
}
display.powerOff();
}
// ==================== LOOP ====================
void loop() {
delay(UPDATE_INTERVAL_MS);
Serial.println("Refreshing data...");
if (WiFi.status() != WL_CONNECTED) {
connectWiFi();
}
if (fetchAqiData()) {
display.init(115200, true, 2, false);
chooseLandscapeRotation();
drawUI();
display.powerOff();
Serial.println("Screen updated successfully.");
} else {
Serial.println("Data fetch failed, will retry next cycle.");
}
}
代码说明
第一步,connectWiFi() 里做的是标准的 WiFi 连接,重试 40 次(20 秒),超时不会卡死,会继续往下走,方便离线也能先看到错误提示而不是黑屏。
第二步,fetchAqiData() 用 HTTPClient 请求 AQICN 的 /feed/@城市ID/ 接口,拿到 JSON 后用 ArduinoJson 的 JsonDocument 解析,逐个字段填进 AqiData 结构体,包括当前 12 项指标和未来几天的 PM2.5/PM10/紫外线预测数组。
第三步,drawUI() 是整个绘图的核心,按“标题栏 → AQI 大方块 → 12 项指标网格 → 预报柱状图 → 底部状态栏”的顺序分区块画,每个区块的坐标都是写死的像素值,方便照着改布局。
第四步,中文靠 U8g2_for_Adafruit_GFX 这层桥接来画,drawCN 系列函数统一封装了黑底白字/白底黑字两种模式,避免每处都重复设置颜色。
第五步,loop() 里每 30 分钟刷新一次,重新初始化屏幕后调用 drawUI(),用完立刻 powerOff() 断电,这是墨水屏省电和护屏的关键——不刷新的时候完全不用给它供电。
常见问题排查
别慌,80% 的问题出在这几个地方:
屏幕一直白屏/花屏:先排查接线,尤其是 CS、DC、RES、BUSY 这四根控制线是否插错顺序;其次确认 display.init() 里的驱动类 GxEPD2_420_GYE042A87 和手上屏幕的真实型号一致,型号不对会导致时序错乱。
中文显示成方块或乱码:说明 U8g2_for_Adafruit_GFX 没有正确初始化,检查 u8f.begin(display) 是否在 display.init() 之后调用,并确认使用的字库(如 u8g2_font_wqy14_t_gb2312)里包含要显示的汉字。
WiFi 连不上:确认开发板只支持 2.4GHz,不支持 5GHz WiFi;SSID 和密码是否有中文或特殊字符导致转义问题。
API 返回数据全是 0:大概率是 API_TOKEN 没申请或者写错,也可能是 API_URL 里的城市 ID(如 @14370)不对,先用浏览器直接打开这个链接确认能返回正常 JSON。
画面上下颠倒:把代码里的 ROTATION_FLIP 从 0 改成 1,重新烧录即可,不用改接线。
**编译时报「空间不足 / region app' overflowed」**:是中文字库太大撑爆了默认分区,按上文「烧录配置:分区方案」一节,把 Partition Scheme改成Huge APP (3MB No OTA/1MB SPIFFS)` 再编译即可。
FAQ 问答
Q:ESP32-S3 换成普通 ESP32 能不能用? A:可以,只要引脚支持 SPI 且不是被开发板占用的特殊引脚(如 Flash 相关引脚),把代码里 6 个 EPD_* 宏定义改成实际接线的 GPIO 编号即可,其余代码不用动。
Q:GxEPD2_420_GYE042A87 这个驱动类不匹配我的屏幕怎么办? A:去 GxEPD2 库的 GitHub 仓库里查对应型号的驱动类名,替换 display 定义那一行即可,其他绘图代码通常不需要改。
Q:为什么刷新一次要好几秒,能不能更快? A:黑白墨水屏的全刷新(Full Refresh)本身就慢,这是硬件特性,不是代码问题;如果只更新局部数字,可以研究 GxEPD2 的局部刷新(Partial Update)接口,但会有残影风险。
Q:AQICN API 的免费额度够用吗? A:AQICN 个人 Token 免费额度通常是每分钟 1000 次请求,本项目 30 分钟才请求一次,完全够用,不用担心超限。
Q:ESP32-S3 不刷新的时候功耗大概多少? A:代码里没有加深度睡眠,loop() 里用 delay() 挂起,实测典型功耗在几十毫安级别;如果要做电池供电版本,建议把 delay(UPDATE_INTERVAL_MS) 换成 esp_deep_sleep,功耗能降到微安级。
Q:屏幕一直不刷新,但串口监视器显示数据抓取成功怎么办? A:检查 drawUI() 里的 display.firstPage()/nextPage() 循环是否被中途 return 打断,GxEPD2 要求这个循环必须完整跑完一次才会真正把画面推到屏幕上。
延伸玩法
- 从 SD 卡读取本地城市列表,做成多城市轮播看板
- 接一个按键,短按手动刷新,长按切换到深度睡眠省电模式
- 把 30 分钟更新间隔改成读取环境光传感器,天黑自动降低刷新频率