ESP32-S3 驅動 ST7262 RGB 螢幕點亮 + LVGL 儀表板完整教學(Waveshare Touch-LCD-5B / 1024×600)

用 ESP-IDF 在 Waveshare ESP32-S3-Touch-LCD-5B(5 吋 1024×600、ST7262 RGB 直驅)上從零點亮 RGB 螢幕,接上 LVGL,做成一個會動的車輛遙測儀表板。講清楚 CH422G 背光控制、PCLK 調參、PSRAM 雙緩衝區與緩動動畫,附完整 ESP-IDF 程式碼與避坑清單。

ESP32-S3 驅動 ST7262 RGB 螢幕點亮 + LVGL 儀表板完整教學(Waveshare Touch-LCD-5B / 1024×600)

難度:⭐⭐⭐☆☆(會點 C、摸過 ESP-IDF 即可上手) 預計時間:2~3 小時(含環境搭建) 測試環境:ESP-IDF 5.3.x(或 5.2.7 補一行巨集)+ LVGL ^9.3 + espressif/esp_lvgl_port 2.8


一句話摘要:用 ESP-IDF 在 Waveshare ESP32-S3-Touch-LCD-5B(5 吋 1024×600、ST7262 純 RGB 直驅)上從黑屏一路點亮 RGB 螢幕、接上 LVGL,最終做成一個會動的車輛遙測儀表板。踩過的坑(解析度騙局、PCLK 白屏、LVGL 記憶體白屏、撕裂與不順滑)和填坑程式碼全在這。


TL;DR(快速上手):

  1. 認清家底:5B 是 1024×600、驅動 IC ST7262、純 RGB 直驅——別信官方例程預設的 800×480。
  2. PCLK 用 16MHz:別抄板卡定義的 21MHz,PSRAM 存畫面時供不上會全白。
  3. 背光走 CH422G:不是普通 GPIO,也不是 PWM,往 I²C 地址 0x38 寫一個 byte 就開關。
  4. 跑 LVGL 必開兩個巨集:LV_USE_CLIB_MALLOC=y + SPIRAM_USE_MALLOC=y,否則白屏 + 看門狗重開。
  5. idf.py build flash monitor,點亮,開香檳。

前言

這週末出門在外,朋友買了一塊 Waveshare 的 ESP32-S3-Touch-LCD-5B,能燒寫上官方的韌體正常顯示,但無法用程式碼點亮,使用官方例子則又黑又白的,完全搞不通。於是我拿過來接手折騰。這是一塊 5 吋、1024×600 的 RGB 電容觸控螢幕開發板。板子不貴,配置卻挺豪華——CAN、RS485、RTC、鋰電池充電全都有,自帶 16MB Flash + 8MB PSRAM。

於是,我接手過來嘗試點亮它,畢竟最近很喜歡點亮螢幕。但點亮它的過程,坑比我預想的多。最勸退的一點是:你照著 Waveshare 官方的文件和例程來,點不亮。 不是你菜,是官方的資源壓根不是為這塊 5B 準備的。

我把整個過程拆成了三個遞進的小例子,程式碼都放在了 GitHub(本專案完整目錄,三個例子都在裡面):

  1. 點亮螢幕:最樸素的方式,顯示一行 Hello World → 01 HelloWorld
  2. 接上 LVGL:做一個帶指標動畫的半圓速度表 → 02 Speedometer
  3. 做成儀表板:改成一個有設計感的車輛遙測面板 → 03 VehicleTelemetry

本文目標:把這三步裡踩過的坑、為什麼這麼填的程式碼、以及一份能直接抄的避坑速查清單交給你,讓你少熬幾個通宵。


實驗效果

最終你能得到一個會動的車輛遙測儀表板:轉速、油門、水溫、車速、電壓五個資料卡片,數值帶緩動逼近、進度條過載變紅、指標動畫絲滑不撕裂。



一、開發板說明:先認清這塊 5B

正式踩坑前,先把這塊 ESP32-S3-Touch-LCD-5B 的硬體參數擺出來。後面的坑——PCLK 該填多少、記憶體夠不夠、哪幾隻腳共用同一條 I²C——基本都圍著這張表轉,對著看會順很多。

螢幕(最該先認清的就是它)

項目 規格
尺寸 5 吋
面板類型 IPS
解析度 1024 × 600(實測,官方文件沒單獨標 5B,預設卻是 800×480——這是第一章的大坑)
顯示色彩 65K 色
介面 RGB(並列),驅動 IC ST7262,純 RGB 直驅、不用發 SPI 初始化命令
視角 175°
亮度 550 cd/m²
觸控 電容式觸控(含玻璃面板)
背光升壓晶片 AP3032KTR-G1

ST7262 是一塊 RGB 介面的液晶面板驅動 IC(Sitronix 出品),負責接收並列 RGB 訊號並驅動液晶分子,在本專案裡你完全不用給它發初始化命令——通電、給對時序、餵資料,它自己就亮。這點省了好多事。

主控晶片(MCU)

項目 規格
模組 ESP32-S3-WROOM-1-N16R8
核心 Xtensa 32-bit LX7 雙核,最高 240 MHz
Flash 16 MB
PSRAM 8 MB(octal SPI)
內部 SRAM 512 KB
無線 Wi-Fi 2.4 GHz(802.11 b/g/n)、藍牙 5(LE),板載天線
USB 全速 (Full-Speed) USB,板載 Type-C

PSRAM 是晶片外接的一塊「大但慢」的記憶體。整屏畫面(framebuffer)就放在這 8MB 裡,由 DMA 不停往螢幕搬。那塊 8MB PSRAM 就是存整屏畫面的地方。 PSRAM 配錯成 quad 是常見坑(詳見第七章)。

觸控

項目 規格
觸控 IC GT911
類型 電容式
支援點數 5 點觸控
介面 I²C
I²C 地址 0x5D

