Creating a TouchGFX Board Setup

TouchGFX開發版配置 （TBS）是 .tpa 文件，定義了運行TouchGFX應用程式的平臺。 This approach is for developers who wish to distribute easy-to-use TBSs separately from the UI code that runs on top of them. 本文描述了如何使用內建工具tgfx.exe，並將現有的TouchGFX專案封裝到可再分配的TBS中。 This tool can be found in the TouchGFX installation directory which is C:/TouchGFX/4.25.0/designer if it is installed in the default directory. For the duration of this article, examples are based on an application called "MyApplication" and on TouchGFX version 4.25.0.

Once you have a fully functional TouchGFX project the following steps are required to create a TBS.

1. Clean up the project: Remove generated files
2. Create description files: Call tgfx.exe to generate the zip and json file
3. Describe the TBS: Edit the json file
4. Generate .tpa: Call tgfx.exe to finalize .tpa
5. Test & Verify: Create a new project with the TBS in TouchGFX Designer and verify that it works

Clean up the project

When generating code (F4) in TouchGFX Designer, multiple files and folders are created. These files are not needed in the TBS because you will generate code again when creating a UI. Therefore, removing these files and folders will significantly reduce the size of the .tpa file. The following files and folders can be removed from the project:

The following TouchGFX related folders can be removed:

.\TouchGFX/assets
.\TouchGFX/build​
.\TouchGFX/config​
.\TouchGFX/generated​
.\TouchGFX/gui
.\TouchGFX/simulator​
.\TouchGFX/screenshots
.\Middleware/ST/touchgfx​
.\Middleware/ST/touchgfx_components

Note

• If you have a dual context project (for example CM4/CM7 or Boot/Appli), the TouchGFX folder will be placed in the CM7 or Appli folder. In this case, you should also remove the CM4/TouchGFX/build or Boot/TouchGFX/build folder during the cleanup process.
• If you wish to keep the GUI inside the .tpa when distributed, you should not remove the .\TouchGFX/gui and .\TouchGFX/assets folders.

The following STM32CubeIDE folders can be removed:

.\STM32CubeIDE/.settings
.\STM32CubeIDE/Debug
.\STM32CubeIDE/Drivers
.\STM32CubeIDE/Middlewares
.\STM32CubeIDE/Release

In the EWARM folder (relating to the IAR IDE), we only need to keep the following files:

.\EWARM/*.eww​
.\EWARM/*.ewd​
.\EWARM/*.ewp​
.\EWARM/*.icf​
.\EWARM/startup_*.s

In the MDK-ARM folder (relating to the Keil IDE), we only need to keep the following files:

.\MDK-ARM/startup_*.s​
.\MDK-ARM/*.sct​
.\MDK-ARM/*.uvoptx​
.\MDK-ARM/*.uvprojx

Create description files

tgfx.exe工具生成設定檔（.json），該文件描述TBS的內部構件。 This information is read by TouchGFX Designer and presented in the description pane on the right when selecting the TBS.

打開TouchGFX Environment 控制台，並在應用的 parent目錄中執行下列指令：

$ /c/TouchGFX/4.25.0/designer/tgfx.exe pack -d MyApplication

為.tpa準備文件

在運行指令的目錄中創建下列檔案：

生成的檔列表

Describe the TBS

Before creating the final .tpa, edit MyApplication.json to control how the TBS is displayed to users in TouchGFX Designer. The following sections should be updated:

• 作者 使用 作者 部分中的欄位指定作者姓名、電子信箱和URL。 You can delete some fields or keep them empty.
• PathToDotTouchGFX Specify the path to the .touchgfx file usually located in the TouchGFX folder.
• Data Use the fields in the Data section to specify TBS version, images, board name, type (TGAT for a TBS) vendor, description, and link to further information.

The available types and how each type is placed in TouchGFX Designer is shown below.

**TGAT** is for TBSs. The TBS will be placed in 'Create' in TouchGFX Designer.

**TGUI** is for GUIs. If it is a simple GUI, set the category to **example**, which will place it in 'Examples'.

**TGUI** is for GUIs. If it is a complex GUI, set the category to **demo**, which will place it in 'Demos'.

**TGAPP** is for a TBS combined with a GUI. It will be placed in 'Board Specific Demo' under 'Demos'.

An example of a json description file for a TBS is shown below.

MyApplication.json

   ...
    "Author": [
      {
        "Name": "Chad Brody",
        "Contact": "chad.brody@mycompany.com",
        "URL": "http://mycompany.com/"
      }
    ],
  ...
  "PathToDotTouchGFX": "",
  "EmbeddedOs": "FreeRTOS"
  ...
  "Data": {
    "Version": {
      "Major": 1,
      "Minor": 0,
      "Build": 0
    },
    "Name": "MyApplication",
    "HumanFriendlyName": "MyApplication",
    "BoardName": "Custom STM32 Board",
    "Type": "TGAT",
    "Vendor": "MyCompany",
    "Description": "This is a working project on which to base your UI on top of.",
    "DocumentationLink": "",
    "Category": "",
    "Images": [
      "http://mysite.com/MyCustomBoard-front.png"
    ],
    "Tags": [],
    "AvailableResolutions": [
      {
        "Height": 480,
        "Width": 480
      }
    ],
    "TargetBpp": [
      24
    ]
  }
}

Note

If the TouchGFX folder is not placed in the root of the project directory, you need to specify the path to the .touchgfx file in the PathToDotTouchGFX field. For example, if it is placed in .\MyTouchGFXFolder/TouchGFX, you need to write:
"PathToDotTouchGFX": "MyTouchGFXFolder/TouchGFX"

Tip

In order to include an image in your TPA, you need to provide a link to the image stored online.

Generate .tpa

執行以下指令創建最終的“.tpa”檔，並確定TouchGFX開發板設置。

$ /c/TouchGFX/4.25.0/designer/tgfx.exe pack -rc -d MyApplication

創建TouchGFX開發板設置

測試& 驗證

To verify that the .tpa file can be seen by TouchGFX Designer as a TBS and used to create new applications, perform the following steps:

1. You can rename the .tpa file if you want to.
2. Copy or move the .tpa file to C:\TouchGFX\4.25.0\app\packages. This allows users to import TBSs, GUIs, and BSDs into TouchGFX Designer from a local folder.
3. Open TouchGFX Designer and select the TBS under the By Partners tab.

TBS的相關資訊

最終說明

The following section contains tips about what to consider when distributing TBSs.

一般提醒

一般情況下，在分發.tpa之前應：

1. 確保提供的所有IDE專案按預期正常工作。
2. 確保在TouchGFX專案檔案.touchgfx中定義的自訂指令（PostGenerate-等）按預期正常工作。
3. 確保TBS可以被TouchGFX Designer讀取並用於創建新的應用。

Tip

Be sure to re-pack the application template after modifying the content of either the TouchGFX project or the `.json` file.

After distributing the .tpa one should instruct users to copy the .tpa file into C:\TouchGFX\4.25.0\app\packages and restart TouchGFX Designer.

版本控制

開發者通常會將整個開發專案（開發板啟動搭建、TouchGFX AL和TouchGFX UI）保存在同一個存儲庫中，因此不需要可分發.tpa文件。 但是，為了讓團隊成員能夠啟動新的TouchGFX應用，在進行測試和驗證時，統一的平臺程式碼會很有幫助。

如需通過分發.tpa檔和/或使用工具（如repo、git子模）來模組化程式碼庫，最好按照前文所述.json描述檔中指定的版本來命名TBS組件版本。 如果使用模組化方法，則platform程式碼在被用作主專案結構中的模組的同時，仍可用於創建可分發.tpa文件。

  "Data": {
    "Version": {
      "Major": 3,
      "Minor": 0,
      "Build": 0
    },

$ git tag
v1.1.0
v2.0.0
v2.1.0
v3.0.0