半年前交付的HMI项目最近又要加新功能打开旧工程时发现TouchGFX Designer已经提示“Project created with an older version of TouchGFX Designer”。一开始我没当回事以为点个继续就行结果客户发来的新UI资源在旧版本里压根打不开。TouchGFX版本升级这事表面上就是装个新软件实际上牵扯到电脑端Designer、STM32CubeMX中间件、嵌入式固件库、编译器包括路径这么一长串东西。这篇LAT1227应用笔记把我从TouchGFX 4.13.0升级到4.18.0的完整过程和踩过的坑记录下来给准备做版本升级的嵌入式UI工程师一份可以直接照做的清单。1. 升级先想清楚TouchGFX版本链到底是什么1.1 一个GUI框架牵出四条版本线先说结论TouchGFX不是一个独立的软件而是一套由“电脑端Designer 嵌入式库 生成代码 CubeMX中间件”组成的生态。版本升级表面上升的是Designer实际要同步处理的是整条链。从工程角度看一个典型的TouchGFX工程目录包含.touchgfx项目文件、.ioc的CubeMX工程、Middlewares/ST/TouchGFX/touchgfx下的库源码、Application/User下的用户代码。这四部分各自有版本和配置升级时必须全部照顾到。版本线常见位置作用TouchGFX Designer电脑端安装程序可视化设计UI、生成界面代码TouchGFX GeneratorCubeMX中间件包在CubeMX中集成生成HAL层初始化代码TouchGFX Embedded Library工程Middlewares目录实际参与编译运行的GUI框架源码编译器/IDEKeil/IAR/STM32CubeIDE编译生成代码与库代码这四者的版本需要匹配。为什么因为Designer生成的代码会调用Embedded Library中的API而Library的某些API在不同版本间会调整Generator根据.ioc配置生成的HAL初始化代码也与Library版本强相关。如果你只把Designer升到新版而工程里Embedded Library还是旧的就会遇到一堆编译错误、链接错误严重时界面直接进不去。1.2 版本跨度不同工作重心完全不同升级之前要判断版本跨度。版本跨度决定了你是“小改”还是“大动”。比如小版本升级如4.17.0 → 4.18.0通常Designer和Library都能向下打开生成代码改动小重点检查编译警告。大版本跨越如4.13.0 → 4.18.0项目文件格式可能变化、字体流程变化、缓存机制变化需要按照完整迁移流程走。我这次就是典型的跨越式升级4.13.0 → 4.18.0。中间隔了5个大版本UI工程本身不复杂但依赖链路长所以每一步都要清晰。另一个常见的情况是从4.16.0升到4.21.0跨度没那么大但同样建议按下面的流程走一遍尤其是备份和版本记录两步能帮你省掉很多返工时间。如果项目里用了大量自定义控件、外部字库、多语言文本要特别注意版本跨越越大资源文件的格式变化概率越大文本哈希表的生成规则也可能变这些是隐藏风险点后面章节会展开。2. 开动前先站稳备份、记录、锁定回滚点2.1 三个备份一个都不能少升级前的备份是很多人最容易跳过的一步但也是最重要的一步。我建议做一个“三重备份”整个工程目录复制一份到本地磁盘排除build、Debug、Release等中间产物目录那些重编译就会出来。单独把.ioc文件和.touchgfx文件复制一份这两个文件是整个工程配置的核心后面升级如果出问题只回滚这两个文件也可以挽救大部分工作。用户手写的业务代码单独备份主要是Application/User目录下的代码尤其是Model.cpp、Screen*Presenter.cpp、Screen*View.cpp中你手动修改过的部分。如果在用Git升级前打一个tag比如release_v1.0_TouchGFX4.13。如果没有Git直接复制一份完整目录并加日期标识目录命名要能一眼看出是哪个版本哪个日期别用final、final2这种。这是血泪教训我曾经升级到一半发现字体渲染效果和旧版本不一样想回退却发现旧工程已经被新Designer改了一遍项目文件格式这时如果没有备份就只能凭记忆改回来工作量直接翻倍。2.2 记录升级前后基线信息在升级前写一个文本文件记录当前环境信息内容大致如下升级前基线信息日期2024-xx-xx - TouchGFX Designer: 4.13.0 - STM32CubeMX: 6.4.0 - TouchGFX Generator: 4.13.0 - MCU: STM32H750VBT6 - 屏幕分辨率: 1024x600 RGB888 - 颜色深度: RGB565 (注意这个极容易被忽略) - 帧缓冲: 双缓冲0x24000000地址 - 触摸IC: GT911I2C - 编译器: IAR 8.50.9, 优化级别 High Speed - 字库: 默认English Windows系统字体 Verdana这个文件非常重要。举个例子很多人在升级后发现图片颜色不对、发紫发绿排查了半天最后发现是颜色深度从RGB565被新字段默认改成了RGB888而屏幕驱动还是按565配置的。如果你升级前记录了基线颜色深度这个问题几分钟就能定位。建议升级完成后再更新这份文件到新版本状态放进工程doc目录作为交付物。这样下次再有人要升级直接看这份文件就能了解工程全貌不用再瞎猜。3. 工具链第一步Designer与CubeMX插件的更新顺序3.1 安装新版Designer能否与旧版共存先给出一个明确的顺序建议先装新版Designer再升级CubeMX和Generator最后才动工程文件。反过来操作容易在半路卡住。TouchGFX Designer安装时会在C:\TouchGFX下创建带版本号的目录比如C:\TouchGFX\4.13.0和C:\TouchGFX\4.18.0两者可以共存。所以不需要卸载旧版直接安装新版即可。这个设计很实用如果新版打开项目失败你还能用旧版继续干活不至于被卡死在一个版本上。安装新版之前有两个小细节关闭所有正在运行的Designer实例否则某些dll文件被占用安装过程可能出现异常。如果电脑上之前装的是社区版Community新版本安装时要注意许可证选择不要误选成VIP/Pro版本导致后续生成代码时功能受限。安装完成后启动新版Designer确认版本号无误。如果你习惯用命令行脚本给客户交付这个步骤会影响到后续的自动化构建路径。3.2 CubeMX与TouchGFX Generator的对应关系打开STM32CubeMX选择Help → Manage embedded software packages在“STM32Cube MCU Packages”里可以找到TouchGFX Generator的版本列表选择与Designer对应的版本比如4.18.0安装。这里有一个容易踩的坑如果只更新了Generator而没有更新CubeMX本体某些旧版本CubeMX无法识别新Generator。所以建议先把CubeMX更新到新版本配套的版本比如对TouchGFX 4.18.0CubeMX至少需要6.6.0以上具体以ST官方Release Note为准再安装对应版本的Generator。还有另一个更隐蔽的问题在已有的.ioc工程中升级Generator版本之后需要在CubeMX的Middleware and Software Packs页面手动把TouchGFX的版本从旧版切换到新版然后重新生成初始化代码。如果不切换工程还是按旧Generator生成新版本特性不会生效。如果项目不是用CubeMX生成的HAL管理方式而是手动维护的CMake工程那么需要跳过Generator环节直接手动更新Middlewares库源码和HAL配置这个工作量会略大但思路一致。我这次用的是CubeMX生成的工程所以按正常流程走即可。4. 项目迁移核心用新版Designer打开旧项目并补齐文件4.1 打开项目时的迁移向导用新版Designer打开.touchgfx文件时大概率会看到一个提示项目由旧版本创建是否转换为当前版本格式。此时不要急着点确定。我自己习惯的操作顺序是把原工程复制一份到临时目录用新版Designer打开这个副本。观察迁移过程中有没有报错弹窗尤其是资源文件、字体文件相关的错误。如果副本顺利打开所有Screen和Widget都正常显示再回到原工程操作。在原工程中打开项目确认迁移向导提示点击继续并保存。迁移向导完成之后Designer会重写项目文件格式。这个格式是基于XML的新版会新增一些字段或者调整某些属性的写法。如果你使用Git做过版本管理此时git diff可以看出项目文件的巨大变化这是正常的。重点是自己手动添加过的用户代码区域一般在Screen1View.cpp这种文件中会有touchgfx开头的注释标记保护段升级不应该覆盖它们。如果迁移过程中提示resource not found或字体文件路径无效多半是旧版本使用了相对路径但目录结构变化了。这时去Designer的Assets页面逐个检查图片、字体、文本资源重新指定文件路径即可。4.2 替换Middlewares下的TouchGFX库源码这一步是很多人容易漏掉的。新版Designer重新生成代码只负责生成应用层代码它不会自动帮你替换工程Middlewares/ST/TouchGFX目录下的嵌入式库源码。正确做法是从Designer安装目录中找到最新的库封装包一般位于C:\TouchGFX\4.18.0\library\ports或类似路径下。根据你的编译器、MCU架构Cortex-M7、屏幕接口类型选择对应的库文件夹然后覆盖到工程中的Middlewares/ST/TouchGFX目录。这里特别提醒一点覆盖之前把旧库目录整个重命名成TouchGFX_old_4.13保留在工程外。原因是新旧库的API可能有细微差异如果你在编译后想对照某个函数是旧版还是新版定义旧库源码直接对照很方便。替换完库源码后如果工程是用CubeMX的Middlewares/ST/TouchGFX路径加include path的编译器会自动找到新版头文件。如果是手动CMake工程检查一下CMakeLists.txt中的include path是否指向了正确的新库目录。4.3 资源文件、字库、图片的重新生成升级后字体和图片资源需要重新生成。因为新版本对字体渲染、图片格式支持的底层实现有调整。在Designer的“Typography”和“Images”页面中检查所有字体和图片资源然后点击Generate重新生成资源文件。图片方面要注意色彩格式。旧项目如果是RGB565新Designer可能在生成时默认改为RGB888导致Flash占用加大。可以在Project Settings里显式指定颜色深度保持和原工程一致。如果屏幕驱动本身支持RGB888可以考虑顺手升级但要评估Flash容量和带宽是否充足。字体方面TouchGFX从4.16左右开始改进了字体缓存机制4.18版本对文字渲染有优化。重新生成字体资源之后建议检查一下中文字库如果你用了中文生成的字库文件大小和页表数量应该匹配。如果发现文字模糊、间距异常检查字号和DPI设置是否有变化。文本资源方面多语言工程的texts表也会重新生成文本ID的哈希规则可能变化生成后需要检查所有TextArea控件绑定的文本ID是否仍然正确。5. 生成代码差异点编译前必须知道的改动5.1 目录结构与头文件引用变化用新版Designer生成代码后和旧版生成的代码对比最直观的是目录和文件组织形式变化。我这次升级遇到的情况是旧版生成的头文件分散在generated/texts、generated/images、generated/fonts等目录新版统一在generated下但某些头文件的引用路径变了。用户代码文件如Screen1View.cpp、Screen1Presenter.cpp位于game目录新版会重新生成但不会覆盖你手动修改过的用户回调代码通常有touchgfx防护注释。编译器中需要重新添加include path否则会报找不到头文件。如果你的IDE是Keil在Options for Target → C/C → Include Paths中添加新目录如果是IAR在Project → Options → C/C Compiler → Preprocessor中操作如果是CMake改CMakeLists.txt。另外一个容易漏掉的地方链接脚本.icf或.ld中可能涉及帧缓冲地址、堆栈大小的配置版本升级后RAM占用有变化需要适当调整。5.2 HAL接口和配置参数新版TouchGFX的HAL层配置参数有变化。以我实际遇到的情况为例旧版本中HAL::initialize()的参数列表较短新版可能增加了帧缓冲数量、缓存配置等参数。这种变化会在CubeMX生成的新HAL代码中体现重新生成后不要拿旧代码直接覆盖让新代码接管即可。帧缓冲地址的定义方式也可能变化。检查TouchGFXConfiguration.cpp中的FrameBuffer地址是否与链接脚本中的段定义一致。4.18版本开始部分平台支持多种帧缓冲策略包括单缓冲、双缓冲、局部缓冲默认值可能和旧工程不同。这些接口变化从生成的代码diff中可以看见。如果你没有保留旧生成代码做对比可以通过阅读新版生成的HAL目录下的说明文件来确认。更笨但有效的方式是用IDE直接编译把报错信息挨个过一遍对着新库源码查找对应API比猜要快得多。5.3 编译报错对照表以下是我升级过程中遇到的典型报错以及对应的排查方向。不同项目情况不同但排查思路可以借鉴。建议收藏起来编译/链接报错可能原因处理方式fatal error: touchgfx/Font.hpp: No such file or directory头文件路径缺失在IDE中添加include path到新版库目录undefined reference to touchgfx::HAL::setDisplayOrientationAPI不再存在或改名查看新版本HAL API改用新的接口cannot open file text conversion...字库资源未重新生成在Designer中重新生成字体error: use of deleted function拷贝构造被禁用检查自定义类中是否拷贝了非拷贝对象multiple definition of touchgfx::Bitmap新旧库源码重复链接检查是否同时链接了多个版本的库文件Flash overflow代码体积超限检查颜色深度、字库体积、优化等级这些示例都是可能遇到的真实问题。实际上手时以diff为准不要照搬报错含义先看是否重复引用、路径是否错误、API是否改名。6. 升级后验证不只跑通demo还要回归UI6.1 基础显示与触控验证烧录后先不急着看业务功能先把基础显示链路验证完。这一步能帮你把“显示环境问题”和“业务逻辑问题”隔离开。具体做法屏幕点亮背光正常无闪烁。全屏填充纯色确认RGB顺序是否正确颜色通道是否接反。显示一张带渐变色的图片观察颜色过渡是否平滑、有没有色阶断层。用设计器生成的Demo页面做滑动、点按测试确认触摸坐标没有偏移。切换几个Screen确认页面切换动画是否流畅有没有明显的掉帧。如果第2步颜色不对大概率是颜色深度或RGB顺序问题如果第4步触摸偏移检查触摸屏驱动里的分辨率配置和I2C地址是否被新版生成代码覆盖。6.2 性能与资源占用对比用编译生成的.map文件对比升级前后的Flash和RAM占用。TouchGFX新版本往往引入更多特效但资源占用也可能变大。如果内存超出需要优先考虑以下优化方向减少缓存的帧缓冲数量从双缓冲改回单缓冲对某些应用是可接受的。关闭局部缓冲或调小缓冲区尺寸。检查字库是否包含了不需要的语言移除多余字库。图片资源压缩格式改为L8或A4格式减少Flash占用。帧率可以借助TouchGFX内部帧率计数器测量。在代码中启用帧率统计后串口打印帧率数据。实测下来4.18.0在相同图形复杂度下文字渲染的帧率比4.13.0略有提升但Flash占用约增加4%左右具体与字体资源有关。如果你的硬件Flash吃紧这个增量必须提前评估。6.3 回归测试清单跑完基础验证后建议按以下清单做一轮完整回归确保升级没有破坏原有功能每个Screen都能正常打开且无卡死。每个可点击控件都能触发对应回调。文本动态刷新如时钟、数值、进度条显示正确。动画循环结束后画面不残留。长时间运行至少2小时内存占用稳定不增长可通过串口打印堆信息观察。触屏校准值在重启后不丢失这是NV存储相关功能常见回归点。我这里特别强调最后一项触屏校准值往往存在Flash或EEPROM中升级过程中如果擦除了存储区可能导致校准失效。之前有次升级就是没注意这一点被现场工程师催了大半天结果只是重新校准一下就解决。所以升级前如果能把校准数据的备份区和偏移地址记下来排查会快很多。最后再分享一个我自己的经验教训。升级完成后我一度觉得跑通Demo就收工了结果第二天测试反馈主页面的背景图有色差。排查了半天发现是升级时Designer默认把图片资源从RGB565转成了RGB888而屏幕驱动还是按565配置的。这个问题的根源就是资源格式与屏幕驱动不匹配。所以升级后第一件事不是看动画效果多流畅而是先做全屏纯色测试把显示链路验证完再谈UI效果。这种从最底层往上排查的思路在任何一次版本升级中都同样适用。