GT911 是一顆電容觸控控制器,負責把手指位置轉成數位座標,透過 I²C 上報。在本專案裡它和 RTC、CH422G 共用同一條 I²C(GPIO8/GPIO9),地址要規劃好。本系列例子還沒接觸控,是後續待辦。

供電與介面

項目 規格
供電 Type-C 5V / DC 7–36V / 單節鋰電池 3.7V(MX1.25)
功耗 5V / 450 mA(典型)
CAN 相容 CAN 2.0(TJA1051,120Ω 終端電阻預設關閉)
RS485 SP3485 收發器(120Ω 終端電阻預設關閉)
工作溫度 0 °C ~ 65 °C
尺寸 裸板 112.4 × 75.1 mm / 含外殼 116.3 × 79 mm

二、板載資源映射(開發板自帶,不用接線)

⚠️ 這塊板是開發板,元件已經焊好,下面這些是板載資源映射,給你查腳位 / 配 SDK 用,不是讓你拿杜邦線去接線。 你要做的只有:Type-C 插上電、USB 插上電腦刷韌體。

螢幕 RGB 介面腳位

以下對應官方文件,並經實機驅動核對。注意 GPIO0 是 strapping 腳(詳見第七章避坑清單)。

ESP32-S3 GPIO LCD 訊號 說明
GPIO0 G3 Green 資料 bit3
GPIO1 R3 Red 資料 bit3
GPIO2 R4 Red 資料 bit4
GPIO3 VSYNC 垂直同步
GPIO4 TP_IRQ 觸控中斷
GPIO5 DE 資料使能
GPIO7 PCLK 像素時脈(實測 16MHz 穩)
GPIO10 B7 Blue 資料 bit7
GPIO14 B3 Blue 資料 bit3
GPIO17 B6 Blue 資料 bit6
GPIO18 B5 Blue 資料 bit5
GPIO21 G7 Green 資料 bit7
GPIO38 B4 Blue 資料 bit4
GPIO39 G2 Green 資料 bit2
GPIO40 R7 Red 資料 bit7
GPIO41 R6 Red 資料 bit6
GPIO42 R5 Red 資料 bit5
GPIO45 G4 Green 資料 bit4
GPIO46 HSYNC 水平同步
GPIO47 G6 Green 資料 bit6
GPIO48 G5 Green 資料 bit5

觸控 / RTC / 外部 I²C(共用匯流排)

ESP32-S3 GPIO 訊號 說明
GPIO8 SDA / TP_SDA / RTC_SDA I²C 資料(觸控 GT911、RTC PCF85063、外部 I²C 共用)
GPIO9 SCL / TP_SCL / RTC_SCL I²C 時脈(同上共用)
GPIO4 TP_IRQ 觸控中斷

USB / SD / RS485 / CAN

功能 ESP32-S3 GPIO 說明
USB D- / D+ GPIO19 / GPIO20 全速 USB
SD MOSI / SCK / MISO GPIO11 / GPIO12 / GPIO13 SD 卡(SPI)
SD CS (CH422G EXIO4) 低態,由 IO 擴展器控制,不在原生 SPI CS 上
RS485 RXD / TXD GPIO43 / GPIO44 SP3485
CAN TX / RX GPIO15 / GPIO16 TJA1051

一個繞不開的晶片:CH422G IO 擴展器

板上那塊背光、重置都掛在它身上的晶片就是 CH422G,走 I²C 操作。它的怪癖是:沒有暫存器指標,直接把 I²C 地址當命令用。

CH422G 是一顆 I²C 介面的 IO 擴展器,負責把背光、螢幕重置、觸控重置、SD 卡片選這些零碎訊號統一管起來,在本專案裡你靠它點亮背光、重置螢幕。

CH422G 腳位 功能 說明
EXIO0 DI0 數位輸入 0
EXIO1 TP_RST 觸控重置
EXIO2 DISP 背光使能(只能開關,不能調亮度)
EXIO3 LCD_RST 螢幕重置
EXIO4 SD_CS SD 卡片選(低態)
EXIO5 DI1 數位輸入 1
OD0 DO0 數位輸出 0
OD1 DO1 數位輸出 1

三、需要安裝的:ESP-IDF 工具鏈 + 元件

這塊板不需要裝庫,但它用的是 ESP-IDF(樂鑫官方的開發框架)而不是 Arduino。原因:RGB 直驅 + PSRAM framebuffer + LVGL 這套組合,sdkconfig 裡幾十個開關(PCLK、PSRAM 模式、記憶體池)在 ESP-IDF 裡好控得多,Arduino 裡調參很彆扭。

準備清單(建議照著核對,能省 80% 排錯時間):

  • ESP-IDF 5.3.x(推薦)。用 5.2.7 也能跑,但要補一行巨集(見第七章)。
  • LVGL ^9.3(esp_lvgl_port 2.8 依賴 9.3 新增的顏色常數)。
  • espressif/esp_lvgl_port 2.8(幫你搞定 LVGL 的時脈、獨立任務、加鎖)。
  • Windows 使用者:用 PowerShell + EIM profile,別在 Git Bash 裡跑 idf.py(它偵測到 MSYSTEM 就罷工)。

元件版本一定要同代配對:esp_lvgl_port 2.8 配 LVGL ^9.3,配錯了編譯就報 RGB565_SWAPPED undeclared。


四、第一步:點亮螢幕(別直接套官方例程)

📦 本章完整程式碼:01 HelloWorld —— 最樸素的方式,點亮螢幕、顯示一行 Hello World。

這是整件事最大的坑,也是我最想先說的。

Waveshare 官方的 ESP-IDF 例程(比如 08_lvgl_Porting)和文件,基本都是按 800×480 來寫的。 它的 #else 預設分支就是 800×480。官方文件更是把整個 5 吋系列籠統標成「800×480 或 1024×600」,偏偏沒單獨標 5B 是多少。

