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.
- Clean up the project: Remove generated files
- Create description files: Call
tgfx.exe
to generate the zip and json file - Describe the TBS: Edit the json file
- Generate
.tpa
: Calltgfx.exe
to finalize.tpa
- 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
在运行指令的目录中会创建下列文件:
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:
- 作者 使用Author字段指定作者姓名、电子邮箱和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.

**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
"PathToDotTouchGFX": "MyTouchGFXFolder/TouchGFX"
Tip
Generate .tpa
执行以下指令创建最终的“.tpa”文件,并完成TouchGFX应用模板。
$ /c/TouchGFX/4.25.0/designer/tgfx.exe pack -rc -d MyApplication
测试& 验证
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:
- You can rename the
.tpa
file if you want to. - Copy or move the
.tpa
file toC:\TouchGFX\4.25.0\app\packages
. This allows users to import TBSs, GUIs, and BSDs into TouchGFX Designer from a local folder. - Open TouchGFX Designer and select the TBS under the By Partners tab.
最终说明
The following section contains tips about what to consider when distributing TBSs.
一般提示
一般情况下,在分发.tpa
之前应:
- 确保提供的所有IDE项目按预期正常工作。
- 确保在TouchGFX项目文件
.touchgfx
中定义的自定义指令(PostGenerate-等)按预期正常工作。 - 确保TBS可以被TouchGFX Designer读取并用于创建新应用。
Tip
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