前阵子有同行问我刚拿到 STM32H7S78-DK板子出厂跑的那个 TouchGFX 演示效果确实惊艳触摸滑动、转盘动画、实时波形全都非常流畅。但 ST 官网的板卡页面里只给了固件下载和入门文档想要拿这份出厂 TouchGFX Demo 的源码却翻遍页面也找不到入口。这个问题看似简单实际上第一次接触这块板子的人几乎都会卡在这里。我把当时的排查过程、拿源码的三条官方路径、以及本地重建工程时踩过的坑完整梳理了一遍希望对后面玩这块板子的人有点帮助。1. 为什么出厂TouchGFX Demo的源码不跟固件放在一起先理解“出厂固件”和“示例工程”的关系1.1 STM32H7S78-DK 出厂演示跑的是什么STM32H7S78-DK 是 ST 面向图形显示应用推出的评估套件核心芯片是 STM32H7S7 系列——Cortex-M7 内核主频可以跑到 600 MHz片上集成了 Neochrom 图形加速器、Chrom-ART DMA2D 控制器还带 MIPI DSI 显示控制器。板载一块 4.3 英寸左右的高清触摸屏外面再接了 64MB 外部 SDRAM 做显存和帧缓冲整个硬件就是为 TouchGFX 这类 GUI 框架准备的。出厂 Demo 展示的并非单纯一张静态图片而是一整套交互式界面转盘滚动的图片列表、带阴影和半透明效果的卡片、动态曲线刷新、文字动画等。这套演示最主要的目的是让客户第一眼就能感受到基于 Neochrom GPU 和 TouchGFX 渲染引擎在 H7S7 系列上的性能上限。也正因为它跑起来非常流畅很多人才会想拿到源码看看官方到底做了哪些优化。实际上这块板子出厂时 Flash 里烧录的是经过编译优化后的二进制固件。我们在板卡上看到的画面就是这个固件跑起来的效果。原厂烧录环节只会关心“固件能不能正常启动、触摸灵不灵敏”而不会把一堆源码工程一起烧进去。源码作为“开发支持材料”走的是另外一条分发路线。1.2 固件、软件包、示例工程同一份 Demo 的三种形态很多嵌入式老手刚到 ST 的生态里也会被绕晕因为同一个演示程序在 ST 官方体系里至少有三种形态出厂固件Pre-programmed firmware就是板卡上电后直接运行的二进制文件。它的存在是为了让你“先看到效果”通常不提供源码或者源码被拆到别的包里。软件包STM32Cube MCU Package针对某个 MCU 系列发布的完整固件库集合里面包含 HAL 驱动、BSP 板级驱动、中间件以及大量示例工程。官方 Demo 源码通常以“Example / Demonstration”工程的形式放在这个包里。TouchGFX 工程示例Example/Board FarmTouchGFX Designer 这个 GUI 设计工具里内置了大量示例工程可以直接按板卡型号筛选。很多板的出厂演示就是从这些示例工程衍生出来的。明白这三种形态之后问题就变成了STM32H7S78-DK 的出厂 TouchGFX Demo 源码到底隐藏在哪个包里。我当初正是把这三个方向挨个试过才把完整的工程挖出来。1.3 为什么 ST 不直接把源码挂在板卡下载页这或许是很多人的第一反应板卡页面下直接放一个“Factory Demo Source Code.zip”不好吗但仔细想一下这种分发的复杂度比表面看起来高得多。TouchGFX 工程不是一套孤立代码就能跑起来的。它依赖的 HAL 驱动、BSP 代码、以及由 TouchGFX Designer 自动生成的 GUI 框架都需要和具体的 MCU 固件库版本、TouchGFX 工具链版本严格匹配。如果直接放一个压缩包里面用了 A 版本的 HAL而用户本地装的是 B 版本的 CubeMX打开工程时就会冒出一堆莫名其妙的警告。把源码放进统一的 Cube 固件包和 TouchGFX 工具链里通过版本管理来保证一致性反而更符合真实开发流程。另外TouchGFX Designer 生成的代码本身是动态的。你在 Designer 里改一个颜色、改一个坐标重新点一次 Generate Code生成的 .cpp/.hpp 就会变。官方如果直接发布固定源码用户反而失去了“改完再生成”的灵活性。最佳做法是给你一个带 GUI 配置文件的工程骨架而不是一份一次性快照。2. 找源码的官方路径从 Cube 固件包到 TouchGFX Designer 的 Board Farm2.1 路径一STM32CubeH7 固件包中的 Demonstrations 目录我最推荐的第一条路径是去下载 STM32CubeH7 固件包。这个包可以从 ST 官网的 STM32CubeH7 软件页面获取下载体积不小但内容非常全。解压之后找到:STM32Cube_FW_H7_Vx.y.z/ └── Projects/ └── STM32H7S78-DK/ ├── Applications/ └── Demonstrations/Demonstrations目录下通常就是官方出厂演示的完整工程里面包含了 .ioc 工程配置、TouchGFX 相关源文件、BSP 驱动、启动文件、链接脚本等。找到工程后用 STM32CubeIDE 打开即可。如果你的目的只是想要这份代码回去完整编译一次这条路最直接。需要注意一点STM32H7S7 系列对固件包版本有要求。并不是任意一个 STM32CubeH7 老版本都能看到 STM32H7S78-DK 的文件夹。我自己的经验是直接下载当时的最新版本再对照 Release Notes 确认是否已经包含该板卡的支持。如果版本太老Projects目录下根本没有这个板子的名字白折腾。2.2 路径二TouchGFX Designer 的 Example 列表和 Board Farm第二条路是在 TouchGFX Designer 里直接生成。安装 TouchGFX Designer 后新建工程时有一个 Example 列表里面按 STM32 系列分类可以筛选出 STM32H7S78-DK 相关的演示工程。有些出厂 Demo 还会以“Board Farm”的方式提供连接板子之后可以一键生成。用这种方式拿源码的好处是你会拿到一份与本地安装的 TouchGFX Designer 版本严格匹配的工程避开了“代码是别人用老版本生成”的兼容性问题。TouchGFX Designer 会按照你本机的工具链配置自动调整生成代码。有一点要提醒并非所有出厂 Demo 都会出现在 Example 列表里。比如说有些针对特定面板做过的显示初始化代码或依赖特定硬件版本的演示未必适合直接给所有用户生成。这时候回到路径一去 Cube 固件包里找往往更靠谱。2.3 路径三GitHub 上的官方/社区仓库ST 近年把不少示例代码都放到了 GitHub搜索STM32H7S78-DK或者stm32h7s78-touchgfx可以看到官方仓库以及一些第三方维护的镜像。从社区仓库拿代码好处是能看到历史上对工程文件的修改记录某些 bug 修复过程会比官方固件包更透明。不过从 GitHub 拉工程要特别留意一点仓库里的代码往往不止对应一个工具链版本。你可能看到一个工程目录结构不错但拉下来之后发现它依赖的 HAL 版本和你本地 CubeMX 自动生成的完全不同打开 .ioc 时会提示缺少组件或版本不兼容。我的经验是在 GitHub 上找源码最好先看 README 或最近的 commit 信息确认它针对哪个固件包版本。否则后面编译报错时你根本分不清是代码问题还是版本问题。获取方式适合场景主要风险STM32CubeH7 固件包想要完整、稳定、可对比的工程包体积大版本过老可能没有板卡支持TouchGFX Designer 生成想直接拿到和本机工具链匹配的工程个别出厂演示不会出现在 Example 列表GitHub 搜索想看历史修改、找社区补丁版本匹配风险高需要仔细核对3. 在本地重建工程从 .ioc 到 TouchGFX Designer 再到 STM32CubeIDE3.1 先看清工程目录里谁管外设、谁管界面拿到源码后如果直接用 STM32CubeIDE 打开整个工程目录很可能会被一堆文件夹搞晕。TouchGFX 工程的目录结构看起来比普通 STM32 工程多了一层它的核心分工是这样的.ioc文件整个工程的硬件配置源头。打开它可以看到 STM32H7S78-DK 上所有引脚复用、时钟树、外设参数。CubeMX 就是靠它生成初始化代码。Core/目录由 STM32CubeMX 生成的处理器初始化代码里面包含main.c、stm32h7xx_it.c等。TouchGFX/目录由 TouchGFX Designer 生成和管理的 GUI 相关代码里面又分为generated自动生成不要手改和gui存放 Model、View、Presenter 等框架代码以及target平台相关移植代码。Drivers/和Middlewares/HAL 驱动库和 TouchGFX 运行时库。理解这个结构非常关键。很多新手遇到编译错误后第一反应是去改generated目录里的代码结果下次生成时改动全部被覆盖。正确的做法是先搞清楚报错落在哪个域里——是外设初始化的问题就去管 .ioc 和 Core是界面显示逻辑的问题就去管 TouchGFX/gui是平台适配的问题才去看 TouchGFX/target。3.2 用 CubeMX 打开 .ioc 并校准工具链拿到官方工程后我习惯先双击 .ioc 文件让 STM32CubeIDE 里的 CubeMX 把它打开。打开后先不要急着点 GENERATE检查几个关键配置工具链是否已经选为 STM32CubeIDE。如果 .ioc 是从别的工具链导出的这里可能出现空配置。项目名称和路径是否正确。官方工程默认路径是解压后的目录目录名如果带空格趁早改掉。是否有组件版本不满足提醒。常见的是 X-CUBE-TOUCHGFX 组件版本和当前工程所需版本不一致。CubeMX 的“Software Packs”管理面板里可以安装或者切换 X-CUBE-TOUCHGFX 的版本。这个组件就是 CubeMX 和 TouchGFX Designer 之间的桥梁。如果你打开 .ioc 时看到中间件区域有触发的“组件缺失”提示说明本机没有安装对应版本的 TouchGFX 软件包需要先在 CubeMX 的软件包管理器里补上。确认这些之后再点 GENERATE。CubeMX 会按 .ioc 配置重新生成 Core、Drivers 等部分。这一步会刷新掉之前由 CubeMX 生成的代码但不会动 TouchGFX 目录里的 GUI 内容。所以如果你的目标是阅读官方 Demo而不是重新配置硬件直接生成即可。3.3 交给 TouchGFX Designer 生成 GUI 代码CubeMX 生成完成后工程里已经有一套可用于编译的骨架了但真正的画面资源、字体资源、图片资源以及触摸交互逻辑还需要 TouchGFX Designer 来生成。在工程目录里找到TouchGFX/下后缀为.part的文件或者直接用 TouchGFX Designer 打开工程根目录下的.touchgfx工程文件。打开后你能看到官方 Demo 的完整界面结构每个 Screen 对应的 View、每个控件的位置和属性以及图片/字体资源列表。此时只需要点一下右上角的 Generate CodeTouchGFX Designer 就会按照当前配置重新生成TouchGFX/generated目录下的代码。如果你对 Demo 样式不满意也可以在这里先改一点东西再生成比如把转盘的图片换成自己的素材或者修改启动页的文案——这正是使用 TouchGFX 的核心工作流。需要留意的是TouchGFX Designer 的版本会影响生成代码的 API。官方 Demo 如果在设计时用了某个版本的新特性而你的 Designer 是旧版打开 .touchgfx 工程时可能直接提示不兼容甚至打不开。这时候最直接的办法是升级 TouchGFX Designer而不是硬去改工程配置文件。3.4 回到 CubeIDE 编译烧录首次点亮的几个关键点当 CubeMX 和 TouchGFX Designer 两边都完成代码生成后回到 STM32CubeIDE刷新工程执行一次完整构建。这里有几个第一次编译时容易出问题的点浮点 ABI 选项TouchGFX 通常启用 VFPv5 或 VFPv4 硬件浮点工程里的 FPU 选项如果被 CubeMX 重置成了软件浮点编译会报一堆寄存器相关错误。优化选项官方 Demo 为了展示流畅度一般使用-O2或更高优化。如果把优化级别调成-O0即使能编译通过触摸和动画的体验也会明显变差。错误告警等级某些 STM32CubeIDE 版本默认把警告当错误处理导致官方工程因为一两个 deprecated 接口直接编译失败。项目属性里可以单独调整。烧录方面STM32H7S78-DK 板载 ST-LINKUSB 线连上后CubeIDE 里可以直接识别。按下 RUN稍等一会儿屏幕亮起TouchGFX 出厂画面出现整个重建流程就算闭环了。4. 重建过程中最容易踩的坑版本、路径与工具链的连锁反应4.1 TouchGFX Designer 版本不够板子直接消失第一个坑出现在最开始。我一开始用的 TouchGFX Designer 是几年前的老版本打开 Example 列表后翻遍了 H7 系列都没看到 STM32H7S78-DK 这个名字。当时第一反应是“这块板子太新了老的 Designer 不支持”升级后问题立刻消失。所以如果你在 Example 列表里找不到对应板卡先不要怀疑官方资料缺失大概率是工具版本太旧。ST 的 TouchGFX 工具链更新速度很快越新的 MCU 越依赖新版 Designer 中的 Board 支持。类似的问题也体现在 CubeMX 的软件包安装上安装完新版 Designer 后记得重新启动让组件注册表刷新一次。4.2 STM32CubeH7 固件包版本和 HAL 层不匹配第二个坑更隐蔽。我在一个较旧的 STM32CubeH7 固件包中找到了 STM32H7S78-DK 的 Demonstrations 目录但打开 .ioc 编译的时候HAL 库报出一堆类似未定义宏、缺少函数原型的错误。核对之后发现工程里的 HAL 驱动目录被固件包覆盖成了旧版本而这个 Demo 工程依赖的新 HAL 接口在旧包里根本不存在。这说明 STM32CubeH7 固件包本身也在持续迭代板卡目录出现并不等于该版本的所有外设支持都是完整的。特别是 STM32H7S7 这种较新的系列某些图形相关外设如 MIPI DSI 控制器、Neochrom GPU 内部寄存器封装的 HAL 更新比较频繁。解决方法是去 ST 官网下载最新版固件包或者在 CubeMX 的软件包管理器里直接更新到最新版本确保 .ioc 引用的 HAL 和实际编译用的 HAL 是同一套。4.3 工程路径里的中文和空格比想象中坑第三个坑听起来像是老生常谈但在 TouchGFX 工程里它会被放大。TouchGFX 生成的资源文件包含大量绝对路径写入的元信息如果工程放在带中文或者空格的目录下生成环节可能不报错但编译时的链接过程会冒出奇怪的 “file not found”而且错误位置指向的源文件看起来完全正常。我当时的工程路径是D:\stm32\factory demo\Creator 和 Designer 都工作正常但编译时链接器就是找不到一个字体资源文件。花了不少时间把路径改成纯英文的D:\stm32\factory_demo\后一切恢复。这种问题排查起来非常恼火所以拿到官方源码的第一步先把路径规范化。4.4 编译通过但屏幕灰屏SDRAM 和显示控制器的初始化顺序这是我在第 3 章提到“编译通过”之后还会遇到的另一类麻烦编译完全正常烧录后串口打印也正常但屏幕只有背光亮画面一片灰。经过排查问题出在初始化顺序上。TouchGFX 的显示链路需要经过 SDRAM 初始化、MIPI DSI 面板初始化、显示控制器配置这几步而且严格的先后顺序是外部存储先就绪再启动显示链路。因为 TouchGFX 的帧缓冲画在 SDRAM 里显示控制器要不断从这个地址取数据如果 SDRAM 还没就绪就开始刷屏屏幕上自然没有有效内容。官方源码里这些初始化函数通常以固定顺序调用。但如果你在对工程做裁剪比如把某个外设初始化延迟到后面一定要保证 SDRAM 的初始化在显示控制器启动之前完成。这个坑不太好排查因为它不会立刻报错只会表现成“开机黑屏/灰屏”。现象可能原因解决思路Example 列表没有板卡Designer/CubeMX 版本过旧升级工具链并重启编译报 HAL 缺函数固件包版本和工程不匹配更新 STM32CubeH7 固件包链接阶段文件找不到路径含中文/空格工程复制到纯英文路径烧录后屏幕灰屏SDRAM 与显示控制器初始化顺序错优先初始化 SDRAM 再启显示链路4.5 不要试图从板子里的固件反推源码还有一个踩坑思路值得一提。当时我在官网找不到源码的时候一度想过用 STM32CubeProgrammer 把 MCU Flash 里的出厂固件读出来再反汇编去逆向工程。后来发现这个做法基本不可行原因有两个一是 ST 出厂固件普遍使能了读保护RDP Level 1正常连接调试器读不出内容二是即使把二进制 dump 出来反汇编得到的代码和 TouchGFX 生成的 C 源码完全不是一回事里面还有大量资源表、字体二进制数据从中还原工程结构毫无意义。相比之下老老实实找官方固件包里的 Demonstrations 工程效率高得多。5. 拿到源码后怎么读、怎么改成自己的项目5.1 读代码的先后顺序先搞清楚 Model、Presenter、View 的调用链TouchGFX 工程的代码组织方式和普通嵌入式 C 工程差别挺大。刚打开源码时很多人习惯先去看main.c然后顺着初始化逻辑往里翻。但 TouchGFX 运行时是在main.c里被启动的真正的业务逻辑却在TouchGFX/gui目录里。读这份 Demo 源码我的建议是先看TouchGFX/gui/include/gui/下面的目录结构。你会看到每个 Screen 都有三个关键类Model负责与后台逻辑通信比如读取传感器数据、更新状态它不直接操作界面。Presenter相当于 View 和 Model 之间的中间层键盘焦点、界面跳转逻辑都在这里。View直接管理界面控件处理触摸事件、刷新动画。官方 Demo 里转盘切换和卡片元素的交互逻辑基本都是 Model/Presenter/View 协作完成的。先顺着这个调用链走一遍比一开始就抠某个控件绘图代码要有用得多。5.2 把官方 Demo 改成自己 UI 项目的边界划分如果你想基于这份出厂 Demo 改成自己的产品界面强烈建议保留官方工程里Board相关代码和TouchGFX/target下的平台相关代码不变只替换TouchGFX/gui目录下的界面逻辑。这个边界划分能省掉大量移植工作。具体操作是在 TouchGFX Designer 里新建一个 Screen或者在现有 Screen 上删除不需要的控件然后添加自己的控件和逻辑。TouchGFX Designer 负责处理界面资源和行为绑定生成代码时会自动更新gui目录。这样硬件驱动、时钟配置、显示接口都沿用出厂 Demo你只需要关心自己的产品到底想展示什么。当然如果产品需求不是重绘一个全新 UI而是基于官方 Demo 的样子做微调那更简单直接在 Designer 里改图片素材、改文案即可。出厂 Demo 里很多特效控件和渲染思路本身就能直接复用。5.3 从 Demo 里抄性能优化手法Neochrom GPU 的典型用法这份出厂 DEMO 之所以流畅并不是因为代码写得特别玄妙而是很多关键性能点都用上了硬件加速。读源码时值得留意几个具体的优化点帧缓冲配置Demo 使用了一块完整的 SDRAM 区域作为帧缓冲部分区域还可能开启了双缓冲或者局部缓冲模式避免整屏刷新带来的带宽压力。图像缓存部分频繁使用的图片资源被预先转换成了适合 GPU 读取的格式省去了每次渲染时的像素格式转换开销。硬件加速渲染TouchGFX 在运行时会把绘制任务卸载给 Neochrom 或 DMA2D而不是靠 CPU 逐像素搬运。在源码里可以看到对图形加速器缓存状态的判断逻辑。这些优化策略并不是只能在 STM32H7S7 上使用我后来在做另一个基于 H7 系列的产品界面时也沿用了同样的思路优先用Cache、Buffer优先使用 GPU 加速的绘制 API避免在onDraw回调里做大量 CPU 侧绘图。如果只是想快速跑起来看效果按第 2、3 章的路径拿工程编译一次就够了但如果你想真正掌握 TouchGFX 在 H7S7 上的最佳实践我强烈建议花一个下午把 Demo 的 GUI 框架代码逐行过一遍尤其是 Model 层和 target 层的代码。很多细节性能调优手法都藏在里面。最后再分享一个小经验拿到源码之后最好把工程整个复制一份一份保持官方原样用于对照一份当作自己的工作副本。这样你在里面改坏了某个配置随时可以切回原版对比差异。我第一次重建之后就在工作副本里改了时钟配置结果整块板子死机了对着官方代码逐项对比才找到是哪一行动了手。这个习惯一直沿用到今天省下过不少时间。