你如果二話不說把官方例程直接燒進 5B,會得到一個很迷惑的畫面:螢幕一大片黑、右邊冒出一條白邊(黑+白)。這不是壞了,是「用 800×480 的訊號去餵一塊 1024×600 的面板」——面板比訊號寬,多出來的右邊沒有訊號,就顯示成那樣。

加上 Waveshare 的命名習慣裡**「B 後綴常代表方屏」**(比如 4B 是 480×480 方屏),我一度懷疑 5B 是塊 720×720 的方屏、還得先走 SPI 初始化。折騰一圈才確認:5B 就是 1024×600,ST7262 驅動 IC,純 RGB 直驅,不用發任何 SPI 初始化命令。 這點很重要,省了好多事。

所以第一步永遠是:別信官方例程的解析度,自己確認清楚你手上這塊到底是多少。

確認的笨辦法就是上面那個——拿 800×480 去餵,右邊出白邊,反證出它是 1024×600(面板比訊號寬才會這樣)。

4.1 開機流程(6 步骨架)

搞清脾氣後開始點亮。開機流程其實就 6 步:I²C 起來 → CH422G 重置螢幕 → 建 RGB 面板 → 畫畫面 → 開背光 → CPU 閒著,靠 DMA 自刷新。

其中「畫好畫面再最後開背光」很關鍵——避免開機那一 frame 花屏。落在程式碼裡,點亮的順序是固定的:

/* 第一步:先把 I²C 匯流排拉起來(GPIO8/9,和觸控 GT911、RTC 共用一條)。*/
i2c_master_bus_handle_t i2c_bus = NULL;
i2c_master_bus_config_t bus_cfg = {
    .sda_io_num = 8, .scl_io_num = 9, .clk_source = I2C_CLK_SRC_DEFAULT,
    .flags.enable_internal_pullup = true,
};
i2c_new_master_bus(&bus_cfg, &i2c_bus);

/* 第二步:驅動 CH422G——先重置、再放開(這一步背光仍關著)。*/
ch422g_handle_t io = {0};
ch422g_init(&io, i2c_bus);
ch422g_set_outputs(&io, 0);                              /* EXIO 全拉低:重置 + 背光關 */
vTaskDelay(pdMS_TO_TICKS(10));
ch422g_set_outputs(&io, CH422G_LCD_RST | CH422G_TP_RST); /* 放開重置,背光仍關 */
vTaskDelay(pdMS_TO_TICKS(120));                          /* 等面板起來 */

/* 第三步:建 RGB 面板、把畫面畫進 PSRAM framebuffer(見下一段)……*/

/* 第四步:畫面備好,最後一步才點亮背光——把 EXIO2 寫高。*/
ch422g_set_outputs(&io, CH422G_LCD_RST | CH422G_TP_RST | CH422G_BL);

順序鐵律:背光永遠最後開。 重置時 EXIO 全拉低(背光關),重置放開後再畫畫面,畫面備好才把 EXIO2 寫高。反過來先亮背光再畫,會看到開機一 frame 花屏。

4.2 背光怎麼「寫高就亮」:CH422G 最小驅動

背光的「寫高就亮」,落到程式碼裡就兩件事:寫一個 CH422G 的驅動,再在開機流程裡按對的順序呼叫它。驅動核心就一點——地址即暫存器,往 0x24 寫模式、往 0x38 寫一個 byte(這個 byte 就是 8 路輸出的電平)。最小驅動長這樣(完整版見倉庫 main/ch422g.c):

/* CH422G「暫存器」= I²C 7-bit 裝置地址本身(沒有單獨的暫存器 byte)。*/
#define CH422G_REG_MODE  0x24   /* 寫 0x01 -> EXIO0..7 推挽輸出 */
#define CH422G_REG_OUT   0x38   /* 寫一個 byte -> EXIO0..7 的電平 */

/* EXIO 輸出位:bit n = EXIO_n 的電平(1 = 高)。*/
#define CH422G_TP_RST   (1u << 1)   /* EXIO1 觸控重置 */
#define CH422G_BL       (1u << 2)   /* EXIO2 背光使能 */
#define CH422G_LCD_RST  (1u << 3)   /* EXIO3 螢幕重置 */

/* 兩個「地址即暫存器」各建一個 I²C 裝置 handle。*/
esp_err_t ch422g_init(ch422g_handle_t *ch, i2c_master_bus_handle_t bus) {
    i2c_device_config_t mode_cfg = { .device_address = CH422G_REG_MODE, .scl_speed_hz = 100000 };
    i2c_master_bus_add_device(bus, &mode_cfg, &ch->dev_mode);
    i2c_device_config_t out_cfg  = { .device_address = CH422G_REG_OUT,  .scl_speed_hz = 100000 };
    i2c_master_bus_add_device(bus, &out_cfg,  &ch->dev_out);

    uint8_t mode = 0x01;                              /* 推挽輸出模式 */
    i2c_master_transmit(ch->dev_mode, &mode, 1, -1);
    uint8_t zero = 0;
    i2c_master_transmit(ch->dev_out,  &zero, 1, -1);  /* 起始全清零 */
    return ESP_OK;
}

/* 一個 byte 就是 8 路輸出電平——這就是「把地址當命令用」。*/
esp_err_t ch422g_set_outputs(ch422g_handle_t *ch, uint8_t exio_mask) {
    return i2c_master_transmit(ch->dev_out, &exio_mask, 1, -1);
}

4.3 建 RGB 面板(本章核心)

建面板這段是整章的核心,後面三個坑會逐個解釋每行為什麼這麼填:

