简介面向STM32嵌入式开发者的UCGUI图形界面库KEIL工程包适合需要在LCD屏上实现人机交互界面的项目快速起步。工程已提前完成UCGUI内核在STM32上的移植使用者只需根据屏幕参数替换LCD驱动中的画点函数即可正常显示无需从头配置底层环境大幅降低GUI开发门槛。压缩包共851个文件主体为736个C语言源文件与97个头文件覆盖UCGUI库函数、示例代码和LCD驱动框架同时附带KEIL工程配置、批处理编译脚本、Hex烧录文件等整体仅1.58MB结构清晰、便于裁剪。库内按功能拆分字体、窗口、控件、内存设备等模块脚本可辅助批量编译与清理有助于理解嵌入式GUI的分层设计。已有1010人学习下载既适合嵌入式GUI入门者学习移植思路也可作为STM32产品界面开发的工程底座。 上个月我帮朋友调一块2.4寸的GC9307屏他手里正好有一份STM32的UCGUI例程对方给的说明很豪爽“这是KEIL工程已经移植好了你改一下LCD驱动就能用。”结果我打开工程光找“LCD驱动”在哪就花了大半天。所谓“改一下驱动就行”前提是你得先搞清楚这个工程帮你封装了什么、留了什么接口。这篇东西我就以一份典型的UCGUISTM32 KEIL工程为蓝本把“修改LCD驱动”这件事完整拆开讲一遍哪些文件是给你改的哪些是库内部的东西碰不得以及当你把GC9307这种屏换成一个完全没接触过的屏时应该按什么顺序改。适合刚接触UCGUI移植、或者手里有一份现成例程但不知道怎么下手的读者。1. 为什么“改个LCD驱动就能用”这种话能成立1.1 UCGUI移植的“三座大山”这个工程替你拆了一半UCGUI要在STM32上跑起来通常有三件事绕不开。第一核心库本身的编译选项要对。UCGUI是一套图形库源码它针不针对你手里的芯片、编译器生成的是thumb指令还是ARM指令以及用没用操作系统都决定了一开始能不能编译过。这一块如果让你从头搭光是找对齐型号的库版本、匹配MDK的ARMCC版本就能耗掉半天。第二GUI_X层要适配。它是UCGUI和底层硬件/OS之间的适配层负责提供时间基准、临界区保护、内存申请释放这些能力。裸机环境和RTOS环境的写法不一样如果工程是裸机你确实只需要提供一个基准时钟其他都可以用空函数顶着。第三才是LCD驱动。UCGUI要把像素画到屏幕上最后一定要落到“往某个地址写一个颜色值”这个动作上。而具体怎么写取决于你的屏接口是SPI、8080并口还是RGB接口以及你的屏用了哪颗驱动IC比如GC9307、ILI9341、ST7735各不相同。一份标称“已经移植好”的UCGUI例程通常意味着前两座大山已经被工程作者翻过去了。核心库编得动、GUI_X层跑得通你真正需要动手的只剩下第三件事把屏幕驱动换成你实际用的那一套然后让UCGUI在合适的时候调用它。所以你不需要从零理解UCGUI的内部调度你要做的是在它留给你的接口上“填空”。1.2 哪些文件是整个工程的“生命线”碰都不要碰很多人拿到工程后的第一反应是把所有带.c的文件都打开翻一遍想找到底哪一段代码能“改一下就能用”。这种扫雷式操作很容易踩中核心库。以我手上这份工程为例它的典型结构是UCGUI源码应用层外设驱动三层结构。其中UCGUI目录下的Core、Widget、WM这些文件夹是图形库的内核你不需要、也不能去改它们的逻辑。Config目录里的GUIConf.c、LCDConf.c属于配置层前者管内存池大小、任务数量、窗口管理器是否启用后者管分辨率、色深、层数这些显示相关参数这是你重点要看的文件。真正需要你动手的外设驱动通常被隔离在BSP_LDC或Hardware/LCD这样的目录下里面会有一个带屏型名称的文件比如gc9307.c、lcd_spi.c或者一个通用的LCD_Driver.c。如果你打开工程树看到文件命名里带有屏型或者带明显的“Driver”字样基本就是它了。我给人做工程评审时遇到最多的一个问题就是有人把UCGUI内核里的文件复制出来改成自己的驱动结果编译器疯狂报重定义。记住一个原则核心库是只读的你改的是外围连函数名都别动你只是去实现它声明的接口。2. 工程结构拆解改驱动前先认识你手里的地图2.1 一个典型UCGUI KEIL工程到底长什么样我见过的UCGUI例程工程虽然版本多样但目录结构大概逃不出下面这种格局。你可以对照自己手里的工程先画一遍地图。STM32_UCGUI_Demo/ ├─ User/ # 应用层 │ ├─ main.c # 主入口 │ └─ lcd_app.c # 应用画图逻辑 ├─ UCGUI/ │ ├─ Config/ │ │ ├─ GUIConf.c # GUI内存池OS任务数配置 │ │ └─ LCDConf.c # LCD分辨率/色深/层配置 │ ├─ Core/ # 图形库内核只读 │ ├─ Lib/ # 带lib封装的库文件如果有 │ └─ GUI_X/ # 硬件/OS适配层 ├─ BSP/ │ ├─ LCD/ │ │ ├─ gc9307.c # 想换屏主要改这个文件 │ │ ├─ gc9307.h │ │ ├─ lcd_spi.c # SPI底层时序一般是固定不变的 │ │ └─ lcd_spi.h │ └─ timing.c # 延时函数 ├─ STM32F103_Drivers/ # 标准外设库/HAL库 └─ Project/ ├─ demo.uvprojx └─ RTE/这里面有几个关键点屏幕驱动文件、LCDConf.c、GUI_X文件夹下的时间基准实现。我把三者单独拎出来讲。2.2 “LCD驱动”这个说法其实涵盖了三个不同层面的东西很多人以为LCD驱动就是那个带屏型名字的.c文件其实严格来说它由三层组成。最底层是时序层也就是你的SPI初始化、片选电平、读写时序一般写在lcd_spi.c里。只要你不换MCU的SPI引脚这一层基本可以不用动。中间层是芯片驱动层比如gc9307.c它负责按照GC9307数据手册的初始化命令表把屏点亮然后提供“设置显示窗口”和“写像素数据”这两个最基本的接口。最上层是UCGUI的适配层在LCDConf.c里通过LCD_X_DisplayDriver这种分发函数把UCGUI的“初始化控制器”“显示缓冲”等请求转接到中间层。所以那句“修改LCD驱动就能用”完整翻译过来是时序层不动中间层整个重写成新屏的驱动上层确认接口函数被正确调用。记住这个层次你改屏的时候才不会眉毛胡子一把抓。3. 驱动修改第一刀LCD初始化序列与分辨率对接3.1 从芯片资料里找到“初始化命令表”这是最关键的一步拿到一颗没接触过的LCD屏第一件事不是写代码而是打开屏驱动芯片的数据手册翻到“Initial Setting”或“Display Setting”章节。屏厂一般会在那个章节给一份初始化命令序列里面是一串寄存器和数值。你把这串序列原样搬进工程屏幕基本就能亮起来。以GC9307为例这颗芯片常见于2.4寸240x320的IPS屏接口支持三线/四线SPI和8080并口。它的初始化有几个典型动作进入厂商私有命令模式、配置电源和伽马、设置显示方向、打开显示。写进代码里大概长这样。static void GC9307_Init(void) { LCD_CS_LOW(); /* 进入厂商命令解锁模式不同芯片解锁方式不同以手册为准 */ LCD_WR_REG(0xFE); LCD_WR_DATA(0x00); LCD_WR_REG(0xEF); LCD_WR_DATA(0x00); /* 电源、伽马等配置直接抄手册里的命令表 */ LCD_WR_REG(0x80); LCD_WR_DATA(0x03); /* 设置像素格式 RGB565如果芯片支持0x3A这条指令 */ LCD_WR_REG(0x3A); LCD_WR_DATA(0x55); /* 设置显示方向0x36是Memory Access Control */ LCD_WR_REG(0x36); LCD_WR_DATA(0xC8); /* 设置显示窗口为全屏 */ LCD_WR_REG(0x2A); /* 列地址0 ~ 239 */ LCD_WR_DATA(0x00); LCD_WR_DATA(0x00); LCD_WR_DATA(0x00); LCD_WR_DATA(0xEF); LCD_WR_REG(0x2B); /* 行地址0 ~ 319 */ LCD_WR_DATA(0x00); LCD_WR_DATA(0x00); LCD_WR_DATA(0x01); LCD_WR_DATA(0x3F); LCD_WR_REG(0x2C); /* 开始写显存 */ LCD_CS_HIGH(); }这里要特别提醒一句上面的寄存器数值是我为了讲流程写的一个简化骨架不同批次的GC9307模组工厂给的初始化命令可能都不一样。你手里的屏资料里如果有“厂家推荐初始化配置”直接把那一整段替换上去比任何通用模板都靠谱。3.2 分辨率、扫描方向和RGB顺序的坑会在最开始集中爆发屏幕亮起来之后第一个遇到的就是显示方向和颜色顺序问题。同样是240x320的屏有的模组出厂扫描方向就是横的有的需要你设置镜像。这个坑很好识别如果你用UCGUI画一个0到100的红色进度条屏幕显示出来的是从上往下拉的一条竖带而不是从左往右的水平条说明行和列方向没对上。这时候要改的是0x36寄存器的值也就是MemoryAccessControl。它的bit5是RGB/BGR顺序开关bit6、bit7是X/Y扫描方向。常见的几个值0x48表示横屏扫描、0xC8表示横屏镜像RGB/BGR交换。具体哪个值配哪个方向建议写个小程序在屏幕上画一个左上角为纯红、右下角为纯蓝的矩形屏幕转一圈哪个方向的颜色和位置都正常就用哪个值。另一个和方向绑定的是初始化完之后的“偏置原点”。有些芯片在扫描方向改变后它的(0,0)不一定在屏幕的物理左上角而是有可能跑到右下角去。所以UCGUI画出来的坐标和屏幕实际显示位置会错位这时候不要急着改UCGUI坐标系统的原点先看看驱动芯片的0x36设置是否覆盖了镜像关系。3.3 初始化序列为什么必须放在UCGUI启动之后很多UM在初始化屏幕时会老实地调用GUI_Init()然后再做自己的屏初始化。这个顺序在大部分UCGUI版本中没问题但有一个隐患UCGUI在初始化时会通过LCDConf.c的LCD_X_DisplayDriver函数下发LCD_X_INITCONTROLLER命令去执行它认为的“初始化控制器”动作。如果你自己的屏初始化写在GUI_Init()之前一旦UCGUI内部又触发了一次控制器初始化你的屏就会被重复复位造成花屏。所以更稳妥的做法是在你自己的LCD驱动层里通过LCDConf.c里的LCD_X_DisplayDriver回调把初始化序列挂在LCD_X_INITCONTROLLER分支下或者确保GUI_Init()之后再执行你的初始化代码。工程作者说“改驱动就能用”通常就是指你已经把初始化动作挂到了合适的钩子上。4. 驱动修改第二刀窗口设置、打点和读点的底层实现4.1 打点函数UCGUI性能瓶颈几乎都集中在这初始化搞定之后UCGUI要把字符、控件画出来最终靠的是两个底层动作设置显示窗口范围然后往窗口里连续写像素数据。屏幕驱动芯片的经典写法是先发0x2A/0x2B设置行列窗口再发0x2C进入写显存模式。之后你每写的一个像素数据芯片都会自动放到窗口的当前位置并递增不需要重复设置窗口。这样一个“开窗-写批量数据”的流程就是优化的关键。static void GC9307_SetWindow(uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1) { LCD_WR_REG(0x2A); LCD_WR_DATA(x0 8); LCD_WR_DATA(x0 0xFF); LCD_WR_DATA(x1 8); LCD_WR_DATA(x1 0xFF); LCD_WR_REG(0x2B); LCD_WR_DATA(y0 8); LCD_WR_DATA(y0 0xFF); LCD_WR_DATA(y1 8); LCD_WR_DATA(y1 0xFF); LCD_WR_REG(0x2C); } static void GC9307_WrPixels(uint16_t *pData, uint32_t len) { while (len--) { LCD_WR_DATA(*pData); } }在UCGUI的底层对接中你通常需要把这些“开窗写像素”的动作封装成可被LCDConf调用的函数有的版本里是Lcd_SetPixel有的版本是更细的FlexColor接口。关键在于能批量写就绝对不要单点写。UCGUI的缓冲如果开了到全屏一层的buffer那它每次刷新都会用Rect或者Color的批量接口把整个区域数据倒给你你的底层写数据函数速度就直接决定了UI刷新率。我见过有人把Lcd_SetPixel写成每次都重新设置0x2A/0x2B再写两个字节结果跑个窗口拖拽跟PPT一样问题不在UCGUI而在驱动。4.2 读点函数能不读就不读但你不能没有UCGUI在部分绘图操作里需要读回当前像素比如做透明叠加、XOR操作、或者窗口滚动时有“把原缓冲读出来再写回去”的需求。驱动芯片读显存通常是发0x2E寄存器之后从DOUT引脚读回当前地址的像素值读完之后地址自动递增。真要在SPI接口上实现读点往往要做总线方向切换稍有不慎时序就崩了而且速度极慢。所以一个很实际的折中方案是如果UCGUI开启了全屏缓冲也就是LCDConf.c里把缓冲层数配成2层或1层读点请求可以优先从内部缓冲直接返回根本不用去读芯片。如果你的底层驱动不支持读点又不想碰缓冲配置也可以直接把读点函数实现成返回一个固定值比如0。这会让某些依赖读点的效果不工作但纯粹的UI显示不受影响。我实际处理过几个要求快速上线的项目只要不涉及到滚动和高级窗口透明效果读点函数返回0并没有引发任何可见问题。所以别被“读点必须实现”这句话吓住先看你的工程是否真的调用它。4.3 三线SPI和四线SPI的坑为什么一飘屏就想到它热词里一直有人在查STM32三线SPI说明很多屏SPI接口确实容易搞混。所谓三线SPI通常是指没接独立的D/C引脚命令和数据都是走一根线靠第9个bit来区分的模式四线SPI则是有CS、SCLK、DIN、D/C四根线D/C高电平表示数据、低电平表示命令程序写起来直观得多。如果工程给你的例程默认是四线SPI而你手里的屏模组是“三线SPI9bit模式”那你光改驱动函数内容还不够整个SPI发送字节的底层都要改成9bit打包发送。这也是为什么我说lcd_spi.c和gc9307.c是两个独立文件芯片驱动层可以照抄新屏的初始化命令表但时序层一定要跟你实际硬件接口匹配。三线模式下写一个命令字节和一帧数据的组合最终可能是把D/C位拼到了每个9bit的最前面程序逐位移位发送速度会明显慢半拍这也是有些人换屏后觉得UCGUI重绘慢的第一怀疑对象。5. KEIL工程配置与编译踩坑从报错到跑到屏5.1 换屏之后常见的三个编译错误先对号入座UCGUI例程在换屏时最常见的编译错误不分先后但都可以很快定位。一类是“identifier is undefined”。原因是工程里原有的屏型号文件被删了但某个配置头文件里还留着针对原来屏的宏定义或函数声明把残留引用清掉即可。你可以在工程里搜索原来的屏型号名比如ILI9341凡是引到的地方要么删除要么改成新屏。二类是“No space in execution regions”。这个报错最经典它表示目标代码超出了Flash或RAM限制。如果闪存不够先把优化等级从-O0调到-O1或-O2如果RAM不够看GUIConf.c里的GUI_ALLOC_SIZE它定义了UCGUI内部内存池大小过大就会撞到RAM天花板。很多例程为了让控件跑得富余直接把GUI_ALLOC_SIZE拉到几十KB在RAM小的芯片上就会卡在这里。三类是“Internal command error”。这个报错有迷之色彩常常发生在编译优化等级改动后、或者工程文件损坏时。我的处理流程是先Clean Target把中间产物全部删掉再重新编译如果还报就在Project菜单里点Manage ProjectItems看一下有没有失效的源文件路径顺带检查是不是装了多个MDK版本导致编译器路径错乱。5.2 内存配置GUI_ALLOC_SIZE和启动文件的堆分开看UCGUI的内存来源分两块。一块是GUIDEMO里常见的GUI_ALLOC_SIZE它在GUIConf.c中定义UCGUI把所有动态分配的控件结构、文本缓冲都从这个内存池里拿。另一块是整个MCU启动文件里定义的Heap_Size它是C库malloc使用的堆UCGUI如果采用标准malloc作为底层内存来源才会用到它。所以调内存的时候别只盯着启动文件里的要看GUIConf.c使用了哪种使能方式。裸机UCGUI通常会在GUIConf.c里直接定义一个静态数组作为内存池然后在GUI_X文件里把GUI_ALLOC_Init指向这个数组。这个时候启动文件里的Heap_Size其实可以保持默认甚至调小因为它已经不影响UCGUI自身内存池了。很多人在小容量芯片上为了把GUI_ALLOC_SIZE调大反过来把启动文件里的Heap缩得很小结果标准库的printf、文件操作全崩了这是没分清两个内存来源造成的。5.3 编译速度慢不是MDK不行UCGUI例程动辄几十个源文件加上核心库源码MDK第一次全编译慢是正常的。但如果你每次改个驱动都要等五分钟就值得优化。最立竿见影的办法是把你确认不再改的UCGUI核心源码编成库例如lib库然后从工程里移除对应的源码文件只保留头文件和库文件。这样编译时MDK只需要链接库不需要反复编译核心源码。其次是在C/C选项卡里检查有没有不小心开启了“-g”过深调试信息或者把项目放在机械硬盘上。尝试过的人都知道MDK项目放到固态硬盘和网络路径上编译速度能有质的差异。6. 实测经验我改完GC9307驱动后的验证顺序6.1 第一个测试程序不要一上来就跑GUI_Init换完驱动文件第一件事不是整个GUI工程跑起来而是写一个最简单的裸机测试不调UCGUI直接把屏当普通外部设备操作一遍。我的验证顺序是先做全屏填充用0x2A/0x2B把窗口设为全屏然后往0x2C灌入同一个颜色值。如果全屏能变成纯色说明初始化序列、SPI时序、写数据通路全通了。第二步做分区域填充左上角画一个红色矩形右下角画一个蓝色矩形验证坐标准确性和行列方向。第三步再跑GUI_Init()然后调用GUI_DispStringAt在屏幕上画一行文字。三步全部通过才说明驱动真正可用了。这里面有个小技巧全屏填充颜色时不要用红色0x00F800这种直接写寄存器先用一个循环把相同颜色值灌进去再用示波器或者简单的手摸屏幕表面温度检查是否有些区域一直没刷新。如果你用的是带缓冲的SPI屏幕数据发送完之后一定要留意芯片是否真的把数据接收完了有些GC9307的SPI在数据量大的时候需要等待Busy信号释放否则掉最后一帧数据。6.2 白屏、黑屏、花屏到底先查哪一环这三个现象我的排查顺序几乎是固定的。白屏优先怀疑初始化序列没有完整执行或者电源配置不对最常见的是复位引脚时序和进入私有模式的命令没对齐。先看你的硬件复位引脚是不是在初始化前拉低过几十毫秒在初始化函数开头手动拉一次复位。黑屏黑屏和白屏看着像但成因差很多。黑屏很多时候是背光没亮或者信号发到了错误的SPI总线上。先用示波器确认SCLK和DIN上有波形再确认CS是不是被其他外设顺带拉低了。花屏花屏多半是分辨率窗口或者像素格式不匹配。比如你初始化里设置的是RGB666但UCGUI配置的是RGB565数据位宽对不上颜色就会变得鬼畜。另一个常见原因是0x36扫描方向设置和屏模组的物理接法矛盾导致上下半屏内容互换看起来也像花屏。这些查一遍0x3A和0x36这两条命令基本都能解决。6.3 如果显示方向不对改驱动还是改应用很多时候改屏的方向问题并不需要动驱动文件。UCGUI提供了GUI_SetOrientation()这类接口可以整体旋转坐标系统应用代码不用改任何地方。但要注意这种旋转是UCGUI层面的映射代价是每次画点都多做一层坐标换算刷新速度会比底层驱动直接改方向慢一些。如果你在做需要高频刷新的界面我更建议直接改LCD驱动初始化里的0x36寄存器让物理扫描方向和你的UI坐标一致速度损失最小。我做过一个设备用户要求屏幕横过来用。我一开始图省事直接调GUI_SetOrientation帧率掉了一截。最后老老实实改回驱动里0x36的方向值再把UCGUI的分辨率和宽高对调画面瞬间流畅。所以我的经验是能改底层就不做应用层旋转改应用层只是为了快速验证不是长期方案。最后再分享一个我个人的习惯改完驱动在工程里贴一份标注好日期的屏参记录把芯片型号、初始化命令表来源、0x36和0x3A的最终值、行场窗口最大值都抄进去。UCGUI这种工程经常在一个项目里被反复翻出来改屏用几个月后你再拿到它直接看记录就能一秒想起当初改了什么东西。这个习惯帮我省过很多次返工时间。本文还有配套的精品资源点击获取