This article lists the issues that are known to be present in all TouchGFX versions, along with potential workarounds. Also, if there are any specific upgrade steps you need to perform to upgrade TouchGFX to a certain version, these will be mentioned. Note that if your current version is several releases old, you need to perform the upgrade steps for all the releases up to the new one.
As of version CubeMX 6.1.0 EWARM projects generated by CubeMX do not work with X-CUBE-TOUCHGFX because of a wrong setting for "C/C++ Compiler" / "Language" option which was changed from "Auto" to "C++" causing compilation errors. This issue will be fixed in CubeMX 6.1.1. In the mean time, changing the option back to "Auto", manually, will solve compilation issues but will be reverted upon code generation from CubeMX.
A bug in CubeProgrammer 2.6 related to how external loaders (
.stldr) are referenced breaks Makefiles for all existing Application Templates (AT) and also prevents the "Run Target" feature in TouchGFX Designer from functioning correctly. This issue also extends to user projects based on current versions of the ATs. Application templates will receive an update to compensate for this bug and will work for both CubeProgrammer 2.5 and 2.6. If you've got a project based on an AT that does not work with CubeProgrammer 2.6, you can make the following modifications to add support. Users must execute
STM32CubeProgrammer_CLI.exe from within the
bin folder when making a reference to an external loader. Generally, speaking:
binfolder of the STM32CubeProgrammer installation folder.
- Execute the command to program the connected target with a relative reference to the
While Cortex-M33 is fully supported by TouchGFX, "Software Packs" (TouchGFX Generator, among others) cannot be enabled in the current verison of CubeMX (v6.0.1) for multi-context MCUs until support is added in CubeMX. Disabling "Trust Zone" for Cortex-M33 based MCUs, thus limiting the MCU to a single context, will allow you to enable TouchGFX Generator. TrustZone should be enabled manually in User Code sections.
While TouchGFX now provides an ARMCLANG (ARM compiler v6.x) library for Cortex-M0, Cortex-M4f, Cortex-M7 and Cortex-M33, CubeMX is not able to generate projects that enable the ARMCLANG compiler (ARM Compiler v6.x). This requires users who wish to use the compiler in their projects to select the compiler manually from the project options in Keil uVision.
If configuring the FreeRTOS middleware from within CubeMX, any generated project using ARMCC (ARM compiler v5.x) will have FreeRTOS portable files that are not compatible with ARMCLANG; And these have to be replaced manually. Whenever "Generate code" is run from within CubeMX any manual changes will be overwritten and it would be wise to keep the project under version control (git, etc.) to undo these particular changes.
In summary. Since CubeMX can only generate ARM Compiler v5.x compiler projects, users have to modify the following every time code is generated from CubeMX unless they keep their project under version control.
- Select ARM Compiler v6.x in project options.
- Link with the ARMCLANG library instead of the ARMCC library (configured by CubeMX).
- If configuring FreeRTOS from within CubeMX, then the FreeRTOS portable files should be taken from the
portable/GCCfolder rather than
portable/RVDS(default for ARM Compiler v5.x) in order to be compatible with ARM Compiler v6.x.
The following workflow describes how to use v6.x ARM Compiler from Keil uVision with CubeMX generated projects and a TouchGFX ARMCLANG library.
- Select ARMCLANG (v. 6.x) in Keil uVision.
If you're configuring FreeRTOS from CubeMX, CubeMX will generate the wrong portable files and configure your project to use those. You have to manually replace these with the ones (from https://github.com/FreeRTOS/FreeRTOS-Kernel/tree/6199b72fbf57a7c5b3d7b195a3bd1446779314cd/portable/GCC (
portmacro.h) or download a FreeRTOS release and find the files in there.
Change your include path settings to include
portable/GCCfolder (in this case for Cortex-M7):
TouchGFX designer Post-Generate step during "Generate Code" will automatically insert the correct library based on the compiler version you've chosen.
The FontConverter tool would generate glyph pixel data for unicodes that were a part of a rule in the font, regardless of that glyph being used in an actual text in the application. This led to several megabytes, potentially, of additional glyph pixel data. New FontConverter tools (windows and linux) that no longer generate pixel data for glyphs that aren't in use by the application can be found here:
Extracting this file at the root of your 4.13.0 installation will update the fontconverter binaries inside
A library built with ARMCLANG compiler (v6.12) can be found here:
Extracting this file at the root of your 4.13.0 installation will place the library
The following deprecated features have been removed. If you have referenced them in your code, you may need to rewrite parts of your application:
- Definition of deprecated
The TextureMapper is disabled by default to reduce the code space used by TouchGFX. TouchGFX designer will insert code to enable texture mapper in all new project.
If you are migrating an old project to TouchGFX 4.13 and you are updating to TouchGFX 4.13 this is handled by TouchGFX Designer.
If you are updating manually then you need to insert code to enable the TextureMapper. Otherwise any TextureMapper will not draw on the screen.
Read more here: Configuring TouchGFX Features.
Two functions were moved from the TouchGFX library code to the
HALSDL2.cpp. This makes no difference for applications that uses the
HALSDL2.cpp as HAL for the Windows simulator.
If you have a old application (before TouchGFX 4.8.0) your simulator is maybe using HALSDL (not 2). This simulator HAL is not included in TouchGFX anymore. The HALSDL is missing the two functions that were previously included in the TouchGFX library. You need to add them manually to
Earlier versions are redrawing the entire screen after a screen transition is completed. This additional redraw caused performance issues on some slow platforms. If you require this redraw for some reason, you need to invalidate the relevant part of the screen, e.g. by calling
container.invalidate() in the
Screen::afterTransition() virtual of the Screen transitioned to.
The format of the binary fonts has changed because kerning data is now also included in the binary fonts. Binary font files needs to be regenerated, old files will not work correctly. Depending on how your Makefiles are setup, this is normally done by regenerating all assets (e.g.
make -f simulator/gcc/Makefile clean assets).
touchgfx/framework/include/touchgfx/lcd/LCD.hpp we have removed an include of the file
touchgfx/hal/HAL.hpp that was inserted by mistake in an earlier version. This may give you a compile error in a file where you have included
LCD.hpp and also make use of the
HAL.hpp content. The solution is to also include
touchgfx/framework/include/touchgfx/hal/HAL.hpp in your file.
From version 4.10.0 TouchGFX runs exclusively on STM32 MCUs.
You need to do the following if updating an old project.
Add the highlighted code below at application startup to inform TouchGFX that you are running on STM32 hardware. A suitable location is the end of the
hw_init() function in
IAR and Keil project updaters invoked from TouchGFX Designer do not respect custom file level optimization set in the respective IDE.
Rendering of TextAreas with ChromART (when TextArea is the top most element / last to be drawn) cause a premature unlocking of the framebuffer and subsequently a premature completion/transfer of the current frame to the display. Once
endFrame() is called by TouchGFX all drawing operations, including DMA operations, should already be completed. Due to a breach of contract by TextArea in how to appropriately protect the framebuffer, DMA operations are allowed to continue even after returning from
The contract for a widget is to either:
- Lock the framebuffer (returns a pointer to framebuffer).
- Draw something in the framebuffer.
- Unlock the framebuffer.
Or to use DMA operations, in which case syncronization of the framebuffer is handled automatically.
TextArea, in 4.10.0, mixes the two procedures which can cause glitches if it is the top most element (last to be drawn) of the current screen. The bug can be fixed by manually guarding
endFrame() with the following override of
endFrame() (based on F4 HAL). It ensures that
endFrame() does not return if ChromART operations are still being processed.
With the introduction of Application Templates, which essentially separates board support packages from the core framework, we have removed a lot of low-level drivers and other files from the touchgfx folder in 4.9.0. These files are now provided by application templates instead. However, this means that you cannot upgrade to 4.9.0 by just replacing the touchgfx folder, since that would likely lead to some BSP files missing. Instead, the TouchGFX Designer is able to perform the upgrade automatically. The upgrade can be done in two different ways, and you will need to decide which one is most suitable for you.
This method is done by simply opening your project in the new 4.9.0 Designer. TouchGFX Designer will prompt you whether you want to upgrade, and by clicking OK, TouchGFX Designer will apply the necessary changes. TouchGFX Designer will perform the following operations:
- Unpack the new reduced touchgfx folder into your application, and modify your TouchGFX path to match this
- Download and unpack all the files we have removed from the touchgfx folder, so that your project still compiles
This approach will leave pretty much everything as they used to be, so if the old file structure suits your project, this is the easiest choice. The main drawback is that you will not have the benefit of the image converter speedup (by working on image folders instead of individual files). But you can modify your makefile manually to use this approach though.
Using this method you can transition your project into the new template-based file organisation. To achieve this, you must first let the Designer upgrade your project using Method 1 above. Then, create a new project using the appropriate application template (simulator, or one matching your eval board). With this new project opened in the Designer, go to the top menu and click "Edit -> Import GUI". In the dialog box point out the .touchgfx file of your project. The Designer will then automatically import all the UI files, including assets, into the newly created project. If you have added additional code outside of the gui folder, you would need to manually copy those files over to the new project.
If you are not using the Designer, you can perform the upgrade by:
- Replacing the touchgfx folder used by your project with the one from the 4.9.0 installation.
- Download this zip and unpack it into the touchgfx folder, restoring the removed files.