#define LCD_H_RES        1024
#define LCD_V_RES        600
#define LCD_PIXEL_CLK_HZ (16 * 1000 * 1000)   /* ← 坑 1:16MHz,不是板卡定義的 21MHz */

/* RGB565 裡綠是 6 位 (0..63)、紅藍 5 位 (0..31),純白要寫 31,63,31(← 坑 2)。*/
#define RGB565(r, g, b)   ((((r) & 0x1F) << 11) | (((g) & 0x3F) << 5) | ((b) & 0x1F))
#define COLOR_BG          RGB565(2, 8, 20)     /* 深藍底 */
#define COLOR_FG          RGB565(31, 63, 31)   /* 真·白 */

esp_lcd_rgb_panel_config_t panel_cfg = {
    .data_width = 16,                          /* RGB565 = 16 位元 */
    .bounce_buffer_size_px = 10 * LCD_H_RES,   /* SRAM bounce:防 16MHz 下供不上白屏 */
    .disp_gpio_num = -1,                       /* 背光在 CH422G 上,不是 GPIO */
    .pclk_gpio_num  = 7, .vsync_gpio_num = 3, .hsync_gpio_num = 46, .de_gpio_num = 5,
    .data_gpio_nums = {
        14, 38, 18, 17, 10,        /* B3..B7 */
        39,  0, 45, 48, 47, 21,    /* G2..G7 */
         1,  2, 42, 41, 40,        /* R3..R7 */
    },
    .timings = {
        .pclk_hz = LCD_PIXEL_CLK_HZ,           /* ← 坑 1 */
        .h_res = LCD_H_RES, .v_res = LCD_V_RES,
        .hsync_pulse_width = 30, .hsync_back_porch = 40, .hsync_front_porch = 220,
        .vsync_pulse_width = 4,  .vsync_back_porch  = 8,  .vsync_front_porch = 4,
        .flags.pclk_active_neg = true,
    },
    .flags.fb_in_psram = true,                 /* 整屏 ~1.17MB framebuffer 放 PSRAM */
};
esp_lcd_new_rgb_panel(&panel_cfg, &panel);
esp_lcd_panel_init(panel);                     /* ← 坑 3:建完面板補這一行 */

面板建好後,拿到 framebuffer 就能直接往上寫像素——ESP-IDF 的 RGB 面板不提供 draw_bitmap 之外的繪圖原語,所以 helloworld 裡自帶了 lcd_fill / lcd_draw_text 兩個小工具(點陣字庫,見倉庫 lcd_draw.c):

/* 拿到 PSRAM 裡的 framebuffer,畫 Hello World。*/
void *fb = NULL;
esp_lcd_rgb_panel_get_frame_buffer(panel, 1, &fb);
lcd_draw_init((uint16_t *)fb, LCD_H_RES, LCD_V_RES);
lcd_fill(COLOR_BG);
lcd_draw_text((LCD_H_RES - tw) / 2, (LCD_V_RES - th) / 2, "Hello World!", 5, COLOR_FG);

/* 畫面備好,最後開背光。之後 DMA 自己從 PSRAM 刷屏,CPU 閒著。*/
vTaskDelay(pdMS_TO_TICKS(60));
ch422g_set_outputs(&io, CH422G_LCD_RST | CH422G_TP_RST | CH422G_BL);

4.4 三個讓我實際栽過的坑

坑 1:PCLK 抄高了,整屏全白。 把官方 Arduino 板卡定義抄過來時,像素時脈(PCLK)填的是 21MHz,結果螢幕一片慘白(不是黑屏)。真相是:畫面放在 PSRAM 裡,要被 DMA 連續讀出來送給螢幕。21MHz × 16 位元 ≈ 每秒 336M 位的頻寬,對「PSRAM → DMA → 螢幕」這條路來說太撐了,一旦供不上,螢幕收不到有效同步訊號,乾脆顯示「無訊號」的白底。降到 16MHz,穩了。

坑 2:白字變粉紅,差點去重排腳位。 點亮後白字顯示成了粉紅色,第一反應是綠色腳位排反了——錯。真正原因是 RGB565 裡綠是 6 位(0–63),紅藍才 5 位(0–31)。RGB565(31, 31, 31) 裡綠色的 31 在 0–63 只有不到一半,紅藍滿、綠一半,混出來就是粉。改成 RGB565(31, 63, 31) 才是真白。偏色分兩種:白變青 = 腳位順序問題;白變粉 = 數值填錯。

坑 3:漏了一行初始化。 正典流程是「建面板 → 重置 → 初始化 → 開顯示」,我一開始只調了建面板那一步。多數情況建完會自動開始掃描,但補一行 esp_lcd_panel_init() 能排除「DMA 沒啟動」的隱患——少了它可能時而亮時而不亮。

4.5 一招最值錢的:先看「怎麼個不亮法」

面對「點不亮」,最有用的一招是先看螢幕到底是怎麼個不亮法:

  • 完全沒背光 → CH422G / 重置序列的事
  • 背光亮但全白/全灰 → RGB 訊號沒給對(最常見,查 PCLK 和時序)
  • 背光亮但花屏/抖動 → 訊號有了,時序參數差點意思
  • 背光亮但顏色錯(白變青) → RGB 通道順序排錯了

就這一個觀察,能把問題劈成兩半,省掉一堆瞎猜。


五、第二步:接上 LVGL,做指標動畫

📦 本章完整程式碼:02 Speedometer —— 接上 LVGL,做一個帶指標動畫的半圓速度表。

點亮之後想做個會動的介面,上了 LVGL(嵌入式上很流行的圖形庫)。接法是官方推薦的 espressif/esp_lvgl_port 元件,它幫你搞定 LVGL 的時脈、獨立任務、加鎖,把畫好的畫面刷到螢幕上。

