TouchGFX从旧版本更新到新版本的方法

01

引言

随着 TouchGFX 不断进行软件版本更新，其提供的功能也越来越丰富，有些新的功能只有更新的版本才有，所以很多时候会面临将旧版本的 TouchGFX 迁移到更新版本的问题。在创建 TouchGFX 应用时，生成的.touchgfx 工程文件版本与用来创建应用的TouchGFX Designer 版本相同，TouchGFX Designer 在设计上是向后兼容的，您可以使用更新版本的软件来开发您的应用。在大多数情况下，仅需一个极简单的流程便可使旧版本应用能够工作在 TouchGFX 新版本上。 

本文档提供了如何从较旧版本的 TouchGFX 升级到较新版本的教程，总结可能发生的常见问题及其各自的解决方案。本文档可能并不详尽，可能在将来进行更新，但旨在解决用户在版本更新时遇到的大多数问题，以确保顺利过渡到最新版本的 TouchGFX，从而享受最新版本的 TouchGFX 功能。

02

TouchGFX软件升级安装

X-CUBE-TOUCHGFX 是 STM32Cube 生态系统的一个软件包，它包含以下组件：TouchGFX Designer，TouchGFX Generator 和 TouchGFX Engine，其中 TouchGFX Designer 是用来构建 UI 的 GUI 构建工具，TouchGFX Generator 是通过 STM32CubeMX来生成用户 TouchGFX HAL 的工具，TouchGFX Engine 是驱动 UI 应用程序的TouchGFX C++框架。软件升级所涉及到的主要是 STM32CubeMX 中 TouchGFX Generator 插件升级安装和 TouchGFX Designer 升级安装。

2.1. 安装新版本 TouchGFX Generator

打开 STM32CubeMX 软件，点击菜单栏“Help”下的“Manage Embedded Software Package”，或者按键 ALT + U，进入到软件包列表。

图1.点击菜单栏“Help”下的“Manage Embedded Software Package”

进入软件包列表后，单击“Refresh”以获取有效的可更新的软件包列表，此操作需保证电脑网络连接正常。

图2.STM32CubeMX 中的软件包列表

然后转到“STMicroelectronics”选项卡， 滚动直至找到“X-CUBE-TOUCHGFX”，然后展开节点，选中最新版本“TouchGFX Generator 4.20”复选框，然后点击“Install ”，此时将下载软件包并显示许可协议。

图3.安装好 TouchGFX Generator 4.20 后的界面

2.2. 安装新版本 TouchGFX Designer

在类似路径

C:Users\STM32CubeRepositoryPacksSTMicroelectronicsX-CUBETOUCHGFX4.20.0UtilitiesPC_SoftwareTouchGFXDesigner 找到 TouchGFX.msi 安装程序，双击 TouchGFX.msi 文件可打开安装程序，按照说明完成安装过程。路径根据您的安装路径略有不同。 

图4.开始安装 TouchGFX Designer 4.20

03

工程项目由旧版本迁移到新版本TouchGFX

安装好新版本的 TouchGFX 软件后，下面介绍将您的工程代码迁移至新版本TouchGFX 的方法。一个完整的软件工程升级到新版本包括 STM32CubeMX 中TouchGFX Generator 配置升级并生成代码和使用新版本 TouchGFXDesigner 打开文件并生成代码。

3.1. STM32CubeMX 中 TouchGFX Generator 配置升级

3.1.1. 使用最新版本 STM32CubeMX 打开旧版本的.ioc 文件

使用最新版本的 STM32CubeMX 打开旧版本的.ioc 文件，CubeMX 会弹出类似如下的窗口。在项目加载时：STM32CubeMX 会检测该项目是否使用该工具的旧版本创建，如果是，则会建议用户迁移，以使用最新的 STM32CubeMX 数据库和 STM32Cube 固件版本，或者继续。点击继续将保持用于创建项目的数据库不变。如果计算机上没有所需的数据库版本，则会自动下载该版本。升级到 STM32CubeMX 新版本时，请确保在加载新项目之前始终备份项目（特别是当项目包含用户代码时）。

图5.STM32CubeMX 加载工程

图6.点击 Migrate 进行工程迁移

3.1.2. 在 STM32CubeMX 中更改 TouchGFX Generator 版本

在 STM32CubeMX 软件中，点击 STMicroelectronics.X-CUBE-TOUCHGFX.4.20.0 进入 TouchGFX Generator 配置界面。在开始升级软件版本时，请首先截图保留以下配置，以方便后面对照更新配置。

图7.截图保留原 TouchGFX Generator 配置

点击 Software packs 选择 Select Components ，在部件选择窗口，取消选择旧版本TouchGFX Generator，然后再选择最新版本的 TochGFX 4.20（或者将来更新版本）。当TouchGFX 4.20 被选中后，需要通过选择 TouchGFX Generator 来应用它。

图8.更改 STM32CubeMX 中 TouchGFX Generator 版本的步骤

3.1.3. 更新 TouchGFX Generator 配置参数

回到 TouchGFX Generator 配置界面，我们使用以前版本图 7 中的参数配置新的TouchGFX Generator，最后点击生成代码。

图9. 更新 TouchGFX 配置和生成代码

忽略以下 warning, 点击 Yes。

3.2. 使用新版本 TouchGFX Designer 打开 .touchgfx 文件生成代码

右键单击 .touchgfx.part 文件，然后选择最新的 TouchGFX Designer 打开，您将收到一个弹出窗口，要求您确认更新，请点击“是”。 

然后，您需要先删除 build 和 generated 文件夹，再重新生成代码。执行此操作后，需要在 STM32CubeMX 中再次生成代码。此时可以使用您的 IDE 来编译项目，并查看是否有任何错误。

 

图11. 选择最新的 TouchGFX Designer 打开.touchgfx 文件

04

软件升级遇到的常见问题

在软件版本升级之前一定要备份自己的软件工程，这是十分重要的。在将旧版本的TouchGFX 工程迁移到新版本的过程中，有以下事项需要检查确认：

（1）使用新版本 TouchGFX Designer 生成代码之前，是否在 STM32CubeMX 中使用相同版本的 TouchGFX Generator 并生成代码？如果您使用 TouchGFX 4.20，则需要在STM32CubeMX 中使用 TouchGFX Generator 4.20 和 TouchGFX Designer 4.20, 版本要保持一致。STM32CubeMX 的版本要选择支持 TouchGFX Generator 最新版本的版本，例如，要使用 TouchGFX Generator 4.20，那么 STM32CubeMX 的版本要最低为 6.5。

（2）检查代码中是否缺少#include 行。使用某些功能时，保证始终在每个文件中包含正确的路径。

（3）检查您使用的函数是否已被弃用，或者是否更改了名称。您可以参考帮助文档中的更新日志页面。

（4）建议使用 STM32CubeMX 单机应用程序，而不要使用 STM32CubeIDE 中的STM32CubeMX。因为在 STM32CubeIDE 使用 STM32CubeMX 进行升级会遇到更多的问题。 

（5）升级结束后，在重新编译代码之前，Clean 你的工程和去除之前编译的目标文件。 

（7）在迁移之前，请确保您没有用户代码部分之外的代码，否则您的代码将在代码生成后被删除。

（8）TouchGFX/Target 文件夹将在迁移后被修改，因此您可能需要将以前的代码复制粘贴到新创建的文件中。 

（9）TouchGFX 设计团队已经列出了 TouchGFX 版本中已知存在的问题，以及可能的解决方法。如果您在迁移时遇到问题，可以查看以下网址链接https://support.touchgfx.com/4.20/docs/miscellaneous/known-issues。