隨著 TouchGFX 不斷進行軟件版本更新，其提供的功能也越來越豐富，有些新的功能只有更新的版本才有，所以很多時候會面臨將舊版本的 TouchGFX 遷移到更新版本的問題。在創建 TouchGFX 應用時，生成的.touchgfx 工程文件版本與用來創建應用的TouchGFX Designer 版本相同，TouchGFX Designer 在設計上是向后兼容的，您可以使用更新版本的軟件來開發您的應用。在大多數情況下，僅需一個極簡單的流程便可使舊版本應用能夠工作在 TouchGFX 新版本上。

本文檔提供了如何從較舊版本的 TouchGFX 升級到較新版本的教程，總結可能發生的常見問題及其各自的解決方案。本文檔可能并不詳盡，可能在將來進行更新，但旨在解決用戶在版本更新時遇到的大多數問題，以確保順利過渡到最新版本的 TouchGFX，從而享受最新版本的 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:UsersSTM32CubeRepositoryPacksSTMicroelectronicsX-CUBETOUCHGFX4.20.0UtilitiesPC_SoftwareTouchGFXDesigner 找到 TouchGFX.msi 安裝程序，雙擊 TouchGFX.msi 文件可打開安裝程序，按照說明完成安裝過程。路徑根據您的安裝路徑略有不同。

圖4.開始安裝 TouchGFX Designer 4.20

安裝好新版本的 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 文件

在軟件版本升級之前一定要備份自己的軟件工程，這是十分重要的。在將舊版本的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。