LVGL 是一個開源的嵌入式圖形庫,負責把按鈕、進度條、動畫這些 UI 元素畫出來,在本專案裡你靠它做速度表和儀表板,而不是自己一行行寫繪圖程式碼。

接法本身不長,核心就是建好 RGB 面板(speedometer 例子裡比 helloworld 多了一行 .num_fbs = 2,這就是後面防撕裂的雙 framebuffer),再交給 esp_lvgl_port:

const lvgl_port_cfg_t lvgl_cfg = ESP_LVGL_PORT_INIT_CONFIG();
lvgl_port_init(&lvgl_cfg);

const lvgl_port_display_cfg_t disp_cfg = {
    .panel_handle  = panel,
    .buffer_size   = LCD_H_RES * LCD_V_RES, /* 全屏:direct mode 的硬要求 */
    .hres          = LCD_H_RES, .vres = LCD_V_RES,
    .color_format  = LV_COLOR_FORMAT_RGB565,
    .flags = {
        .direct_mode = true,   /* 直接畫進面板的 framebuffer,省一次拷貝 */
        .buff_dma    = false,
        .buff_spiram = true,   /* 繪圖緩衝區放 PSRAM(← 坑 1:得先開 SPIRAM_USE_MALLOC)*/
        .swap_bytes  = false,  /* 並列 RGB 面板,不做 byte order 交換 */
    },
};
const lvgl_port_display_rgb_cfg_t rgb_cfg = {
    .flags = {
        .bb_mode       = true,  /* 用了 bounce buffer → 走 on_bounce_frame_finish 同步 */
        .avoid_tearing = true,  /* frame 邊界切 fb → 防撕裂(見本章末)*/
    },
};
lvgl_port_add_disp_rgb(&disp_cfg, &rgb_cfg);

/* 任何 lv_* 呼叫都得先拿這把鎖,免得和 esp_lvgl_port 的渲染任務撞車。*/
lvgl_port_lock(0);
dashboard_create();   /* 建速度表 + 啟動指標動畫 */
lvgl_port_unlock();

三個 flag 是這段的精髓:direct_mode 讓 LVGL 直接畫進面板 framebuffer(少一次整屏拷貝);avoid_tearing 讓兩塊 fb 在 frame 邊界切換(防撕裂);buff_spiram 把繪圖緩衝區挪進 PSRAM——這個看著無害,恰恰引出了下面最大的坑。

5.1 坑 1(最隱蔽):白屏 + 看門狗重開

接好燒進去,螢幕先是黑兩秒,然後全白,再不動了。這症狀跟前面 PCLK 太高導致的白屏一模一樣,我差點又一頭扎進去調時序。

幸虧這次先打開串口看開機 log,一眼看到關鍵一行:

E task_wdt: CPU 0: taskLVGL

LVGL 的任務觸發了看門狗,被系統判定卡死。這是軟體卡住,不是訊號問題。 順著呼叫堆疊查,發現 LVGL 第一次畫整屏時要臨時申請一塊 MB 級的繪圖緩衝區,可 LVGL 預設用的是它自己內建的小記憶體池,只有 64KB——1MB 塞不進 64KB,於是反覆折騰,畫不完,任務卡死,看門狗發火。

有意思的是:我明明把顯示緩衝區設在了 PSRAM,怎麼還說記憶體不夠?因為顯示緩衝區(給「刷屏」用)和 LVGL 內部繪圖用的記憶體池(給「算畫面」用)是兩碼事,別混。解法就兩個開關:

CONFIG_LV_USE_CLIB_MALLOC=y    # LVGL 改用系統的 malloc,不用那 64KB 小池子
CONFIG_SPIRAM_USE_MALLOC=y     # 讓系統 malloc 能去 PSRAM 拿大塊記憶體

這裡還有個更要命的認知:同樣是「白屏」,至少有兩種完全不同的成因。 一種是 RGB 訊號/頻寬問題(前面 PCLK 那個),一種是軟體卡死沒畫到畫面(這個)。永遠先看串口 log 分辨,別看到白屏就調時序。

5.2 坑 2、3:元件版本與 IDF 巨集對不上

  • 坑 2(元件版本要配對):esp_lvgl_port 2.8 內部用到了 LVGL 9.3 才新增的顏色常數。把 LVGL 版本釘成 ~9.2 會報 RGB565_SWAPPED undeclared,改成 ^9.3 就好。
  • 坑 3(IDF 巨集對不上):新版 esp_lvgl_port 檢查 SOC_LCDCAM_RGB_LCD_SUPPORTED 這個巨集,但它 IDF 5.3 才改名,5.2.7 裡還是舊名,執行時報 “This target does not support RGB”。解法是在頂層 CMakeLists 的 project() 之前補一行 add_compile_definitions(SOC_LCDCAM_RGB_LCD_SUPPORTED=1)。

5.3 「不順滑」和「畫面撕裂」,都不是算得慢

速度表跑起來後兩個新問題:指標動得不夠順,還會撕裂(畫面中間一道錯位的橫線)。這倆都跟「算得快不快」沒關係。

先說不順。 這塊螢幕的物理更新率我先算了:PCLK 16MHz ÷ 一 frame 總像素數 ≈ 20Hz。也就是說這塊螢幕一秒最多只能重畫 20 次畫面,軟體再快也沒用,是硬天花板。所以「順不順」不是更新率問題,是動畫曲線問題。指標勻速掃到頭、瞬間反向,特別生硬;換成 ease-in-out(兩端減速、中間加速),轉折就自然了。

/* 270° 速度表:ROUND_INNER 模式,從 135° 起轉,底部留 90° 缺口。*/
lv_obj_t *scale = lv_scale_create(scr);
lv_obj_set_size(scale, 460, 460);
lv_scale_set_mode(scale, LV_SCALE_MODE_ROUND_INNER);
lv_scale_set_range(scale, 0, 120);
lv_scale_set_angle_range(scale, 270);
lv_scale_set_rotation(scale, 135);          /* 起始角度,決定缺口朝向 */
lv_scale_set_total_tick_count(scale, 25);   /* 每 5 km/h 一格 */
lv_scale_set_major_tick_every(scale, 4);    /* 每 4 格一個主刻度 → 0,20,...,120 */

