简介：面向嵌入式 GUI 开发者的 ART-Pi 平台示例工程，基于 RT-Thread 生态，演示 TouchGFX 如何绕过默认图片资源包、直接从文件系统读取并显示图片，适合正在学习 TouchGFX 与 RT-Thread 集成、需要处理动态图片加载场景的开发者参考。压缩包共包含 3767 个文件，以 h/c/cpp 源文件为主体，辅以 sconscript 构建脚本、HTML 文档、PNG 图片素材以及预编译链接库，涵盖工程构建、运行与调试所需的完整目录结构，同时保留 md、txt 等说明文档，整体体积约 87.79MB。Demo 将图片显示流程与文件系统读取逻辑分离，读者可借此掌握文件系统加载位图、图片资源管理、显示刷新等关键环节；通过阅读源码还能理解 TouchGFX 在 ART-Pi 硬件上的工程组织方式与静态库依赖关系。资源已有 683 人学习下载，特别适合具有一定 RT-Thread 基础、希望进阶图形界面开发的嵌入式开发者作为实战参考。 最近翻备份盘的时候，又看到了这个art_pi_touchgfx.zip，去年在 Art-Pi 开发板上跑 TouchGFX 图形库时留下的完整示例工程。当时这套东西帮我省了不少事，直接把 TouchGFX 和 RT-Thread 的融合流程跑通了。如果你也在折腾 Art-Pi 或者手里有 STM32H750 这类高性能 MCU，想做一个带屏幕的图形界面项目，这个 zip 其实是很好的起跑线。
把它解压开，里面是一套可以直接编译运行的可视化界面样例，覆盖了文本显示、进度条、图片资源、交互事件这些常用元素。要说它能解决的问题，就是“TouchGFX 到底怎么和 RT-Thread 配合，怎么在 Art-Pi 上点亮屏幕并跑起来”。对刚接触 TouchGFX 的人，或者说对只会用裸机跑 ST 官方例程的朋友，这份工程能帮你少走不少弯路。下面我把这套工程的拆解、环境准备、实际操作、还有最近大家问得比较多的字体图标问题，一次性讲清楚。
1. 拆包先看本质：art_pi_touchgfx.zip 里到底封装了什么
1.1 为什么是 Art-Pi 配 TouchGFX 这套组合
Art-Pi 是 RT-Thread 官方推出的一颗开发板，主控是 STM32H750VBT6。这颗芯片主频能跑到 480MHz，内置 1MB 用户 Flash（注意这里有个历史梗，后面会细说）加上 1MB RAM，外扩了 SDRAM 和 QSPI Flash，板载 RGB 屏幕接口、音频、以太网、WiFi，几乎是把“能跑 GUI”的硬件条件一次性配齐了。尤其它保留了完整的 RGB LCD 并口，这让 TouchGFX 这类基于 LTDC + DMA2D 的图形框架有了用武之地。
TouchGFX 是意法半导体官方维护的 GUI 框架，主推对象就是 STM32 系芯片。它和普通轻量级图形库最大的区别在于，它有一套 PC 端可视化设计工具 TouchGFX Designer，UI 画好后一键生成 C++ 代码，界面上的控件、交互逻辑、动画效果都能直接被 MCU 编译执行。配合 H750 的 Cortex-M7 内核和硬件 2D 加速器 DMA2D，几百帧的刷新率在低分辨率 RGB 屏上是能看到的。相比在裸机上直接操作像素，TouchGFX 把界面开发的抽象层级提高了不少，上手曲线也友好很多。
1.2 解压后看目录，工程结构怎么理解
zip 解压以后，目录结构并不复杂，但我第一次打开时还是有点懵，因为它比普通 STM32 工程多了不少 TouchGFX 相关文件夹。核心部分大概是这样：
TouchGFX目录：这是整个工程的图形核心，里面包括generated（由 Designer 自动生成的代码，不能手改）、gui（你的界面逻辑、自定义控件代码）、target（驱动层适配，包括 LTDC、DMA2D、帧缓冲配置）。Applications或app目录：RT-Thread 的应用代码入口，比如创建 GUI 线程、初始化外设的地方。board/drivers目录：板级驱动，SDRAM、LCD 背光、触摸芯片等外设的初始化。rt-thread目录：RT-Thread 内核源码。
如果你以前玩过 ST 官方的 TouchGFX 例程，会发现在 Art-Pi 这份工程里，系统调度由 RT-Thread 接管，TouchGFX 只是其中一个线程。这种结构的好处是，你可以同时在工程里跑网络协议栈、文件系统、传感器采集，完全不用担心 GUI 把 CPU 占死。这个 zip 的定位更像一个“工程模板”而不是跑完就算的 demo，后续改 UI、加功能都很顺手。
2. 环境准备：版本搭配与工具链选择
2.1 TouchGFX 版本怎么选
TouchGFX 的版本迭代很快，从 4.10 到 4.21，几乎每半年一版。不同版本生成的代码结构有些差异，如果用了旧版 Designer 打开新工程，经常会报“版本过新无法打开”。我实测下来，4.18 到 4.21 这几个版本生成的工程结构相对稳定，对 H7 系列的支持也很成熟。
这里给一个保守的搭配：TouchGFX Designer 4.21 + STM32CubeMX 6.x + RT-Thread Studio 2.x。如果你手里的工程是用 4.18 生成的，升级 Designer 时它会提示迁移，一般直接确认就行，但迁移后最好重新生成一次代码，避免工程文件残留旧路径。
注意：TouchGFX Designer 会附带一个模拟器，可以在 PC 上直接跑你的 UI 工程。这个功能非常实用，强烈建议先把 UI 在模拟器上调好，再烧到板子上，能节省 70% 的调试时间。
2.2 三条跑通工程的路线
这里我整理了我试过的几种常见玩法，按推荐程度排列：
- Designer 打开 zip 里的 TouchGFX 工程 → 修改 UI → 点击 Generate Code → 回到 RT-Thread Studio / Keil 编译下载。这是最顺的一条路，也是官方示例工程的标准工作流。
- 用 STM32CubeMX 生成底层初始化代码，手动把 TouchGFX 代码嵌入 RT-Thread 工程。适合不想用现成模板、需要自己定制驱动的人，但工作量大，不建议新手一开始就走这条路。
- 完全不用 IDE，用 CMake + GCC 命令行编译。适合对构建系统非常熟悉的老手，能看懂
SConscript和linker script的话，也可以玩得很溜。
我自己的建议是，新手先走路线 1，把art_pi_touchgfx.zip当成“黑盒”跑通，再去研究里面每一层是怎么连接的。等熟悉了，再尝试把 TouchGFX 移植到自己的板子上。
3. 核心环节实操：从 UI 草稿到板卡亮屏
3.1 Designer 里搭一个可用页面的完整流程
打开 TouchGFX Designer，导入工程后你会看到一个空白的 Screen。我做的第一个界面是“时间显示 + 温湿度 + 按钮”，大致流程如下。
第一步，从右侧控件面板拖一个Text控件到画布中间，配置它的Typographic（字体样式）。TouchGFX 默认自带一些字体，但显示中文需要额外导入字体文件，记得准备一个 GBK 或 UTF-8 的 TTF 字体。
第二步，拖一个Toggle Button，用于切换背景颜色。选中控件后在右侧Interactions里添加点击事件，可以直接选择“点击后调用回调函数”，或者用现有的交互模板，比如Screen Transition这种。
第三步，如果你需要显示动态数据，比如时间变化，可以用Wildcard Text。设置文本内容时填<value>，然后在代码里调用text.setValue()方法更新内容。这一步是 GUI 和业务逻辑解耦的关键，不要在控件回调里写死业务。
注意：Designer 里任何保存操作都会触发代码生成，生成的代码在
TouchGFX/generated目录下。所有手工修改只建议放在TouchGFX/gui目录，generated里的代码会在下次生成时被覆盖，千万别手改。
3.2 与 RT-Thread 系统代码的衔接
工程跑起来以后，TouchGFX 实际上被封装成了一个线程。你可以通过 RT-Thread 的INIT_APP_EXPORT宏把 GUI 初始化放到系统启动阶段，然后在main里创建touchgfx_thread_entry。这里提几个关键配置点。
帧缓冲地址必须配置正确。在TouchGFX/target目录的TouchGFXHAL.cpp里，会看到类似下面的代码：
#define LCD_FB_START_ADDRESS 0xC0000000 // SDRAM 地址如果你的板子外扩了 SDRAM，帧缓冲一般放在 SDRAM 里，地址需要跟链接脚本中的分区对齐。Art-Pi 上 SDRAM 基地址是 0xC0000000，默认是够用的。如果出现花屏，第一反应就是查这个地址和 LCD 控制器的配置。
另外一个容易坑的点是 LTDC 时钟。TouchGFX 在初始化时会调用HAL::configureDisplay，但实际上 LTDC 的 PLL 频率、像素时钟分频都来自 CubeMX 生成的MX_LTDC_Init。如果刷新率不对、画面闪烁，优先查这两处的时钟配置是否与屏幕手册一致。
4. 这次的热词：TouchGFX 到底能不能用字体图标
4.1 先把结论放这儿
热搜词里有“touchgfx 可以使用字体图标吗”，我直接给结论：完全可以，而且这是 TouchGFX 官方支持的标准用法。TouchGFX 的字体引擎可以加载任意 TTF 字体文件，并把其中的字形作为字体资源编译进工程。常见的字体图标库，比如 FontAwesome，本质上就是一个特殊编码的 TTF 字体，里面的“图形”全部映射到 Unicode 私有区段。你要做的，就是把这个 TTF 导进 TouchGFX Designer，然后像用普通文字一样去显示图标。
这比把图标导成 PNG 图片再放上去要优雅得多。字体图标是矢量的，缩放不糊，颜色可以通过文本颜色属性调整，内存占用也小。
4.2 实操：把图标字体塞进 TouchGFX
我以 FontAwesome Free 为例，详细说说操作过程。
第一步，下载字体文件。FontAwesome 的官方 TTF 在它的 GitHub 仓库里可以找到，文件名类似fa-solid-900.ttf。下载后放到一个你能找到的目录，可以顺便放到工程assets/fonts里。
第二步，在 TouchGFX Designer 里新增字体。进入Texts → Typographies，点加号新建一个 Typography，选择字体文件为刚才的 TTF，设置字号（比如 20px），样式选 Regular 即可。
第三步，这是最关键的一步——字符集设置。TouchGFX 默认不会把整个 TTF 的所有字形都编译进去，它只收集你在界面文本中实际用到的字符。如果你只是“想看看效果”，直接在 Text 控件里粘贴一个 FontAwesome 图标（比如 iOS 上能正常显示的那个图标字符），Designer 会自动收录。但如果你要在代码里拼接图标或需要动态显示，建议在 Typography 设置里指定Unicode Range，以 FontAwesome 为例，很多常用图标集中在U+F000到U+F2E0这个区间。
第四步，在 Text 控件中输入图标字符。编辑文本时，直接拷贝字体文件里的 icon 字符，或者用 Windows 字符映射表找到对应字符粘贴进去。设计器上会立刻显示预览。
第五步，生成代码并编译。生成的编译产物里包含一个Font_xxx.cpp文件，里面是字形数据表。程序里把这个字体赋给某个 Text 控件，运行后就能显示图标了。
注意：如果把图标字体和普通中文字体混用，同一个 Text 控件里可能只能指定一种 Typography，要显示图标和文字并存，可以拆成两个控件重叠放置，或者用混合文本功能（Mixed Text）。
4.3 字体图标方案有哪些优势，又有什么坑
字体图标的优势很直观，首先是体积，一个 PNG 图标 32x32 的压缩后大约 1~2KB，而 FontAwesome 的几百个图标编译进工程后可能也就增加了十几 KB 到几十 KB。其次是灵活性，颜色、透明度、字号都能随时改，不用重新做图。再者就是遍历动画，比如旋转、缩放，对字体图标来说就是普通的文本变换，实现起来非常简单。
但坑也有。第一个坑就是字符集，如果你在代码里动态设置一个“Designer 生成时没收录”的字符，屏幕上就会显示方框。解决方法是把需要用到的字符范围提前写进 Typography 设置，或者干脆把整个字体文件的字形区段都勾上（这样体积会明显增加）。第二个坑是字体版权，FontAwesome 免费版有版权约束，商业项目里要注意授权；可以用开源的 Material Icons、Remix Icon 等替代。第三个坑是抗锯齿，小字号下图标边缘容易发虚，一般建议字号不小于 14px，必要时开启 LCD 渲染的高级抗锯齿选项。
5. 翻车记录：常见问题与排查思路
5.1 编译报错 region 'FLASH' overflowed
这是 H750 玩家最常见的问题。H750 虽然官方标称有 1MB Flash，但很多型号实际出厂只烧了 1MB 用户区，严格说可用 Flash 为 1MB。如果只是写个小 demo 还好，一旦 UI 资源多、图片多、字体多，很容易爆 Flash。
排查和解决路径大致有三条：
- 开启编译优化。在 Keil 里把
-O0换成-O1或-O2，代码体积能缩小很多。 - 图片资源压缩。TouchGFX 支持将 PNG/JPG 在 PC 端压缩成可直接渲染的格式，尽量使用 4bit 或 8bit 色深，不要一上来就 ARGB8888。
- 字体子集化。动态字符范围设置得好，字体资源能缩小很多。
5.2 白屏和花屏
白屏通常是 LTDC 初始化失败或背光没打开；花屏则多半是帧缓冲地址不对、时钟频率偏差、或者 SDRAM 初始化失败。排查顺序我建议这样：
- 用逻辑分析仪或示波器查 LCD 的
HSYNC、VSYNC信号，确认 LTDC 在输出。 - 查背光引脚电平，Art-Pi 的背光由 GPIO 控制，初始化代码里写
HAL_GPIO_WritePin(LCD_BL_GPIO_Port, LCD_BL_Pin, GPIO_PIN_SET)。 - 查 SDRAM 自检，在触摸任何 UI 代码之前单独跑一个 SDRAM 读写测试，确认帧缓冲区域没问题。
在实际项目中，我遇到过最隐蔽的问题是在MPU配置里，帧缓冲区域被设成了不可缓存，导致 DMA2D 和 CPU 访问不一致，表现为画面有时花有时不花。解决方法是把0xC0000000对应的 MPU 区域配置成Device Memory或关闭 Cache 试试。
5.3 触摸屏没反应或坐标不准
Art-Pi 用的是电容触摸屏，一般是 I2C 接口。RT-Thread 里的驱动通常会把触摸设备注册成touch设备，然后在 app 里读取坐标并上报给 TouchGFX。如果屏幕亮了但点击没反应，先查驱动加载日志。
常见问题有两个。一是 I2C 引脚复用错误，需要对照 Art-Pi 原理图确认 SCL/SDA。二是坐标映射方向不对，TouchGFX 里setTouchCoordinate的 x、y 可能和屏幕面板的物理方向不匹配，旋转屏幕后需要做坐标变换。可以先在touchgfx::HAL::touchEvent里打印原始坐标，然后根据屏幕方向做一次线性映射。
5.4 字体图标显示成方框
这个问题在字体图标使用中排第一。根据我的排查经验，按下面顺序检查：
- 确认 Text 控件使用的 Typography 是不是正确的字体图标字体。
- 确认该字符已被 TouchGFX 收录。生成工程后，在
generated/fonts/src目录下查看对应的Font_xxx.cpp，看里面是否包含该 Unicode 编码。 - 确认程序里没有动态修改字体或走了其他字体渲染路径。
- 在 Designer 里直接输入该字符，看模拟器是否正常显示；模拟器正常但板子上不行，说明是资源没同步完整，重新生成并 Clean 后编译。
6. 基于这套工程，后面还能这么玩
我之前在这个art_pi_touchgfx.zip工程基础上做过一个小型仪表界面，用到了滑动菜单、圆环进度条、摄像头图像显示（通过 DMA2D 搬运数据），整体体验还挺稳的。如果你准备深挖，可以试着做几件延伸的事：在 Gui 层引入 MVP 模式，把界面和逻辑彻底分离；把屏保动画做成自定义控件，继承Container然后重写handleTickEvent；或者通过 TouchGFX 的TextArea配合中文字体库，把富文本显示也接进来。
最后分享一个我个人总结的经验：拿到这类 zip 模板，先别急着改 UI，第一件事是原样编译、烧录、确认屏幕能亮，然后在 Designer 里加一个按钮、一个文本、一个交互，全部跑通后，再去动复杂的东西。这样后面踩坑时，你能快速判断问题出在驱动层还是 GUI 层。另外，generated目录千万别手改，这是我在这个项目里花过最冤枉的一晚上得到的教训。
本文还有配套的精品资源，点击获取
求解三维声波方程的MATLAB实战指南)
