在 ESP32-S3(如 xiaozhi-esp32 / ESP-IDF 工程)上接一块 SPI TFT(ST7735S / ST7789 / GC9A01 等),最常让人抓狂的现象是:背光亮着,但屏幕一片纯白,UI 怎么也出不来。很多人会反复去"换驱动、调 RGB 顺序、开关反色、查接线",却怎么都点不亮。
这套技能是一条经过实战检验的排查手册——它最关键的一条结论是:"纯白"恰恰是"SPI 通信成功"的证据,而不是失败。屏幕收到了数据,说明接线和通信基本没问题,问题出在"颜色/初始化参数错"。手册会教你怎么找到屏厂商官方的初始化序列文件、怎么用三个来源交叉验证 RGB 顺序/反色/MADCTL、以及怎么用 vendor_config 覆盖驱动的默认初始化序列——这往往是决定性的一步。
你可能会听到的"信号原话":
idf.py -p COMx monitor)。ST7735S_CTC180_INITIAL.txt 或例程的 Lcd_Driver.c)——这是点亮的"钥匙",第一步就该去找它。| 现象 | 含义 | 方向 |
|---|---|---|
| 纯白、均匀、有背光 | 屏收到数据,颜色/初始化参数错 | 查参数与初始化序列,别查接线 |
| 黑屏、无背光 | 背光/供电/复位问题 | 查 BL 脚、VCC、RST |
| 花屏、噪点、条纹 | 数据位错/时钟过快/接线错 | 查接线、降 SPI 时钟 |
| 有图像但偏移/翻转 | 参数微调 | 调 offset / mirror |
通用驱动点不亮的屏,第一步就该找厂商资料包里的 INIT 文件,而不是反复调驱动参数。它包含这块屏专用的电源控制 0xC0、帧率 0xB1/B2/B3、VCOM 0xC5、gamma 0xE0/0xE1,甚至独有的 0xF0/0xF6——通用驱动序列里往往没有。实录中,某 1.8" ST7735S 的 0xC0 电源控制,通用驱动是 0xA2,0x02,0x84,而厂商官方是 0x28,0x08,0x04,差异极大,直接决定能否出图。
同时找 3 处来源比对 RGB 顺序 / 反色 / MADCTL / offset:① 屏厂商资料包的 INIT 文件(最权威);② 你自己历史工程/例程里能点亮这块屏的配置(如 MicroPython 驱动、STM32 例程);③ 框架内的参考板(如 xiaozhi 的正点原子 ST7735 实现)。三源一致才动手。
组件(如 waveshare/esp_lcd_st7735)自带通用序列,用 vendor_config 把厂商序列喂给它:把厂商文件原样照抄成 static const st7735_lcd_init_cmd_t 数组,创建 panel 之前挂上 vendor_config(panel_config.vendor_config = &vc; 必须在 esp_lcd_new_panel_st7735 之前)。配套 config.h 设好 MADCTL(如 0xC0,RGB 顺序、不反色)。串口出现只有厂商序列才有的命令(如 cmd f0/cmd f6)即证明已生效。
你直接对 AI大模型或AI智能体 说:"我的 1.8 寸 ST7735S 在小智工程里背光亮但全白,调了 RGB 和反色都不行,怎么办?"
AI大模型或AI智能体 会:先告诉你"纯白 = 通信通,别查接线",然后让你去翻屏的厂商资料包找 INIT 文件(如 ST7735S_CTC180_INITIAL.txt),把里面 0xC0 电源、0xB1 帧率、0xF0/0xF6 等逐条照抄成 vendor_config 数组,挂到创建 panel 之前,并配套 config.h 把 MADCTL 设成 0xC0、不反色。多数情况这一步就能点亮。
你直接对 AI大模型或AI智能体 说:"我怕自己调错,你帮我确认这块屏的 RGB 顺序和要不要反色?"
AI大模型或AI智能体 会:按"三源交叉验证"帮你比对——厂商 INIT、你历史能点亮的工程配置、框架参考板,三源一致才定结论(实录里三源都指向 MADCTL=0xC0(RGB 顺序,MX|MY)、不反色发 0x20 INVOFF),并提醒你每次只改一层、靠串口日志打点确认。
进阶 / 可选——如果你工程里没有该屏的独立组件,用 ST7789 组件凑参数常点不亮,需要在 idf_component.yml 加上真正的 ST7735 组件:
(这只是"驱动选择"这一步;初始化序列与 config.h 的覆盖 AI大模型或AI智能体 会替你写。)
0xC0 电源控制常与该屏不符。waveshare/esp_lcd_st7735)。DISPLAY_OFFSET_X/Y 只作用于 LVGL 层,硬件偏移需 esp_lcd_panel_set_gap(panel,2,0)。每次只改一层,靠串口日志确认。