/* 動畫每一 frame 被呼叫:把指標指到 v。數字讀數只在整數變化時才刷新。*/
static void gauge_set_value(void *var, int32_t v) {
    gauge_ctx_t *g = (gauge_ctx_t *)var;
    lv_scale_set_line_needle_value(g->scale, g->needle, 150, v);  /* 指標,150px 長 */
    int vi = (int)v;
    if (vi != g->last_int) {                 /* 整數沒變就不動 label,省掉重畫 */
        g->last_int = vi;
        lv_snprintf(s_value_buf, sizeof(s_value_buf), "%03d", vi);
        lv_label_set_text(g->value_label, s_value_buf);
    }
}

/* 0 → 120 → 0,無限循環。順不順,關鍵就在最後一行。*/
lv_anim_t a;
lv_anim_init(&a);
lv_anim_set_var(&a, &s_ctx);
lv_anim_set_exec_cb(&a, gauge_set_value);
lv_anim_set_values(&a, 0, 120);
lv_anim_set_duration(&a, 2500);                       /* 單程 2.5s */
lv_anim_set_playback_duration(&a, 2500);              /* 回程:0→120→0 */
lv_anim_set_path_cb(&a, lv_anim_path_ease_in_out);    /* ← 兩端減速,轉折才不生硬 */
lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);
lv_anim_start(&a);

關鍵就是 lv_anim_set_path_cb(&a, lv_anim_path_ease_in_out) 這一行。playback_duration 讓動畫到 120 自動折返回 0,折返瞬間速度本來會硬生生反向;ease-in-out 讓它先減速到 0 再反向加速,肉眼幾乎看不出轉向。

再說撕裂。 原因是只準備了一塊畫面緩衝區,DMA 在不停往外搬,LVGL 同時往裡寫新的,沒同步,就搬出「半新半舊」的一 frame。解法是雙緩衝 + 垂直同步切換:兩塊畫面,DMA 永遠只搬完整的那塊。注意:我們這塊螢幕必須保留一個叫 bounce buffer 的小緩衝區(防 16MHz 下供不上白屏),所以是「雙緩衝 + bounce 一起用」,不能照官方例程把 bounce 關掉。

在這塊螢幕上,「順」靠緩動曲線,「不撕裂」靠雙緩衝,都跟算得快不快無關。


六、第三步:做成一塊車輛遙測儀表板

📦 本章完整程式碼:03 VehicleTelemetry —— 改成一個有設計感的五卡片車輛遙測面板。

最後把速度表換成了一個像模像樣的車輛遙測面板:轉速、油門、水溫、車速、電壓五個資料,每張卡片有大數字、進度條、最低最高刻度,數值過載了還會變紅。資料是隨機模擬的,但動作要自然。

6.1 卡片怎麼搭出來

每張卡片就是個去掉了預設樣式的 lv_obj 容器,裡面塞標籤、單位、大數字、進度條、min/max 刻度。座標全部直接寫死,靠 1px 邊框 + 純色分層(不用陰影)。核心長這樣(完整版見 lvgl_dashboard.c 的 make_card):

static void make_card(lv_obj_t *parent, int i) {
    const metric_cfg_t *c = &CFG[i];      /* 幾何/範圍/危險閾值/顏色都在配置表裡 */
    metric_t *m = &s_m[i];
    m->accent = lv_color_hex(c->accent_hex);

    lv_obj_t *card = lv_obj_create(parent);
    lv_obj_remove_style_all(card);                       /* 清掉預設樣式,全部自己設 */
    lv_obj_set_pos(card, c->x, c->y);                    /* 座標寫死,不用 flex 自動排版 */
    lv_obj_set_size(card, c->w, c->h);
    lv_obj_set_style_bg_color(card, COL_CARD, 0);
    lv_obj_set_style_radius(card, 18, 0);
    lv_obj_set_style_border_color(card, COL_BORDER, 0);  /* 1px 邊框分層,不加陰影 */
    lv_obj_set_style_border_width(card, 1, 0);

    lv_obj_t *lab = lv_label_create(card);
    lv_label_set_text(lab, c->label);
    lv_obj_align(lab, LV_ALIGN_TOP_LEFT, 0, 0);          /* 標籤左上;單位右上同理 */

    lv_obj_t *val = lv_label_create(card);
    lv_obj_set_style_text_font(val, &lv_font_montserrat_48, 0);  /* 大數字 */
    lv_obj_align(val, LV_ALIGN_TOP_LEFT, 0, c->value_y);
    m->value = val;

    /* 進度條:trough 和 indicator 兩部分分別設色,危險時把 indicator 改紅。*/
    lv_obj_t *bar = lv_bar_create(card);
    lv_obj_remove_style_all(bar);
    lv_bar_set_range(bar, c->min, c->max);
    lv_obj_set_size(bar, c->w - 2 * c->pad, c->big ? 14 : 10);
    lv_obj_align(bar, LV_ALIGN_BOTTOM_LEFT, 0, -24);
    lv_obj_set_style_bg_color(bar, COL_BAR_BG, 0);                /* trough */
    lv_obj_set_style_bg_color(bar, m->accent, LV_PART_INDICATOR); /* indicator */
    m->bar = bar;
}

6.2 想讓數字「活」起來:緩動逼近,不是勻速

