# TouchGFX快速移植教程
本文为micespring的原创文章,首发平台为[oshwhub.com](https://oshwhub.com/) 和 [RT-Thread社区](https://club.rt-thread.org/)。转发请保留此内容和原始链接。
## 前言
TouchGFX是专为STM32系列芯片设计的一个现代的、高性能的、强大的嵌入式图形库。
本文面向熟悉STM32但是从未使用过TouchGFX的新手。通过阅读本教程,你将可以快速上手创建你的第一个TouchGFX项目,并将其移植到你自己的硬件平台上。
因为以快速为目标,本文除了关键点外,不会对教程中的步骤进行过多的讲解,所以需要具有一定的STM32开发基础,这至少需要你做过图形界面的开发或者对无图形库下的,基于RGB显示屏的应用开发有最基本的概念、并且需要了解相关的外设如FMC(SDRAM),LTDC,DMA2D的知识。如果你曾有过LVGL、emWin之类的图形库开发经验,那么在本教程中,这些经验同样会发挥作用。
本教程基于STM32 CubeMX和STM32Cube IDE进行开发,需要对这两个软件有最基本的了解。如果你习惯使用MDK或IAR,那么也可以使用自己熟悉的IDE来完成本教程,但是STM32 CubeMX是必须的。不过,我还是建议使用STM32CubeIDE,毕竟CubeIDE是ST官方的开发环境,拥有最好的兼容性。
## 准备工作
此小节说明了移植TouchGFX的准备工作,包括软硬件的准备,和软件环境的搭建
### 硬件
* 基于STM32 MCU的核心板/开发板一块,**需要带有LTDC功能**的型号(常见型号如F429,F746,H743)。核心板需要至少板载1M以上的外部SDRAM(本文中使用基于STM32F429IG核心板,板载SDRAM为IS42S16400QJ-7TLI)
* **RGB接口**的显示屏一块儿(推荐分辨率:320x240或480x272), 建议选择带触摸的型号(本文使用分辨率为320x240带电阻触摸的LCD屏)。
* ST-Link或者兼容的调试器(本文使用ST-Link v2.1)
### 软件
* STM32 CubeIDE(本文中使用的版本:v1.6.1)
* STM32 CubeMX(本文中使用的版本:v6.2.1)
* CubeMX请预先安装MCU对应的软件包(本文中使用:STM32Cube_FW_F4 V1.26.1)
* 独立的TouchGFX软件包,下载地址:[STM32 Graphical User Interface - STMicroelectronics](https://www.st.com/content/st_com/en/ecosystems/stm32-graphic-user-interface.html) (本文中使用:TouchGFX v4.16.1)
### 软件安装
#### TouchGFX Designer的安装
解压下载的TouchGFX软件包
![image.png](//image.lceda.cn/pullimage/sZ59G2H3VrxqTK3nnrH9CTCpeMA30nlXjXplJsr0.png)
进入目录\Utilities\PC_Software\TouchGFXDesigner,找到TouchGFX-4.16.1.msi,双击运行,保持所有的选项默认直接安装即可
![image.png](//image.lceda.cn/pullimage/GRSiv5garyux3HGPcpo8MPJttFJ9CKlET9dQxE9N.png)
安装完毕后,桌面上应该出现这两个图标
![image.png](//image.lceda.cn/pullimage/Rk3CtWS1YUEtmqEfmwmmh86O3s8ZQDH8xfEw0O2m.png)
#### CubeMX中TouchGFX软件包的安装
运行STM32 CubeMX
![image.png](//image.lceda.cn/pullimage/bhMgELA6XaLxnxHOTRhutBhAaj5lfBTMf0fUWQxY.png)
在主界面右侧点击 install/remove
![image.png](//image.lceda.cn/pullimage/MGZYOOWRecBgUbwJLY1Qa2HT1pAlp3QZ9UcxSOUd.png)
在打开的对话框中,定位至 STMicroelectronis 选项卡
![image.png](//image.lceda.cn/pullimage/hhtEnQmUaKUNm0eOy8AWNxWOEjyzxDcvL9fZfXc7.png)
滚动条往下拉,找到X-CUBE-TOUCHGFX并展开。然后选中v4.16.1版本前方的方块,点击下方InstallNow安装
![image.png](//image.lceda.cn/pullimage/kIULW6GGoalIHYFEdYAeQxraVgun7JnRdY49hkZY.png)
等待安装结束,则准备工作完成。
## 创建基础项目
### 通过CubeMX创建一个基础项目
通过STM32CubeMX 创建一个可以驱动RGB显示屏的基本工程,配置好必要的外设,如果可以的话,请顺便添加触摸屏的支持。创建的过程不再赘述。
提示,这一步中**请不要为项目添加过多的功能**,只需添加可以驱动你的液晶屏的最少功能即可(一般为RCC,FMC,SDRAM,LTDC和DMA2D,如果有触屏,则可能需要配置SPI或者IIC),否则出现错误后会增加排查的难度。
![image.png](//image.lceda.cn/pullimage/HggM5PSTu3okdi6b9uey1OJdVP1bm1RzQWV4lHg7.png)
切换至Project Mananger,根据下图进心项目配置
![image.png](//image.lceda.cn/pullimage/m427FwZz0iZ2eU1zL3D0oXYmkf0r3WLxZZZgHcrs.png)
配置完成后,点击右上角“Generate code”生成代码
![image.png](//image.lceda.cn/pullimage/tkSt2BrICgCuicrGksKEIycm2ePjWBnYdJqyfOwr.png)
等待代码生成完毕,点击关闭对话框
![image.png](//image.lceda.cn/pullimage/gXcDmmM6kUkVch7loPJmkYRtYcr26mw8eZvFGfTp.png)
### 将项目导入至STM32 CubeIDE
启动STM32 CubeIDE,**注意工作空间(Workspace)一定是CubeMX中设置的Project Location,**
![image.png](//image.lceda.cn/pullimage/eg6Bfh64tR6FcOi5wOf2x7CgXqiq0gBVfVDnoVYm.png)
选择“File” -> "Import"
![image.png](//image.lceda.cn/pullimage/DXAHkZhVUMafQno1lqFMdOEWwYolEvM8ba2oUAUT.png)
选择 “Existing Projects into Workspace”,点击“Next”
![image.png](//image.lceda.cn/pullimage/MHUFwBOHVTCofs9YOxmZlOYSJTfSJXrtC4Xh6ufl.png)
点击Browse,选择刚刚生成的项目
![image.png](//image.lceda.cn/pullimage/1TMJgoCyn1BJQeC0PNyDtj0y3puKoBEfvQ2QO0Pa.png)
其他选项保持与下图相同,点击Finish
![image.png](//image.lceda.cn/pullimage/JRH0Gcj7JsrZ6VxElRRtgrncmZ7PpWYYzSE0zDLs.png)
### 纠错、测试并运行项目
在左侧Project Explorer中即可看到刚刚导入的项目,展开工程,打开main.c文件
![image.png](//image.lceda.cn/pullimage/MHDadpucmQ1gVN15M0zSQNh1YfM0d4V5zP2EHjJq.png)
在User code begin 2区域中,**添加SDRAM的初始化代码**,然后编写简单的液晶屏清屏测试代码,用来确认工程配置是否存在错误
**注意!!!**
**如果生成的代码文件中存在类似XXX CODE BEGIN 和XXX CODE END注释包裹的代码块,则所有自行编写的代码的都必须放置在这些代码块中,否则下次点击CubeMX的生成代码按钮时,代码块以外的内容会被删除。**
![image.png](//image.lceda.cn/pullimage/qQcZoFTFPAZY9K0dDKX6DzB0bNV7dXDf4YaKG1En.png)
完成后,将**开发板通过ST-Link连接至电脑**,点击运行按钮
![image.png](//image.lceda.cn/pullimage/ejXjMWvkyd32CX82L19P2LySsDF0Oc3xy4e8GWKT.png)
首次运行会弹出运行配置对话框,保持所有选项默认,直接OK确认即可
![image.png](//image.lceda.cn/pullimage/nuYuXQhbwCuGwPx2aqoiHYooABa0co0m1AFdzjT0.png)
如果一切配置都正确,则程序会下载至开发板运行,液晶屏此时也应该按照预期显示颜色,如果存在错误,请根据错误提示检查,直至液晶屏可以正常工作。
![image.png](//image.lceda.cn/pullimage/KGqDmkoiZ0KJj9toNGZ1YkFSXfsj6HjCBjgfyaE8.png)
![image.png](//image.lceda.cn/pullimage/mXdtbWHZw2aYrsAT8E3IwyZTBd6mr3QBOZqTgSyj.png)
至此,本章结束,下一章我们将正式开始TouchGFX的移植。
## 为项目添加TouchGFX软件包
通过此章节,我们会将TouchGFX软件包添加至我们刚刚创建的项目,并创建一个最基本的用户界面
### 添加TouchGFX软件包
切换回CubeMX,选择Select Components
![image.png](//image.lceda.cn/pullimage/y92OK7ZjdF4215X9N67jmkdm9iPEZ0zPD6QPLdoK.png)
选择TouchGFX,然后点击OK
![image.png](//image.lceda.cn/pullimage/XjQooTiQGTgjq0o7llBpdYIyNsCnVzuBeZ2MYOB6.png)
在左侧的Software Packs中选择TouchGFX,在右侧勾选Graphics Application启用TouchGFX功能
![image.png](//image.lceda.cn/pullimage/HYbimYbCKRQbzLL50c1En6blFzq9SWhx00vmOfWa.png)
### 配置TouchGFX的基本参数
按照图中的说明设置参数,其中的参数的具体功能为:
* 1、 显示接口的类型,选择LTDC即可
* 3、颜色格式,根据实际情况选择,推荐RGB565
* 4、TouchGFX的帧缓存策略,此处使用单缓冲即可,暂时不使用双缓冲和部分缓冲
* 4、设置缓冲区地址为by address,即固定的缓冲区地址
* 5、在SDRAM的LTDC framebuffer之外的空间选择一处空间分配给TouchGFX的帧缓存,需要注意,可用空间必须大于等于LTDC帧缓冲的大小,并且四字节对齐。
* 6、TouchGFX的时钟源,选择LTDC即可
* 7、硬件加速器,如果你选择的MCU有DMA2D,选择即可(如果之前的项目配置中,未启用DMA2D,则需要先配置启用DMA2D)
* 8、在本教程中,我们暂时不使用OS
![image.png](//image.lceda.cn/pullimage/DrxOM7YOFMsx26UkLHLW3wGzB2779BOaxHmYWlPC.png)
然后我们还有几个关键的功能需要开启,第一个是硬件CRC校验:
![image.png](//image.lceda.cn/pullimage/vUunHmLMhFBqiORmmkkEcvib2dXh88jmbu9rIToz.png)
第二个是中断管理中的DMA2D和LTDC中断必须开启
![image.png](//image.lceda.cn/pullimage/V19gIdFmd2Wl8JmRuW8mJQOuFgZzcuHkl9fJccZC.png)
全部设计完成后,我们再次点击“GENERATE CODE”生成代码,生成代码完成后,选择**Open Folder**
![image.png](//image.lceda.cn/pullimage/JVG6WgfYcKXkVT9cQfgfZdZZlqHCDKWoIbOMHBCi.png)
### 设计界面
进入TouchGFX文件夹,双击运行后缀名为touchgfx.part的文件
![image.png](//image.lceda.cn/pullimage/Gzzn7V8vNRxloWFkgZkNfF93k6icouYqwUPa4h3g.png)
![image.png](//image.lceda.cn/pullimage/SgAEL2KYWWNOXzhjXnCCbVLO860YUIOgMWrwbD6y.png)
此时,TouchGFX Designer会自动启动
![image.png](//image.lceda.cn/pullimage/HY1RIoRFMZGyTAGWX5M9OzXXsfuLGrFKCwVGKelz.png)
然后会进入设计器主界面
![image.png](//image.lceda.cn/pullimage/qkhNvrNxO0hu0uHsAfMvbC3X8A8ocfVGQULoNwdq.png)
我们点击 Add Widgets,随意添加几个控件
![image.png](//image.lceda.cn/pullimage/ljZ21vNdIgk3htUp6wX9hXhDgv3HJUIIl5UUPiJS.png)
然后点击右上角的 Generate Code,等待代码生成结束。
![image.png](//image.lceda.cn/pullimage/BdcbIZQ4svw7BwVqp9H1PtSiWcx0jxhihAZuBZV6.png)
### 运行代码
代码生成完毕后回到STM32CubeIDE,在右边的工程上点击右键,选择刷新
![image.png](//image.lceda.cn/pullimage/eTKZJ11TE7ibLpZ8GJEe4QtNQzJZAxzLXPMaURDB.png)
然后依然点击运行
![image.png](//image.lceda.cn/pullimage/0x04uyA2flghctTHUpcq3G2rB2FryNTf9BaXvBzA.png)
一切正常的话,我们应该可以看到液晶屏上出现了我们刚刚放置的小部件
![image.png](//image.lceda.cn/pullimage/CXbyt2OlrbvPAoUmsRc8zQl7CuoQ92XS4HmD4v4e.png)
至此,我们已经成功完成了TouchGFX的移植。
### 添加触摸支持
接下来,我们要为TouchGFX添加触摸支持。触摸支持需要通过常规的方法根据你的开发板和液晶屏的具体硬件编写或者移植触摸屏驱动,编写完成后,我们在左侧项目管理器中打开STM32TouchController.cpp
![image.png](//image.lceda.cn/pullimage/Pa7cPDaWPxxbCbBmrpN3mer0006rKZghh4cEYOYZ.png)
在打开的代码文件的init函数中添加触屏的初始化代码,然后在sampleTouch函数中添加读取触屏的代码,典型的代码应该如下。
![image.png](//image.lceda.cn/pullimage/lShCeILJ5BiTVkDqOdceXLnPQpzHdqQNNB4Kqzvg.png)
完成代码的编写后,点击运行,将程序下载至开发板,此时点击按钮之类的控件,如果可以看到按压动画,则标志触摸屏支持移植完成。
## 移植官方的Demo
要想学习一个软件库,最好的方法就是参考官方的Demo。在本章中,我们将移植一个官方的Demo至我们的项目。
### 导入官方Demo并运行
续上一章,我们回到TouchGFXDesigner,点击Edit 选择Import
![image.png](//image.lceda.cn/pullimage/AZoX49GWI4cbVDGCBLCqkdEihmH3bgWlt3yODVRZ.png)
然后在弹出的对话框中,根据你的液晶屏分辨率,选择一个合适的Example或者Demo,点击感叹号可以查看此Demo适合的屏幕分辨率,此处选择的是分辨率240x320的Demo
![image.png](//image.lceda.cn/pullimage/PJDhwLcfh6b42hb6jQAJfeKzxEgwqgFtywpfojih.png)
![image.png](//image.lceda.cn/pullimage/OYhPRSbczpwHFr9wWGFoCCGq1lTIMZDqfuvZwj6U.png)
根据分辨率选择你感兴趣的、合适的Demo,点击Import,将Demo导入自己的项目中。**注意!!!请不要选择过于复杂的Demo,这些Demo通常会因为携带大量的媒体文件导致片内Flash无法存储需要外部储存器映射。**
![image.png](//image.lceda.cn/pullimage/Hs29z9i18GnwZLCY0FE7cHMU1a0KazXKcN7FIben.png)
此处因为笔者的显示屏分辨率是320x240,而Demo的分辨率是240x320,所以需要配置一下屏幕旋转,如果你也需要使用此功能,请在Config中设置,
![image.png](//image.lceda.cn/pullimage/IS4DM5XUkqpU8u33ObKnfCesqzRoWetN4wfDOEvX.png)
回到设计器界面,确认配置无误后,依然点击GenerateCode 按钮生成代码
![image.png](//image.lceda.cn/pullimage/WQ637KU10bwc7vDJlujo2nDBJ1CwsWzFO1gT3fCs.png)
切回STM32CubeIDE,**刷新项目**后运行项目,将代码下载到开发板中。如果没有错误的话,Demo就可以正常运行了。
![Video_2021-05-26_180008.gif](//image.lceda.cn/pullimage/Ji1xWBENMxvUOV4tAvN0iRxCgZRMpHxls6WMgw1s.gif)
## 结语
至此我们成功地在自己的开发板上运行了TouchGFX,本教程结束。
感谢大家的阅读,如果有什么问题、建议或者发现了教程中的错误,可以直接在评论区提出。我会尽快响应。
请不要发送私信,因为公开的技术讨论才能帮助所有人。
如果你还想继续深入地研究TouchGFX的运行机理,开发自己的TouchGFX应用,请参考TouchGFX的官方文档:[TouchGFX Documentation](https://support.touchgfx.com/docs/introduction/welcome)