简介：面向STM32H743IIT6嵌入式开发者的TouchGFX综合例程，基于480×272分辨率官方Demo构建，适合需要快速掌握Cortex-M7平台图形界面开发的工程师与学生，也适合作为高校嵌入式课程的进阶参考资料。资源共1133个文件，以334个cpp源码、262个hpp与171个h头文件为主体，配合png素材、静态库、链接脚本与工程配置，完整覆盖编译链接依赖，压缩包约60.23MB。已有46人学习/下载。例程重点展示TouchGFX在STM32H743上的初始化流程、图形绘制、触摸输入处理、动画切换与内存管理，帮助开发者理解从底层驱动到上层UI的协作方式。通过实际运行与修改源码，还能学习到工程结构划分、多任务事件驱动及性能优化思路，为后续复杂人机交互产品提供可直接复用的参考架构。工程包含完整的构建配置与可执行产出，便于直接导入IDE验证实际效果，并针对具体场景调整图形资源与交互逻辑，缩短项目前期预研时间。
1. 打开 STM32H743IIT6 的 TouchGFX 480x272 综合 Demo 前，先想清楚这三件事
如果你拿到一包名为“STM32H743IIT6单片机TouchGFX例程-基于480x272分辨官方例程-综合Demo.zip”的压缩包，第一反应多半是解压、编译、下载、看屏亮。这个流程能跑通，但更值钱的是搞清楚它背后的链路：STM32H743IIT6 作为一颗 Cortex-M7 内核、带 LTDC 控制器和 1MB RAM 的单片机，为什么成为 TouchGFX 高分辨率界面开发的常见选型；480x272 这个分辨率在 RGB 屏驱动中的帧缓冲开销怎么算；综合 Demo 里的多页面跳转、动画和控件事件如何被 TouchGFX 的 MVP 框架组织起来。这篇文章既不替作者背书，也不重复官方文档，只讲我从解压这个例程到把它改成自己产品的完整路径，以及这条路上的参数、命令和坑。
2. 为什么是 H743IIT6 + 480x272：先算清楚显示链路这笔账
2.1 从 LTDC 到帧缓冲：这颗芯片的显示资源到底够不够
STM32H743IIT6 的显示能力来自片上 LTDC（LCD-TFT Display Controller），它可以直接驱动 RGB 接口的 TFT 屏，不需要额外的 SSD1963 之类的控制器芯片。480x272 的 4.3 寸屏是 RGB 屏里最常见的规格之一，而 LTDC 正好支持这个时序范围。算一笔账：480x272 的单帧像素点约 13 万，如果用 RGB565（每像素 2 字节），一帧图像要 261KB；如果是 ARGB8888（每像素 4 字节），则要 522KB。H743IIT6 有 1MB 的连续 RAM，其中 DTCM 只能给内核用，不能被 LTDC 和 DMA2D 访问，所以帧缓冲要放到 AXI SRAM（D1 domain）里。在 AXI SRAM 划分出双缓冲，也就是两份 261KB 的帧缓冲，占 522KB，剩余空间还能放显示列表、字体缓存和局部图像缓存。这个账算下来，480x272 配 RGB565 双缓冲是这颗芯片最稳妥的组合。这也是为什么很多官方参考设计选这个分辨率——它让 TouchGFX 在不开外部 SDRAM 的情况下也能稳定跑到 60fps 的刷新率。
2.2 480x272 RGB 屏的硬件引脚：除了数据线，别忘了背光和触摸
拿到例程先看硬件连接定义，常见做法是把 LTDC 的 RGB888 数据线、时钟、行场同步、数据使能接到屏幕的对应引脚，同时留一个 PWM 脚控制背光。H743IIT6 的 LTDC 引脚是固定的几组，比如 LTDC_R0 在 PH3、LTDC_G0 在 PJ11、LTDC_B0 在 PJ12 这类走线，设计 PCB 时基本是照着芯片手册的 AF 功能表布线，例程的 GPIO 初始化代码也是这套映射。需要特别注意的是背光引脚：如果例程里把背光接到某个普通 GPIO，上电时序必须是先初始化 LTDC 和帧缓冲，再点亮背光，否则会出现一帧花屏闪白。触摸部分常见的是电容触摸屏接 I2C，比如 GT911 或 FT5x06，复位脚和中断脚要预留，并且触摸 I2C 的初始化必须发生在 TouchGFX 触摸驱动挂载之前。这块追根溯源你会看到例程的 app_touchgfx 层里会做一个带延时的触摸 IC 探测流程，原因就在这。
2.3 最小软件配置：CubeMX 里必须勾选的中间件和存储区域
用 STM32CubeMX 打开例程的 .ioc 文件时，你会看到几个不是默认开启的配置项。首先是 TouchGFX 中间件，它要求使能 LTDC、使能 DMA2D、使能 CRC，并且要选对帧缓冲所在的存储区；其次是 FreeRTOS，TouchGFX 在 H7 上默认跑两个任务：一个叫 TouchGFX_Task，负责渲染和事件处理，一个叫 Main_Task 或默认的默认任务，负责业务逻辑。CubeMX 的 RAM 分配里，系统默认会把 DTCM 留给内核栈和堆，把 AXI SRAM 分区成几个用途段，TouchGFX 的帧缓冲和各 Buffer 都在 D1 域里配置。另一个容易漏的是时钟树：LTDC 的像素时钟来自 PLL3Q，480x272 的 4.3 寸屏典型像素时钟是 9~10MHz，有些屏要求 14.4MHz 也有，具体看屏的 datasheet。在 Clock Configuration 页面里要把 PLL3 的分频配到屏的典型值范围，配太高屏幕会闪或者直接不亮。
如果例程的 CubeMX 版本和你本机不同，打开 .ioc 时会提示版本迁移。这种迁移不是百分百安全，我之前遇到过一次从 CubeMX 6.8 到 6.10 的迁移，TouchGFX 的版本从 4.21 跳到 4.23，生成的代码接口变了，导致 build 直接报错。处理办法是先不升级，装回原版本；或者接受迁移后，打开 TouchGFX Designer 让工程重新生成一遍代码。所以动手之前先确认这三个软件的版本：CubeMX、TouchGFX Designer、Keil MDK 或 IAR。这个确认动作看起来无关紧要，但在后续排除“莫名其妙的编译错误”时，能帮你省掉整整一个下午。
3. 把综合 Demo 跑起来：解压、编译、下载、亮屏全流程
3.1 解压后的目录结构：哪些文件是生成的，哪些别乱动
我第一次拿到这类例程时，习惯是把整个 zip 解压到纯英文路径下，比如 D:\demo\H743_TouchGFX_480x272，因为 Keil 和 TouchGFX Designer 对中文路径的兼容性都一般。解压后你会看到类似这样的布局：根目录有 .ioc 工程文件、.touchgfx.part 文件（TouchGFX Designer 的工程描述文件）、若干 PDF 或 README 文档，然后是 Core、Drivers、TouchGFX、Middlewares 这几个标准目录。Core 里是 main.c、gpio.c、ltdc.c 这些 CubeMX 生成的初始化代码；Drivers 是 HAL 库；TouchGFX 里有两个子目录，Generated 和 target，Generated 是 TouchGFX Designer 每次生成代码时重写的部分，target 是用户自己写的平台适配代码，比如 stm32h7 的 LCD 接口和触摸驱动。注意：TouchGFX 目录下的 Generated 别手工改，改了也会在下次生成时被覆盖。要改业务逻辑，改的是 src 目录下的 View、Presenter 和 Model。
3.2 Keil MDK 编译与下载：先选对 Target，再配 Flash 下载算法
用 Keil 打开工程后，第一步不是直接编译，而是检查 Target 选项里的芯片型号是否锁定到 STM32H743IIT6，以及 Flash 下载算法里有没有选 STM32H7x 的 2MB Flash 算法。这个例程一般会自带下载算法配置，但如果 Keil 版本不同，下载算法经常丢失，表现为点 Load 后报错 “No Algorithm found” 或者 “Flash Download failed”。处理方式是打开 Options for Target -> Debug -> Settings -> Flash Download，把 Programming Algorithm 改成 STM32H7 系列对应的 2MB 算法，勾选 Erase Full Chip 或 Erase Sectors 都行。编译时注意优化等级，TouchGFX 生成的代码量不小，Debug 模式经常超过 Hex 文件大小限制，建议至少用 -O2 或 -O3。命令行编译的方式也可以：Keil 安装目录下有 UV4.exe，配合 -b 参数能做命令行构建，例如：
UV4.exe -b project.uvprojx -o build_log.txt这条命令适合写进 CI 脚本或批量验证多个例程工程。构建日志里出现 0 Error(s) 之后，再接 ST-Link 下载。下载时如果调试器不是 ST-Link 而是其他第三方工具，Keil 的 Flash 下载设置里要切换调试器类型。整个下载过程不出问题的话，也就是十几秒的事。
3.3 上电后怎么确认 Demo 真的跑起来了：至少要看到这三种交互
按下载键后屏幕亮起，第一眼看到的是类似仪表盘或菜单的界面。综合 Demo 这个词意味着它不止一个页面，通常会有一段自动播放的动画，比如指针旋转、波形移动或者图片切换。验证链路正常与否，我一般看三点：一是滑动页面时有没有残影，有残影说明帧缓冲配置或 LCD 刷新频率有问题；二是点击按钮时有没有跳转动画，如果点击无反应但画面在动，问题大概率出在触摸坐标映射或触摸 I2C 时序；三是看帧率稳不稳，去掉屏幕贴膜后快速滑动，看是否掉帧。如果界面完全不动但屏幕有背光，先用示波器或逻辑分析仪看 LTDC 的 VSYNC/HSYNC 信号是否正常，再看背光 GPIO 是否被拉高，这两个信号决定屏幕是“黑屏”还是“亮但没内容”。
如果你手头没有 ST-Link，而是想用串口通过 STM32CubeProgrammer 下载，需要注意：H743 的 BOOT0 引脚默认从 Flash 启动，串口下载需要把 BOOT0 拉高到 1，进入系统存储器引导，然后用 STM32CubeProgrammer 的 UART 模式连接，选择固件包里的 .elf 或 .hex 文件下载，下载完再拉低 BOOT0 并复位。这个流程能跑通，但注意串口下载速度远慢于 SWD，1MB 左右的固件要等几分钟，而且下载过程中不能断开串口，否则 Flash 验校失败，得从头再来。
4. 把综合 Demo 的工程骨架拆开：MVP 架构和多 Screen 跳转
4.1 TouchGFX 为什么强制用 Model-View-Presenter
TouchGFX 的工程组织方式不是裸奔的 main loop，而是完整的 MVP 架构。Model 负责数据和业务状态；View 负责界面显示，接收用户输入并渲染；Presenter 是 Model 和 View 之间的粘合层，处理界面事件到业务逻辑的转发。这个结构对应到目录里就是：Model.hpp/Model.cpp、View 目录下每个页面一套 View 和 Presenter，比如 MainView.cpp、MainPresenter.cpp。当你在 TouchGFX Designer 里添加一个新 Screen，会自动生成四件套：ScreenView、ScreenPresenter、以及 Screen 的关联项注册到 MVP 容器里。综合 Demo 里有多个 Screen，切换时实际发生的是 View 的替换和 Presenter 的挂载卸载。
看例程代码时你会发现一个规律：View 里不直接处理业务数据，而是通过 presenter->someFunction() 把事件往上抛。这种分层让多人协作和后续换 Model 层变得干净，但也让新手困扰，因为想找一个按钮点击后的逻辑，要顺着 View 的 callback 跳到 Presenter 再看 Model。我的经验是第一周先别改业务逻辑，只追一遍这五类文件：View.cpp 里的 handleTick、handleClickEvent、setupScreen、tearDownScreen，以及 Presenter 里的各种 action 转发。追完一遍，整个 Demo 的界面流就清楚了。
4.2 一个 Screen 从生成到渲染：代码执行的先后顺序
以综合 Demo 里的主屏为例，从触摸到看到动画，代码执行路径大致是这样：
// MainView.cpp 的关键回调示例 void MainView::handleClickEvent(const ClickEvent& event) { // 先判断点击区域是否命中某个控件，TouchGFX 会按 z-order 遍历 if (event.getType() == ClickEvent::RELEASED) { // 命中按钮后，通过 presenter 层把事件转成业务动作 presenter->onButtonPressed(); } } // MainPresenter.cpp 把 View 的动作转发给 Model void MainPresenter::onButtonPressed() { model->requestScreenChange(); }这段代码里没有直接调用屏幕切换函数，真实动作发生在 Model 层收到 requestScreenChange 之后，通过 Application::getInstance()->gotoScreen 或类似机制执行视图切换。TouchGFX 的渲染循环在后台持续调用 View 的 handleTick，每 tick 代表一帧。动画对象比如 MoveAnimation 或 ImageAnimation，就是在这个循环里被推进的。理解这个顺序对排查很有用：如果你发现按钮按下但界面没反应，先在 handleClickEvent 里打断点，如果断点不进来，说明点击事件被拦截或触摸数据没到 TouchGFX 事件队列；如果断点进来了但跳转没发生，说明 Presenter 或 Model 层逻辑断了。
4.3 帧缓冲和局部刷新：为什么这么快又为什么偶尔抽风
TouchGFX 在 H7 上默认启用局部刷新机制，意思是只有变化区域的像素被重绘，而不是整屏刷新。480x272 的整屏 RGB565 刷新一次大约 261KB 数据，如果每帧都全刷，LTDC 的带宽会明显吃紧。局部刷新配合 DMA2D 的字库和图片加速，才能让界面常用操作维持在 60fps。但局部刷新也带来一个经典坑：如果界面上某个控件的外部输入变化频率过快，比如传感器数值每秒更新 30 次，而刷新循环跟不上，你会看到画面撕裂或闪烁。解决办法是把这个控件标记为setInvalid()强制重绘，或降低数据推送频率。综合 Demo 的动画设计通常不会触发这个问题，但新手改代码时容易在某个回调里高频刷新整个 View，这时候帧率会从 60 掉到 20 甚至更低，看起来就是“界面卡成 PPT”。
触摸驱动的数据流也要和渲染循环配合。H743 的触摸中断一般是 EXTI 或 I2C 轮询，TouchGFX 在每次 tick 里会调用触摸驱动读取坐标。如果触摸数据到达的频率远高于渲染频率，会产生事件堆积，点击响应滞后。常见做法是在底层做触摸数据滤波和去抖，再提交给 TouchGFX 的事件队列。
5. 跑这个例程最常碰到的 5 个坑：现象、原因与处理办法
5.1 编译报错：找不到 touchgfx 头文件或链接时一堆 undefined reference
现象：Keil 编译时提示 fatal error: touchgfx/Application.hpp: No such file or directory，或者最后链接时出现几十个 undefined symbol。
原因：这类例程通常依赖 TouchGFX Designer 先执行一次代码生成。如果你解压后直接用 Keil 编译，而 TouchGFX/Generated 目录里的源码不是完整的，就会缺头文件。另一个常见原因是工程路径含中文或空格，TouchGFX 的代码生成器对路径敏感。
处理：先在 TouchGFX Designer 里打开 .touchgfx.part 或 .touchgfx 文件，执行一次 Generate Code，然后重新编译；同时把整个工程目录移动到纯英文路径下再试。如果链接时报缺touchgfx_*相关的符号，检查是否在 Keil 工程里漏掉了 TouchGFX 库文件，比如 touchgfx.lib 或生成的 .cpp 文件被排除在编译目标之外。
5.2 上电白屏或花屏：多半不是屏坏了，而是 LTDC 时序和帧缓冲地址的问题
现象：屏幕亮但不显示内容，呈现纯白或随机彩色噪点；或者在一段花屏后突然正常，再卡住。
原因：LTDC 的像素时钟和屏的 datasheet 不一致。480x272 屏需要的像素时钟范围通常在 8~15MHz，配错会导致屏幕无法锁定同步。另一种情况是帧缓冲地址没有落在 AXI SRAM 域，LTDC 无法从这个地址取数据，就会显示空白或抓取到内存里的垃圾数据。
处理：先用示波器量 LTDC_PCLK 引脚的实际频率，对照屏幕规格调整 PLL3Q 分频；然后用 STM32CubeProgrammer 的 Memory Viewer 读帧缓冲地址，确认内容是否在更新。帧缓冲地址一般由 TouchGFX 自动分配，但如果你在 main.c 里手动改过内存布局，就要重新检查 LINK 脚本里对FrameBuffer段的划分。还有一个隐蔽原因：LTDC 的层配置里，LTDC_Layer_InitStruct.FBStartAdress如果写成 0，而运行时没有使用宏定义的地址，会出现屏幕闪烁一下然后白屏。
5.3 触摸没反应或点击位置错乱
现象：界面动画正常，但手指点击按钮无响应，或者点左边按钮右边触发。
原因：综合 Demo 的触摸驱动通常按 480x272 横向布局校准。如果你换过屏或者触摸面板的安装方向不同，坐标映射会偏移。电容触摸屏和电阻屏的坐标方向可能不同。另一个常见问题是触摸 IC 的初始化耗时较长，而 TouchGFX 在系统启动过程中就开始读坐标，导致前几秒触摸无效。
处理：先确认触摸 IC 的中断引脚和 I2C 地址和例程一致，用 I2C 扫描工具验证触摸设备在总线上可发现。然后在触摸驱动的探测函数里增加 50ms~100ms 的延时，等待触摸 IC 自检完成。坐标映射问题在 TouchGFX 的 HAL 层setTouchSampleRate或触摸驱动里做 X/Y 交换，也可以在 Designer 里直接改 Screen 的 orientation，但要注意这个改动会影响整个 UI 的布局方向，实际操作中我更习惯在底层把触摸坐标先转换成标准方向再交给 TouchGFX。
5.4 频繁点“Generate Code”后，自己的改动突然消失了
现象：在 TouchGFX Designer 里改了一点界面布局，生成代码后，某个自己写的回调函数不见了，编译直接报错。
原因：TouchGFX Designer 生成的代码分两类：一类是每次生成都会被覆盖的 Generated 目录；一类是你手动添加的 user code 区域，它们被放在特定标记注释之间。如果你把自定义代码写在了 Generated 目录下的文件里，或者写在 View 的#ifndef USERCODE标记外面，一次重新生成就会把它冲掉。
处理：自定义代码一律放在 TouchGFX Designer 预留的 UserCode 段内，通常是在.touchgfx工程的 View 文件里有明确的// User Code Begin和// User Code End注释块，把逻辑写在这两个标记之间。如果你需要加新文件，不要放在 Generated 目录，而是新建到 src 目录，再手动加入 Keil 工程的编译组。这个习惯能让你在改 UI 和改代码之间自如切换，不用每次重新生成前备份半个项目文件。
5.5 帧率上不去 60fps：关于优化等级和图片格式的两个低级错误
现象：滑动页面时明显卡顿，感觉不到“跟手”，或者动画掉帧。
原因：最常见的是 Keil 编译优化等级选的 Debug 模式，默认 -O0，TouchGFX 的渲染代码在 -O0 下性能下降非常明显。另一个原因是界面里的图片资源用了 ARGB8888 格式，比如按钮背景图是三通道透明 PNG 转出来的，这种格式在内存中体积大，DMA2D 加速效率低。
处理：把 Keil 工程切到 Release 模式或手动把优化等级改成 -O2/-O3，再观察帧率。图片资源尽量在 TouchGFX Designer 里用 L8 调色板或 RGB565，不使用透明通道的图不要用 ARGB8888。如果这两步做完还卡，就看一下有没有在绘制循环里做了高频率的浮点运算，H743 虽然带 FPU，但大体积四边形变换如果交给软件计算，60fps 还是会崩。此时把绘制类操作改为 TouchGFX 的setUpdateAction或moveTo这类内建动画，而不是自己刷新坐标。
6. 从例程到自己的第一块界面：先学会用这三个技巧
第一个技巧是验证帧率。综合 Demo 跑通后，不要在视觉上“感觉流畅”就完事，应该用 TouchGFX Profiler 或直接在 View 的 handleTick 里做一个计数器，统计 1 秒内进入多少次 tick。480x272 的目标是 60，如果实际只有 30，先去查优化等级，再去查图片格式，这两项占掉 90% 的性能问题。
第二个技巧是图片资源进 Keil 之前先统一格式。TouchGFX Image 资源在 Designer 里可以配置导出格式，界面不透明的装饰图用 RGB565，有圆角和阴影效果的需要半透明的图才用 ARGB8888。按钮按下前后的两张图最好尺寸完全一致，不一致时 Designer 会自动对齐，但实际点击热区是按第一张图计算的，看起来就会“点不到按钮边缘”。
第三个技巧是把一个 Screen 改成你自己的。在 Designer 里添加新 Screen，画一个按钮，然后在 View 里把按钮的 callback 指向一个自己的函数。这个函数里先不要写复杂逻辑，只是翻转一个 LED 或修改一个文本的值。跑通这一条，你就掌握了 TouchGFX 的基本闭环：控件创建、事件回调、界面更新。我从第一次跑通到首次给自己的产品做完一整个设置页，用了大约三天。最深的教训是别一上来就想改架构，H7 和 TouchGFX 的组合已经足够成熟，如果你发现某个效果做不出来，先怀疑自己对框架的用法不对，而不是怀疑芯片性能不够。希望帮到你。
本文还有配套的精品资源，点击获取