最直覺的做法是「隨機給個新值,讓顯示勻速追過去」。但勻速追,到目標瞬間速度歸零,看著很機械。我用的是緩動逼近:每個資料記當前顯示值 current 和目標 target,每次刷新追近差距的 1/6(指數衰減,越靠近越慢)。每隔約 1.2 秒再從當前值附近隨機遊走出一個新目標,不是滿量程亂跳,這樣像真車資料:

/* 每 30 次(~1.2s)換一次目標:從當前值附近遊走,幅度 = 量程的 1/3。*/
if (tick % 30 == 0) {
    int span = (m->max - m->min) / 3;
    m->target = clampi(m->current + rnd_range(-span, span), m->min, m->max);
}
/* 緩動逼近:追近差距的 1/6;差太小就直接吸過去,免得永遠差一丟丟。*/
int diff = m->target - m->current;
if (diff > -6 && diff < 6) m->current = m->target;
else                       m->current += diff / 6;   /* ← 就是這句指數衰減 */

/* 進度條每 frame 都更新(它是「活的」視覺)。危險時 indicator 變紅。*/
bool danger = in_danger(m);   /* RPM≥6800 / 水溫≥105 / 電壓≤10.8 或 ≥14.6 */
lv_bar_set_value(m->bar, m->current, LV_ANIM_OFF);
lv_obj_set_style_bg_color(m->bar, danger ? COL_DANGER : m->accent, LV_PART_INDICATOR);

跟指標的 ease-in-out 一個道理——都是在轉折處減速。danger 判斷讓進度條在過載時變紅,就是面板上「過載變紅」那個效果的來歷。

6.3 順手的小優化:沒變就別重畫

每 40 毫秒刷新一次,但經常連續兩次算出來是同一個整數(尤其快到目標時基本停住)。每次調 lv_label_set_text 都要複製字串、標記重畫,全是白工。所以加一句:只有顯示的文字真的變了才更新:

/* 數字讀數:格式化出來的字串真變了,才 set_text。*/
char buf[12];
fmt_scaled(m->current, m->scale, buf, sizeof(buf));
if (strcmp(buf, m->last_text) != 0) {
    strcpy(m->last_text, buf);             /* 記下來,下次拿來比 */
    lv_label_set_text(m->value, buf);      /* strdup + 標記重畫,只在真變化時發生 */
}
lv_obj_set_style_text_color(m->value, danger ? COL_DANGER : COL_VALUE, 0);

6.4 嵌入式 UI 的一點取捨

固定解析度的小螢幕上,座標直接寫死比用 flex 自動排版更省心、更可預測;卡片不加陰影(LVGL 的陰影在 20Hz 更新下有點貴),靠邊框和純色就夠分層;電壓的一位小數用「存 142 代表 14.2」的整數縮放,省掉一堆浮點運算。整數縮放的做法是把每個指標的幾何/範圍/危險閾值/顏色/scale 全塞進一張配置表:

/* 配置表,每行一個指標。座標/範圍/危險閾值/顏色/scale 全在表裡,方便統一調。*/
static const metric_cfg_t CFG[] = {
    /* label      unit    x   y    w   h  pad v_y  min  max  dHi  dLo init accent   sc big */
    { "ENGINE",  "RPM",  24, 84, 478,242, 28, 78,    0,8000,6800,  0, 850,0xFF5A3C, 1, 1 },
    { "BATTERY", "V",   688,346, 312,230, 24, 64,  100, 150, 146,108, 124,0xB08CFF,10, 0 },
    /*                                                                  ↑ scale=10:124 代表 12.4V */
    /* ...其餘三行同理 */
};

/* 顯示時再除回去:124 → "12.4"。全程整數,沒有浮點運算。*/
static void fmt_scaled(int32_t v, int32_t scale, char *buf, size_t n) {
    if (scale == 10) lv_snprintf(buf, n, "%d.%d", (int)(v / 10), (int)(v % 10));
    else             lv_snprintf(buf, n, "%d", (int)v);
}

scale=10 的存 x10、scale=1 的存原值,緩動、危險判斷、進度條全跑在這套整數上,只有最後格式化成字串那一瞬間才「翻譯」回帶小數的樣子。


七、常見問題排查(別慌,問題就這幾類)

別慌,90% 的問題出在這幾個地方。遇到怪現象先看串口 log、先算物理參數,別急著改程式碼。

關於這塊螢幕

  • 官方例程/文件預設 800×480,直接套到 5B 會黑底 + 右邊白條。5B 是 1024×600、ST7262、純 RGB 直驅,不用 SPI 初始化。
  • 背光走 CH422G 的 EXIO2,不是普通 GPIO,也不是 PWM(只能開關,不能調亮度)。
  • 觸控晶片 GT911(I²C 地址 0x5D)和 RTC、CH422G 共用一條 I²C,注意地址規劃;本系列例子還沒接觸控,是後續待辦。

建構環境(Windows)

  • 別在 Git Bash 裡跑 idf.py,它偵測到 MSYSTEM 就罷工。用 PowerShell + EIM profile,呼叫前 unset MSYSTEM(或 $env:MSYSTEM=$null)。
  • 串口被佔用報 “port is busy”,多半是上次的 monitor 沒殺乾淨,確認無殘留再 flash。
  • 改了 sdkconfig.defaults 不生效?IDF 不會自動把 defaults 重新併進已存在的 sdkconfig,刪掉 sdkconfig 讓它從 defaults 重生。

點亮螢幕

  • PCLK 別抄板卡定義的 21MHz,用 PSRAM framebuffer 時從 16MHz 起步,還白就降到 12MHz 試。
  • PSRAM 別配錯:N16R8 是 octal(SPIRAM_MODE_OCT),不是 quad。
  • 建完面板別忘了補一行 esp_lcd_panel_init()。
  • 注意 GPIO0 是 strapping 腳(開機瞬間需為高),開機後當 RGB 資料腳用沒問題,但別在它上面接會拉低開機的電路。
  • 顏色偏色先分清兩種:白變青 = 腳位順序;白變粉 = RGB565 綠通道填值(綠是 6 位 0–63,純白要寫 31,63,31)。

