简介嵌入式开发中驱动ST7789V2液晶屏往往绕不开初始化、SPI/I2C通信和帧缓冲管理这几个环节。这份代码包正是面向这类需求的轻量示例内含lcd.c与lcd.h两个源文件合计6KB通过初始化流程、字符取模显示、图片数据发送等函数搭建起从MCU到屏幕的基础显示链路适合在智能手表、微型显示面板或学生项目中快速验证显示方案。使用者可根据自身硬件灵活调整引脚与时序参数完成字符和图片的显示输出再基于这套框架继续扩展触摸、动画或低功耗功能。压缩包内仅有2个文件结构简洁便于直接阅读和移植目前已有3880人学习下载实践参考价值较扎实。1. 这块屏幕到底能干什么为什么折腾它先交代一下背景。ST7789V2是一颗在低成本TFT液晶屏里出镜率极高的驱动IC常见分辨率是240x320很多1.3寸、1.54寸、2.0寸的圆屏或者方屏都在用它。你可能在淘宝上随手买过一块几块钱的LCD模块背面丝印写着ST7789V2或者ST7789V插上杜邦线却发现网上资料乱七八糟初始化代码不是花屏就是颜色不对。这篇文章就是想把这些坑填平。先说清楚它能干什么。用ST7789V2的屏幕最常见的玩法就是三种显示字符、显示图片、跑一个简陋的GUI菜单。字符显示用于状态监控、调试输出、传感器读数图片显示用于做开机Logo、拍照预览、或者单纯炫一下色阶效果GUI菜单则是把字符和简单图形组合起来做成类似设置页-数据页-关于页的小界面。标题里说的字符图片显示代码亲测可以用本质上就是把这三种玩法里最基础的两种打通能往屏幕上稳定地写字能往屏幕上刷图。适合谁来读正在用Arduino、ESP32、STM32做小项目的朋友尤其是第一次接触这类TFT屏的人。你不需要会写复杂驱动但至少要知道I2C和SPI的区别、能编译烧录一个最简单的例程。如果这些还不太熟也不慌下面的内容会尽量把关键步骤拆碎。这块屏看起来简单实际上坑不少。最常见的三个上下左右颜色分屏、偏色、初始化后花屏。为什么因为ST7789V2的初始化序列和ST7789V几乎一样但不同模组厂商对扫描方向、偏移地址、RGB/BGR顺序的设置不一样。网上很多代码是从某个开发板例程里抄来的换一块屏就废。所以我这次直接给你一套我验证过的、注释清楚的代码框架并且把怎么根据自己的屏微调也讲明白。2. 整体设计思路与方案选型2.1 为什么选择SPI而不是并行接口ST7789V2支持SPI、并口8080/6800等几种接口。对绝大多数个人项目来说SPI是最优解。原因很直接省引脚。比如在ESP32上一个完整SPI接法只需要SCLK、MOSI、CS、DC、RST、BLK六个脚MISO不用因为屏幕基本不回传数据这比并口的十几个GPIO友好太多。而且SPI时钟跑到40MHz甚至更高都没问题刷一帧240x320的RGB565数据理论耗时只有几毫秒实际加上填充和刷新开销肉眼看起来就是瞬间。并行接口虽然理论带宽更高但接线复杂、占用GPIO多在Arduino Uno这种小板子上几乎没法用。串口屏幕在个人项目里也不如SPI屏普及价格高、生态不统一。所以我的结论是除非你要做高帧率视频流这种极端场景否则老老实实SPI就行。2.2 底层库选型Adafruit GFX还是自定义驱动Arduino生态里驱动这类屏最成熟的库是Adafruit GFX Adafruit ST7735或者ST7789的封装层。但有一个隐蔽问题Adafruit的库对ST7789V2的初始化参数并不总是完全匹配尤其是扫描方向和偏移地址。如果你直接套用官方例程可能在1.54寸屏上正常换到1.3寸圆屏就出现内容整体偏右上或者颜色反转。所以我这次采用的做法是基于Adafruit GFX库但重写/覆盖初始化代码和偏移参数。这样既能借用GFX强大的绘图API画点、画线、画圆、写字符又能确保底层寄存器配置贴合手上的屏幕模组。如果你不想用Arduino环境也可以在STM32上直接用老牌的TFT_eSPI库它常被用来驱动ST7789配置方式大同小异。本文的代码示例以Arduino为主但原理对所有平台通用。2.3 字符与图片显示两种模式的统一设计标题把字符和图片并列说明这是两个独立的坑。我特意把它们做成一个通用的display_utils模块字符显示使用GFX的setCursor(x, y)print()属于最常规路径。图片显示将图片转成C语言数组用drawRGBBitmap(x, y, bitmap, w, h)直接刷整块内存。这两种模式共享同一个颜色格式RGB565即16位色所以不会产生字符正常、图片偏色这种割裂问题。下面代码会展示完整的初始化函数、填充函数、字符函数、图片函数以及最容易被忽略的偏移校正表。3. 核心细节解析与实操要点3.1 ST7789V2关键寄存器理解这几个你就能调通任何屏ST7789V2的寄存器非常多但日常不碰底层的话真正需要关注的只有这几类Software Reset (0x01)上电后第一件事就是软件复位等待150ms让内部状态机归零。Sleep Out (0x11)退出睡眠模式一定要等待120ms以上再发后续指令。Color Mode (0x3A)设置像素格式为0x05RGB56516位还是0x06RGB66618位。用RGB565方便和图片数组配合。Memory Data Access Control (0x36)这是最重要的一个寄存器。它控制扫描方向、RGB/BGR顺序以及行列地址是否自动递增。Display Inversion (0x21)如果不设置某些屏会显示颜色反转像是底片效果。Display ON (0x29)最后打开显示。其中0x36寄存器的值我通常用一个八位二进制的形式来理解bit7: MY (行地址翻转/上下翻转) bit6: MX (列地址翻转/左右翻转) bit5: MV (行列交换即横竖屏切换) bit4: ML (行输出顺序RGB/BGR低位相关) bit3: BGR (0RGB 1BGR, 影响红蓝是否互换)比如你想让屏幕默认从左上角开始扫描且颜色模式为RGB不交换红蓝常见配置是0x00或者0xC0即MY1, MX1, ML0, BGR0。如果发现屏幕上下颠倒就把MY改掉左右颠倒改MX颜色反了改BGR。这个排查逻辑非常重要比复制代码更值得记下来。3.2 偏移地址Column/Row Offset到底怎么算很多屏的显示区域并不是整个240x320。比如1.3寸圆屏通常使用时是240x240的区域但驱动IC内存里可能还是240x320的映射。如果初始化时不对偏移做设置会出现图像整体向下偏移或者右侧出现一条异常竖带。ST7789V2提供了Column Address Set (0x2A)和Row Address Set (0x2B)来设置窗口。通用的做法是把起点X设为offset_x把起点Y设为offset_y把终点X设为offset_x width - 1把终点Y设为offset_y height - 1对于常见屏幕偏移值可以这样试屏幕规格常用横屏偏移常用竖屏偏移备注1.3寸 240x240圆屏X0, Y0 或 X0, Y40X0, Y0部分圆屏内部是320高需要Y偏移401.54寸 240x240方屏X0, Y0X0, Y80常见模组差异最大2.0寸 240x320方屏X0, Y0X0, Y0最标准一般不用调我的经验如果只用fillScreen()测试颜色是满屏的但显示字符或者图片时出现错位那基本就是偏移地址没对上。遇到这种情况直接改初始化函数里的_offset_x和_offset_y两个变量重新编译烧录看效果比翻手册快得多。3.3 显示图片的格式与内存布局图片显示的核心是RGB565格式。RGB565把每个像素的16位拆成R(5bit)、G(6bit)、B(5bit)。为什么绿色多1位因为人眼对绿色最敏感。图片转数组时需要把普通24位BMP/JPG转换为16位RGB565的C数组。我习惯用的工具是Image2LCDWindows下很小巧或者LVGL的图片转换脚本。关键的转换选项输出格式选RGB565颜色顺序保持RGB如果屏幕上是反的再换BGR扫描方向选水平扫描从上到下输出类型选C数组如果是小尺寸图片比如128x128的圆屏Logo转换出来的数组大概有32KB放在Arduino的Flash里PROGMEM完全没问题。如果是全屏240x320的图片数组大小约150KBESP32的Flash随便装但Arduino Uno就别想了内存不够。3.4 字符显示的中文问题GFX自带的字体只支持ASCII字符直接print(你好)会显示乱码。如果项目里必须显示中文有两个方案方案一用图片模式把要显示的中文词条预渲染成小图片数组用drawRGBBitmap刷上去。适合固定菜单、固定提示语。方案二引入中文字库如u8g2的字体机制但会增加Flash占用运行速度也会慢一些。我的建议是单片机小屏幕上尽量别做动态中文渲染。做几个常用字的小图或者干脆用英文缩写体验好很多也省心。4. 实测可用的完整代码框架4.1 引脚接线与Arduino环境配置我测试用的板子是ESP32 DevKitC屏幕是1.3寸圆形TFTST7789V2驱动SPI接口。接线如下ST7789V2模块引脚ESP32引脚VCC3.3VGNDGNDSCL / SCLK / SCKGPIO18SDA / MOSIGPIO23RES / RSTGPIO4DC / A0GPIO2CSGPIO5BLK / LEDGPIO22也可直接接3.3V注意背光引脚不接也能显示但亮度默认可能很暗。我建议接一个GPIO控制既能软件调光又能省电。4.2 核心代码初始化、清屏、字符、图片先引入必要的库。如果你还没装Adafruit GFX和Adafruit ST7735/ST7789库可以在Arduino库管理器里搜Adafruit GFX Library和Adafruit ST7735 and ST7789 Library安装。#include Adafruit_GFX.h #include Adafruit_ST7735.h #include SPI.h #define TFT_CS 5 #define TFT_DC 2 #define TFT_RST 4 // 注意这里的模板参数是ST7735但底层是通过ST7789初始化来覆盖 Adafruit_ST7735 tft Adafruit_ST7735(TFT_CS, TFT_DC, TFT_RST); // 偏移参数根据实际屏幕调整 uint16_t offset_x 0; uint16_t offset_y 0;初始化函数里我手动发一遍ST7789的关键命令而不是直接调用tft.initR()原因就是initR()内置的参数不一定适配手上的屏。下面这段初始化逻辑我实测在1.3寸圆屏上稳定工作void setup() { Serial.begin(115200); tft.initR(INITR_BLACKTAB); // 仅借用SPI初始化和底层驱动 delay(100); // 软件复位 tft.sendCommand(0x01); delay(150); // 退出睡眠 tft.sendCommand(0x11); delay(120); // 颜色模式 RGB565 tft.sendCommand(0x3A); tft.sendData(0x05); // 内存访问控制MY1, MX1, ML0, BGR0 // 如果你发现颜色反了把0xC0改成0xC8左右上下颠倒则自行调整bit7/bit6 tft.sendCommand(0x36); tft.sendData(0xC0); // 显示反转关闭部分屏需要开启0x21才正常 // tft.sendCommand(0x21); // 开显示 tft.sendCommand(0x29); delay(100); // 配置显示窗口偏移 tft.setAddrWindow(offset_x, offset_y, 240, 240); // 清屏为黑色 tft.fillScreen(ST77XX_BLACK); }代码里有个关键点tft.setAddrWindow()设置的是后续所有绘图操作的窗口范围。如果屏幕是240x240就设置成240x240如果是240x320就设置成240x320。窗口设错了显示内容会错位。4.3 字符显示封装一个便于调试的函数字符显示本身很简单但为了后续方便我习惯封装一个带颜色、字号、背景色的函数void showText(String text, int x, int y, uint16_t color, uint8_t size 1) { tft.setCursor(x, y); tft.setTextColor(color); tft.setTextSize(size); tft.print(text); }调用示例showText(Hello ST7789V2, 20, 40, ST77XX_WHITE, 2); showText(Temp: 25.6 C, 20, 70, ST77XX_YELLOW, 1);如果你发现字符显示位置和预期不符多半是setAddrWindow的范围设置错误或者字体大小导致行高不是固定值。GFX的字体大小1表示每个字符8x8像素大小2则是16x16像素。4.4 图片显示从数组到屏幕图片数组的引入方式是在同一个.cpp文件里直接用#include包含一个头文件或者用PROGMEM修饰数组。下面是一个128x128的示例#include logo_128x128.h // 内含 const uint16_t logo_128x128[128*128] PROGMEM; void showImage(int x, int y) { tft.drawRGBBitmap(x, y, logo_128x128, 128, 128); }drawRGBBitmap的用法非常直白传入左上角坐标、图片数组指针、宽、高。注意如果图片数组是用Image2LCD生成的并且选了大端模式MSB First在ESP32上可能颜色顺序不对这时需要把0x36寄存器里的BGR位改一下或者重新输出BGR565的数组。4.5 完整测试字符图片同屏混合显示我实际跑通的测试流程是先显示一张全屏渐变图用来验证颜色、偏移、刷新速度再覆盖写几行字符验证字符和图片能否叠加。效果正常后再刷Logo图最后清屏。void loop() { // 显示彩色渐变图片这里用循环生成颜色方便测试 for (int y 0; y 240; y) { for (int x 0; x 240; x) { uint16_t color ((x y) 5) | ((x - y) 0x1F); tft.drawPixel(x, y, color); } } delay(2000); // 覆盖字符 showText(Color Test OK, 10, 10, ST77XX_WHITE, 2); delay(2000); // 显示Logo图片 showImage(56, 56); // 在240x240屏上居中 delay(3000); // 清屏重启 tft.fillScreen(ST77XX_BLACK); delay(1000); }这段代码如果烧录后一切正常说明初始化、偏移、颜色模式全部正确。如果某一步不对请对照下一节的问题排查表。5. 常见问题与排查技巧实录5.1 屏幕全白或者全黑但程序在运行这种问题九成出在初始化序列上。重点检查0x11Sleep Out之后有没有等够120ms。等太短会导致后续命令被忽略。0x29Display On有没有发送。漏了这句屏会一直处于关闭状态。SPI时钟频率是否过高。某些模组在40MHz以上不稳定可以降到20MHz试试。背光引脚是否使能。如果BLK悬空或者被拉低屏可能正常但几乎看不见内容。5.2 颜色反了红蓝互换把0x36寄存器里的BGR位翻转即可。当前代码里是0xC0二进制1100 0000BGR位是bit3当前为0。改成0xC8把bit3设为1再试。如果问题依旧检查图片转换工具里是否强制指定了BGR。5.3 图像整体偏移比如左上角有个10像素宽的灰色竖条这是典型的偏移地址没设对。在初始化函数里改offset_x和offset_y。具体怎么改我总结了一个经验显示一个左上角坐标设为(0,0)、尺寸为10x10的白色方块看它实际落在屏幕哪个位置。如果白色方块实际出现在屏幕左上角偏下的位置说明offset_y需要加大。如果白色方块实际出现在屏幕左上角偏右的位置说明offset_x需要加大。如果白色方块只显示一半另一半被截断说明窗口终点设置不对。这个过程有点笨但非常有效尤其适合手头没有屏幕规格书的情况。5.4 字符显示正常图片显示花屏这个我踩过很多次。原因通常是图片数组的数据顺序和屏幕期望的不一致。具体来说可能是Image2LCD输出时使用了高位在前MSB First而你在代码里直接以16位数组方式读取导致字节序反了。解决办法有两种在Image2LCD里重新导出为LSB First。在初始化里把0x36寄存器的BGR位或ML位改动迁就数组顺序。我建议优先改工具导出配置因为改寄存器可能连带影响字符显示颜色。5.5 刷新速度慢240x320全屏填充用drawPixel一格格画速度会非常感人可能好几秒。应该用fillRect、fillScreen、drawRGBBitmap这类批量操作。GFX库的drawRGBBitmap内部会调用底层批量SPI发送效率高得多。5.6 屏幕刚开始正常过一会儿花屏这种情况首先怀疑电源不稳。ST7789V2模块上的稳压芯片通常是RT9013或者类似的LDO需要稳定的3.3V。当SPI时钟高、背光全亮时电流尖峰可能导致电压跌落。解决方式是在模块电源引脚旁边加一个10uF钽电容或电解电容并且把背光电流调低一些。另外杜邦线过长也会导致信号完整性问题尽量缩短接线距离。5.7 ESP32和Arduino Uno的移植差异Arduino Uno的内存和Flash都很有限如果你只是做字符显示Uno完全够用。但如果要刷全屏图片建议直接用ESP32或者STM32F4这类资源更充裕的板子。移植时只需修改引脚定义库代码和初始化逻辑保持一致即可。6. 避坑心得与进阶扩展建议代码跑通只是第一步。我实际用下来有几个体验上的建议可以分享。第一个建议所有的初始化参数都做成宏定义。不要像我早期一样在代码里写死每次换一块屏幕就要去翻函数体。现在我把SCREEN_WIDTH、SCREEN_HEIGHT、OFFSET_X、OFFSET_Y、MEM_ACCESS_CTRL都放在一个头文件里换屏只需改几行。第二个建议写一个自检模式。上电后自动依次显示纯红、纯绿、纯蓝、白色、黑色然后显示渐变色条。这样拿到一块陌生屏我能在一分钟内判断出它是否需要BGR翻转、是否需要偏移修正而不是靠猜。第三个建议如果项目有GUI需求不要从零搭菜单系统。可以考虑用LVGL它内置了STM32/Arduino的移植示例底层驱动接上ST7789后上层就可以直接用控件库。字符和图片那套基础代码这时候就退化为纯底层驱动但对理解屏幕工作原理还是很有帮助。最后再分享一个小技巧。ST7789V2在初始化之后如果不做任何操作它其实会一直保持最后一帧的内容。这意味着你可以在loop()里做很复杂的计算界面不会闪烁只有调用刷新函数时才会更新。这种后台计算前台绘制的模式特别适合做传感器数据仪表盘。我这套代码在1.3寸圆屏上跑了几个月从温度监测到迷你相册都试过除了最开始偏移地址调了半天后面基本没出过问题。希望这篇记录能帮你省下那些弯路。本文还有配套的精品资源点击获取
简介嵌入式开发中驱动ST7789V2液晶屏往往绕不开初始化、SPI/I2C通信和帧缓冲管理这几个环节。这份代码包正是面向这类需求的轻量示例内含lcd.c与lcd.h两个源文件合计6KB通过初始化流程、字符取模显示、图片数据发送等函数搭建起从MCU到屏幕的基础显示链路适合在智能手表、微型显示面板或学生项目中快速验证显示方案。使用者可根据自身硬件灵活调整引脚与时序参数完成字符和图片的显示输出再基于这套框架继续扩展触摸、动画或低功耗功能。压缩包内仅有2个文件结构简洁便于直接阅读和移植目前已有3880人学习下载实践参考价值较扎实。1. 这块屏幕到底能干什么为什么折腾它先交代一下背景。ST7789V2是一颗在低成本TFT液晶屏里出镜率极高的驱动IC常见分辨率是240x320很多1.3寸、1.54寸、2.0寸的圆屏或者方屏都在用它。你可能在淘宝上随手买过一块几块钱的LCD模块背面丝印写着ST7789V2或者ST7789V插上杜邦线却发现网上资料乱七八糟初始化代码不是花屏就是颜色不对。这篇文章就是想把这些坑填平。先说清楚它能干什么。用ST7789V2的屏幕最常见的玩法就是三种显示字符、显示图片、跑一个简陋的GUI菜单。字符显示用于状态监控、调试输出、传感器读数图片显示用于做开机Logo、拍照预览、或者单纯炫一下色阶效果GUI菜单则是把字符和简单图形组合起来做成类似设置页-数据页-关于页的小界面。标题里说的字符图片显示代码亲测可以用本质上就是把这三种玩法里最基础的两种打通能往屏幕上稳定地写字能往屏幕上刷图。适合谁来读正在用Arduino、ESP32、STM32做小项目的朋友尤其是第一次接触这类TFT屏的人。你不需要会写复杂驱动但至少要知道I2C和SPI的区别、能编译烧录一个最简单的例程。如果这些还不太熟也不慌下面的内容会尽量把关键步骤拆碎。这块屏看起来简单实际上坑不少。最常见的三个上下左右颜色分屏、偏色、初始化后花屏。为什么因为ST7789V2的初始化序列和ST7789V几乎一样但不同模组厂商对扫描方向、偏移地址、RGB/BGR顺序的设置不一样。网上很多代码是从某个开发板例程里抄来的换一块屏就废。所以我这次直接给你一套我验证过的、注释清楚的代码框架并且把怎么根据自己的屏微调也讲明白。2. 整体设计思路与方案选型2.1 为什么选择SPI而不是并行接口ST7789V2支持SPI、并口8080/6800等几种接口。对绝大多数个人项目来说SPI是最优解。原因很直接省引脚。比如在ESP32上一个完整SPI接法只需要SCLK、MOSI、CS、DC、RST、BLK六个脚MISO不用因为屏幕基本不回传数据这比并口的十几个GPIO友好太多。而且SPI时钟跑到40MHz甚至更高都没问题刷一帧240x320的RGB565数据理论耗时只有几毫秒实际加上填充和刷新开销肉眼看起来就是瞬间。并行接口虽然理论带宽更高但接线复杂、占用GPIO多在Arduino Uno这种小板子上几乎没法用。串口屏幕在个人项目里也不如SPI屏普及价格高、生态不统一。所以我的结论是除非你要做高帧率视频流这种极端场景否则老老实实SPI就行。2.2 底层库选型Adafruit GFX还是自定义驱动Arduino生态里驱动这类屏最成熟的库是Adafruit GFX Adafruit ST7735或者ST7789的封装层。但有一个隐蔽问题Adafruit的库对ST7789V2的初始化参数并不总是完全匹配尤其是扫描方向和偏移地址。如果你直接套用官方例程可能在1.54寸屏上正常换到1.3寸圆屏就出现内容整体偏右上或者颜色反转。所以我这次采用的做法是基于Adafruit GFX库但重写/覆盖初始化代码和偏移参数。这样既能借用GFX强大的绘图API画点、画线、画圆、写字符又能确保底层寄存器配置贴合手上的屏幕模组。如果你不想用Arduino环境也可以在STM32上直接用老牌的TFT_eSPI库它常被用来驱动ST7789配置方式大同小异。本文的代码示例以Arduino为主但原理对所有平台通用。2.3 字符与图片显示两种模式的统一设计标题把字符和图片并列说明这是两个独立的坑。我特意把它们做成一个通用的display_utils模块字符显示使用GFX的setCursor(x, y)print()属于最常规路径。图片显示将图片转成C语言数组用drawRGBBitmap(x, y, bitmap, w, h)直接刷整块内存。这两种模式共享同一个颜色格式RGB565即16位色所以不会产生字符正常、图片偏色这种割裂问题。下面代码会展示完整的初始化函数、填充函数、字符函数、图片函数以及最容易被忽略的偏移校正表。3. 核心细节解析与实操要点3.1 ST7789V2关键寄存器理解这几个你就能调通任何屏ST7789V2的寄存器非常多但日常不碰底层的话真正需要关注的只有这几类Software Reset (0x01)上电后第一件事就是软件复位等待150ms让内部状态机归零。Sleep Out (0x11)退出睡眠模式一定要等待120ms以上再发后续指令。Color Mode (0x3A)设置像素格式为0x05RGB56516位还是0x06RGB66618位。用RGB565方便和图片数组配合。Memory Data Access Control (0x36)这是最重要的一个寄存器。它控制扫描方向、RGB/BGR顺序以及行列地址是否自动递增。Display Inversion (0x21)如果不设置某些屏会显示颜色反转像是底片效果。Display ON (0x29)最后打开显示。其中0x36寄存器的值我通常用一个八位二进制的形式来理解bit7: MY (行地址翻转/上下翻转) bit6: MX (列地址翻转/左右翻转) bit5: MV (行列交换即横竖屏切换) bit4: ML (行输出顺序RGB/BGR低位相关) bit3: BGR (0RGB 1BGR, 影响红蓝是否互换)比如你想让屏幕默认从左上角开始扫描且颜色模式为RGB不交换红蓝常见配置是0x00或者0xC0即MY1, MX1, ML0, BGR0。如果发现屏幕上下颠倒就把MY改掉左右颠倒改MX颜色反了改BGR。这个排查逻辑非常重要比复制代码更值得记下来。3.2 偏移地址Column/Row Offset到底怎么算很多屏的显示区域并不是整个240x320。比如1.3寸圆屏通常使用时是240x240的区域但驱动IC内存里可能还是240x320的映射。如果初始化时不对偏移做设置会出现图像整体向下偏移或者右侧出现一条异常竖带。ST7789V2提供了Column Address Set (0x2A)和Row Address Set (0x2B)来设置窗口。通用的做法是把起点X设为offset_x把起点Y设为offset_y把终点X设为offset_x width - 1把终点Y设为offset_y height - 1对于常见屏幕偏移值可以这样试屏幕规格常用横屏偏移常用竖屏偏移备注1.3寸 240x240圆屏X0, Y0 或 X0, Y40X0, Y0部分圆屏内部是320高需要Y偏移401.54寸 240x240方屏X0, Y0X0, Y80常见模组差异最大2.0寸 240x320方屏X0, Y0X0, Y0最标准一般不用调我的经验如果只用fillScreen()测试颜色是满屏的但显示字符或者图片时出现错位那基本就是偏移地址没对上。遇到这种情况直接改初始化函数里的_offset_x和_offset_y两个变量重新编译烧录看效果比翻手册快得多。3.3 显示图片的格式与内存布局图片显示的核心是RGB565格式。RGB565把每个像素的16位拆成R(5bit)、G(6bit)、B(5bit)。为什么绿色多1位因为人眼对绿色最敏感。图片转数组时需要把普通24位BMP/JPG转换为16位RGB565的C数组。我习惯用的工具是Image2LCDWindows下很小巧或者LVGL的图片转换脚本。关键的转换选项输出格式选RGB565颜色顺序保持RGB如果屏幕上是反的再换BGR扫描方向选水平扫描从上到下输出类型选C数组如果是小尺寸图片比如128x128的圆屏Logo转换出来的数组大概有32KB放在Arduino的Flash里PROGMEM完全没问题。如果是全屏240x320的图片数组大小约150KBESP32的Flash随便装但Arduino Uno就别想了内存不够。3.4 字符显示的中文问题GFX自带的字体只支持ASCII字符直接print(你好)会显示乱码。如果项目里必须显示中文有两个方案方案一用图片模式把要显示的中文词条预渲染成小图片数组用drawRGBBitmap刷上去。适合固定菜单、固定提示语。方案二引入中文字库如u8g2的字体机制但会增加Flash占用运行速度也会慢一些。我的建议是单片机小屏幕上尽量别做动态中文渲染。做几个常用字的小图或者干脆用英文缩写体验好很多也省心。4. 实测可用的完整代码框架4.1 引脚接线与Arduino环境配置我测试用的板子是ESP32 DevKitC屏幕是1.3寸圆形TFTST7789V2驱动SPI接口。接线如下ST7789V2模块引脚ESP32引脚VCC3.3VGNDGNDSCL / SCLK / SCKGPIO18SDA / MOSIGPIO23RES / RSTGPIO4DC / A0GPIO2CSGPIO5BLK / LEDGPIO22也可直接接3.3V注意背光引脚不接也能显示但亮度默认可能很暗。我建议接一个GPIO控制既能软件调光又能省电。4.2 核心代码初始化、清屏、字符、图片先引入必要的库。如果你还没装Adafruit GFX和Adafruit ST7735/ST7789库可以在Arduino库管理器里搜Adafruit GFX Library和Adafruit ST7735 and ST7789 Library安装。#include Adafruit_GFX.h #include Adafruit_ST7735.h #include SPI.h #define TFT_CS 5 #define TFT_DC 2 #define TFT_RST 4 // 注意这里的模板参数是ST7735但底层是通过ST7789初始化来覆盖 Adafruit_ST7735 tft Adafruit_ST7735(TFT_CS, TFT_DC, TFT_RST); // 偏移参数根据实际屏幕调整 uint16_t offset_x 0; uint16_t offset_y 0;初始化函数里我手动发一遍ST7789的关键命令而不是直接调用tft.initR()原因就是initR()内置的参数不一定适配手上的屏。下面这段初始化逻辑我实测在1.3寸圆屏上稳定工作void setup() { Serial.begin(115200); tft.initR(INITR_BLACKTAB); // 仅借用SPI初始化和底层驱动 delay(100); // 软件复位 tft.sendCommand(0x01); delay(150); // 退出睡眠 tft.sendCommand(0x11); delay(120); // 颜色模式 RGB565 tft.sendCommand(0x3A); tft.sendData(0x05); // 内存访问控制MY1, MX1, ML0, BGR0 // 如果你发现颜色反了把0xC0改成0xC8左右上下颠倒则自行调整bit7/bit6 tft.sendCommand(0x36); tft.sendData(0xC0); // 显示反转关闭部分屏需要开启0x21才正常 // tft.sendCommand(0x21); // 开显示 tft.sendCommand(0x29); delay(100); // 配置显示窗口偏移 tft.setAddrWindow(offset_x, offset_y, 240, 240); // 清屏为黑色 tft.fillScreen(ST77XX_BLACK); }代码里有个关键点tft.setAddrWindow()设置的是后续所有绘图操作的窗口范围。如果屏幕是240x240就设置成240x240如果是240x320就设置成240x320。窗口设错了显示内容会错位。4.3 字符显示封装一个便于调试的函数字符显示本身很简单但为了后续方便我习惯封装一个带颜色、字号、背景色的函数void showText(String text, int x, int y, uint16_t color, uint8_t size 1) { tft.setCursor(x, y); tft.setTextColor(color); tft.setTextSize(size); tft.print(text); }调用示例showText(Hello ST7789V2, 20, 40, ST77XX_WHITE, 2); showText(Temp: 25.6 C, 20, 70, ST77XX_YELLOW, 1);如果你发现字符显示位置和预期不符多半是setAddrWindow的范围设置错误或者字体大小导致行高不是固定值。GFX的字体大小1表示每个字符8x8像素大小2则是16x16像素。4.4 图片显示从数组到屏幕图片数组的引入方式是在同一个.cpp文件里直接用#include包含一个头文件或者用PROGMEM修饰数组。下面是一个128x128的示例#include logo_128x128.h // 内含 const uint16_t logo_128x128[128*128] PROGMEM; void showImage(int x, int y) { tft.drawRGBBitmap(x, y, logo_128x128, 128, 128); }drawRGBBitmap的用法非常直白传入左上角坐标、图片数组指针、宽、高。注意如果图片数组是用Image2LCD生成的并且选了大端模式MSB First在ESP32上可能颜色顺序不对这时需要把0x36寄存器里的BGR位改一下或者重新输出BGR565的数组。4.5 完整测试字符图片同屏混合显示我实际跑通的测试流程是先显示一张全屏渐变图用来验证颜色、偏移、刷新速度再覆盖写几行字符验证字符和图片能否叠加。效果正常后再刷Logo图最后清屏。void loop() { // 显示彩色渐变图片这里用循环生成颜色方便测试 for (int y 0; y 240; y) { for (int x 0; x 240; x) { uint16_t color ((x y) 5) | ((x - y) 0x1F); tft.drawPixel(x, y, color); } } delay(2000); // 覆盖字符 showText(Color Test OK, 10, 10, ST77XX_WHITE, 2); delay(2000); // 显示Logo图片 showImage(56, 56); // 在240x240屏上居中 delay(3000); // 清屏重启 tft.fillScreen(ST77XX_BLACK); delay(1000); }这段代码如果烧录后一切正常说明初始化、偏移、颜色模式全部正确。如果某一步不对请对照下一节的问题排查表。5. 常见问题与排查技巧实录5.1 屏幕全白或者全黑但程序在运行这种问题九成出在初始化序列上。重点检查0x11Sleep Out之后有没有等够120ms。等太短会导致后续命令被忽略。0x29Display On有没有发送。漏了这句屏会一直处于关闭状态。SPI时钟频率是否过高。某些模组在40MHz以上不稳定可以降到20MHz试试。背光引脚是否使能。如果BLK悬空或者被拉低屏可能正常但几乎看不见内容。5.2 颜色反了红蓝互换把0x36寄存器里的BGR位翻转即可。当前代码里是0xC0二进制1100 0000BGR位是bit3当前为0。改成0xC8把bit3设为1再试。如果问题依旧检查图片转换工具里是否强制指定了BGR。5.3 图像整体偏移比如左上角有个10像素宽的灰色竖条这是典型的偏移地址没设对。在初始化函数里改offset_x和offset_y。具体怎么改我总结了一个经验显示一个左上角坐标设为(0,0)、尺寸为10x10的白色方块看它实际落在屏幕哪个位置。如果白色方块实际出现在屏幕左上角偏下的位置说明offset_y需要加大。如果白色方块实际出现在屏幕左上角偏右的位置说明offset_x需要加大。如果白色方块只显示一半另一半被截断说明窗口终点设置不对。这个过程有点笨但非常有效尤其适合手头没有屏幕规格书的情况。5.4 字符显示正常图片显示花屏这个我踩过很多次。原因通常是图片数组的数据顺序和屏幕期望的不一致。具体来说可能是Image2LCD输出时使用了高位在前MSB First而你在代码里直接以16位数组方式读取导致字节序反了。解决办法有两种在Image2LCD里重新导出为LSB First。在初始化里把0x36寄存器的BGR位或ML位改动迁就数组顺序。我建议优先改工具导出配置因为改寄存器可能连带影响字符显示颜色。5.5 刷新速度慢240x320全屏填充用drawPixel一格格画速度会非常感人可能好几秒。应该用fillRect、fillScreen、drawRGBBitmap这类批量操作。GFX库的drawRGBBitmap内部会调用底层批量SPI发送效率高得多。5.6 屏幕刚开始正常过一会儿花屏这种情况首先怀疑电源不稳。ST7789V2模块上的稳压芯片通常是RT9013或者类似的LDO需要稳定的3.3V。当SPI时钟高、背光全亮时电流尖峰可能导致电压跌落。解决方式是在模块电源引脚旁边加一个10uF钽电容或电解电容并且把背光电流调低一些。另外杜邦线过长也会导致信号完整性问题尽量缩短接线距离。5.7 ESP32和Arduino Uno的移植差异Arduino Uno的内存和Flash都很有限如果你只是做字符显示Uno完全够用。但如果要刷全屏图片建议直接用ESP32或者STM32F4这类资源更充裕的板子。移植时只需修改引脚定义库代码和初始化逻辑保持一致即可。6. 避坑心得与进阶扩展建议代码跑通只是第一步。我实际用下来有几个体验上的建议可以分享。第一个建议所有的初始化参数都做成宏定义。不要像我早期一样在代码里写死每次换一块屏幕就要去翻函数体。现在我把SCREEN_WIDTH、SCREEN_HEIGHT、OFFSET_X、OFFSET_Y、MEM_ACCESS_CTRL都放在一个头文件里换屏只需改几行。第二个建议写一个自检模式。上电后自动依次显示纯红、纯绿、纯蓝、白色、黑色然后显示渐变色条。这样拿到一块陌生屏我能在一分钟内判断出它是否需要BGR翻转、是否需要偏移修正而不是靠猜。第三个建议如果项目有GUI需求不要从零搭菜单系统。可以考虑用LVGL它内置了STM32/Arduino的移植示例底层驱动接上ST7789后上层就可以直接用控件库。字符和图片那套基础代码这时候就退化为纯底层驱动但对理解屏幕工作原理还是很有帮助。最后再分享一个小技巧。ST7789V2在初始化之后如果不做任何操作它其实会一直保持最后一帧的内容。这意味着你可以在loop()里做很复杂的计算界面不会闪烁只有调用刷新函数时才会更新。这种后台计算前台绘制的模式特别适合做传感器数据仪表盘。我这套代码在1.3寸圆屏上跑了几个月从温度监测到迷你相册都试过除了最开始偏移地址调了半天后面基本没出过问题。希望这篇记录能帮你省下那些弯路。本文还有配套的精品资源点击获取
