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。