跑 LVGL

  • 幾乎一定要開 LV_USE_CLIB_MALLOC + SPIRAM_USE_MALLOC,否則 LVGL 那個 64KB 內建記憶體池裝不下整屏繪圖,表現就是白屏 + 看門狗重開。
  • 元件版本要同代:esp_lvgl_port 2.8 配 LVGL ^9.3。
  • IDF 5.2 配新版元件,頂層 CMakeLists 補 SOC_LCDCAM_RGB_LCD_SUPPORTED=1。
  • LVGL / esp_lvgl_port 跨版本會改 API 名,別憑記憶寫,去讀抓下來的實際 header。

順滑與撕裂

  • 先算面板物理更新率(這塊約 20Hz),低於它的優化大多是動畫設計問題。
  • 不順首選 ease-in-out,別急著堆更新率。
  • 撕裂 = 單緩衝 + 無同步,解法是雙 framebuffer + avoid_tearing,且保留 bounce buffer。

八、FAQ

Q:Waveshare ESP32-S3-Touch-LCD-5B 解析度到底是多少?800×480 還是 1024×600? A:5B 是 1024×600。Waveshare 官方文件把整個 5 吋系列籠統標成「800×480 或 1024×600」,沒單獨標 5B。驗證方法:用 800×480 訊號燒進去,螢幕會黑底 + 右邊一條白邊,說明面板比訊號寬,就是 1024×600。別直接套官方例程的 800×480。

Q:螢幕一片全白是怎麼回事? A:先看串口 log 分兩種白屏。① 沒有 watchdog 報錯 → 多半是 RGB 訊號沒供上,PCLK 抄了 21MHz 太高,降到 16MHz。② 串口有 task_wdt: taskLVGL → 是 LVGL 記憶體池太小導致卡死,開 LV_USE_CLIB_MALLOC + SPIRAM_USE_MALLOC。

Q:背光能不能調亮度?為什麼找不到 PWM 腳位? A:不能。背光掛在 CH422G IO 擴展器的 EXIO2 上,只有開/關兩態,不是 PWM。想調亮度得硬體改板(加可調升降壓),軟體層面做不到。

Q:這塊螢幕更新率多少?為什麼指標動起來卡? A:約 20Hz(PCLK 16MHz ÷ 一 frame 總像素數)。這是物理天花板,軟體再快也突破不了。卡頓多半不是更新率問題,是動畫曲線太硬——把指標動畫從線性換成 ease-in-out,轉折處自然減速,立刻順滑。

Q:能在 Arduino IDE 裡點亮嗎?為什麼用 ESP-IDF? A:理論上能(Arduino-ESP32 底層也是 ESP-IDF),但 RGB 直驅 + PSRAM framebuffer + LVGL 這套組合,在 Arduino 裡調 sdkconfig 很彆扭,PCLK、PSRAM 模式、記憶體池這些開關 ESP-IDF 裡好控得多。本教學基於 ESP-IDF。

Q:LVGL 燒進去白屏 + 看門狗重開,怎麼辦? A:八成是 LVGL 內建的 64KB 記憶體池裝不下整屏繪圖。在 sdkconfig 裡開兩個:CONFIG_LV_USE_CLIB_MALLOC=y(LVGL 改用系統 malloc)和 CONFIG_SPIRAM_USE_MALLOC=y(讓 malloc 能去 PSRAM 拿大塊)。ESP32-S3 + PSRAM + 大螢幕幾乎必開。

Q:PSRAM 配 quad 還是 octal?配錯了會怎樣? A:N16R8 是 octal(SPIRAM_MODE_OCT)。配成 quad 會頻寬不夠,表現就是 PCLK 稍高就花屏/白屏,或執行不穩定。

Q:IDF 5.2.7 報 “This target does not support RGB” 怎麼辦? A:新版 esp_lvgl_port 檢查 SOC_LCDCAM_RGB_LCD_SUPPORTED 這個巨集,它 IDF 5.3 才改名,5.2.7 裡還是舊名。在頂層 CMakeLists 的 project() 之前補一行 add_compile_definitions(SOC_LCDCAM_RGB_LCD_SUPPORTED=1)。


九、延伸玩法

點亮只是起點,這塊板還能往下玩很多:

  • 接觸控:GT911 已經在 I²C 上(GPIO8/9),加個驅動就能做按鈕互動。
  • 從 SD 卡讀資源:板載 SD 卡槽(SPI),可以載入圖片、字型,告別把資源全塞進 Flash。
  • 接 CAN 匯流排:板載 TJA1051,配合 ESP-IDF 的 TWAI 驅動,做一個真正的 OBD 車況儀,儀表板的數就不再是模擬值了。
  • 上 RS485:SP3485 收發器接工業感測器/Modbus 設備。
  • 加 RTC 掉電走時:PCF85063 也在那條 I²C 上,做個帶真實時間戳的資料記錄器。

十、參考資料

官方資料手冊與產品頁

開源庫與框架

本專案程式碼


寫在最後

回頭看,整條路其實是三層:點亮螢幕 → 接上 LVGL → 做成介面。每一層都有它專屬的坑,但坑之間往往長得很像(兩種白屏、兩種偏色),最容易讓人白忙的就是認錯坑。

如果只讓我留一句話給後來人,大概是這句——我在這三個例子裡反覆栽跟頭後才真正學會的:

遇到怪現象先看串口 log、先算物理參數,別急著改程式碼。 官方例程的解析度坑、PCLK 的白屏、LVGL 記憶體的白屏,看起來都像「螢幕壞了」,但一個是文件不對、一個是硬體頻寬、一個是軟體卡死,方向反了就一通宵白熬。