Skip to main content

Known Issues

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.

Issues with CubeMX 6.1.0 and CubeProgrammer 2.6​

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:

  • cd into the bin folder of the STM32CubeProgrammer installation folder.
  • Execute the command to program the connected target with a relative reference to the .stldr file.
@cd "$(st_stm32cube_programmer_bin_path)" && ./$(stm_stm32cube_programmer_exe) -c port=SWD -d $(application_path)/$(binary_output_path)/target.hex -el $(stm32cubeLoader_relative_path) -hardRst

TouchGFX 4.18.0​

New .touchgfx format​

From TouchGFX 4.17.0 to TouchGFX 4.18.0 the content of the .touchfgx file has been changed significantly in two major areas. This may result in a vastly updated .touchfgx file, simply by opening and saving a .touchgfx project file using the TouchGFX Designer. The main changes are in the following areas:

Default values are not written to .touchgfx​

Widget parameters that have a default value e.g. as a box offset of X=0, Y=0 or the color black (red=0, green=0, blue=0) were previously written to the .touchgfx file, but in TouchGFX version 4.18.0 these values are not written. This may result in slightly smaller .touchgfx files.

Removed TextEntries block​

SingleUseId's have been renamed to contain random numbers and letters instead of sequential numbers to ease merging of a project with several active developers, as new single use text id's do not get the same id. Also, the "TextEntries" section in the .touchgfx has been removed, which may result in a vastly reduced .touchgfx file size.

LCD16bpp::fillRect and LCD16bpp::drawGlyph​

The fillRect and drawGlyph functions in LCD16bpp now pass the full 24bit color to the DMA, instead of the reduced 16bit (RGB565) color. This may result in wrong colors on the hardware (not the simulator) and can be fixed by regenerating the DMA classes from CubeMX.

Makefile and xlsx​

TouchGFX 4.18.0 uses a new .xml format for storing texts and translations instead of the old .xlsx format previously used. This means that all references of "texts.xlsx" in Makefiles and visual studio projects should be changed to "texts.xml". The TextConvert tool will recognise this, even if the old texts.xlsx file exist and the texts.xml does not, and convert texts.xlsx to texts.xml for all future uses.

To see a new, working Makefile, simply create a new (blank) project using TouchGFX Designer and consult the generated Makefile located in folder generated/simulator/gcc/Makefile.

SDL2 linker error on Linux​

The SDL2 libraries used by the simulator are now only included for Windows users. Linux users must install the SDL2 libraries themselves. This is a task that has to be carried out only once, and for ubuntu the command is

sudo apt install libsdl2-dev libsdl2-image-dev

to install libsdl2 and libsdl2-image including header files for development

TouchGFX 4.17.0​

Painters no longer support setAlpha()​

For performance reasons, Painters used by the Canvas Widget Renderer (CWR) no longer support alpha. The effect can still be achieved by setting the alpha on the Canvas Widget that has the Painter. In general code can be changed from looking something like this:

painter.setColor(Color::getColorFromRGB(0xFF, 0x00, 0x00));
painter.setAlpha(128);
circle.setPainter(painter);

to something like this:

painter.setColor(Color::getColorFromRGB(0xFF, 0x00, 0x00));
circle.setPainter(painter);
circle.setAlpha(128);

If alpha was previously applied to both the Painter and the Canvas Widget, these two alpha values can be multiplied and then divided by 255, as follows:

painter.setColor(Color::getColorFromRGB(0xFF, 0x00, 0x00));
painter.setAlpha(painterAlpha);
circle.setPainter(painter);
circle.setAlpha(circleAlpha);

becomes

painter.setColor(Color::getColorFromRGB(0xFF, 0x00, 0x00));
circle.setPainter(painter);
circle.setAlpha((painterAlpha * circleAlpha) / 255);

or use LCD::div255() instead of dividing with 255.

Using the HAL class​

Prior to version 4.17.0, the header file touchgfx/hal/HAL.hpp would be included by several files in the TouchGFX framework that did not use HAL at all. These unnecessary references have been cleaned up, and this may result in user code that will not compile because HAL is not known to the compiler. To fix this, simply include the HAL header file as follows:

#include <touchgfx/hal/HAL.hpp>

Alternatively, the Screen class has two new functions getScreenWidth() and getScreenHeight() to give the screen size. This the recommended way to get the size of the screen and can be called directly from any subclass of Screen, such as e.g. Screen1View.cpp.

FMC Display Interface in TouchGFX Generator​

When using the new FMC Display Interface in TouchGFX Generator the memory offset for FMC banks will not be correct (zero) when generating with CubeMX 6.2.1. This will be corrected in CubeMX 6.3.0 and upon release the minimum required version for X-CUBE-TouchGFX will be bumped to 6.3.0 rather than the current 6.2.1. Until then, users can enter the correct FMC BANK Memory addresses inside TouchGFXGeneratedHAL.cpp (will be overwritten upon re-generation). E.g.

#define FMC_BANK1_REG ((uint16_t *) 0x60000000)
#define FMC_BANK1_MEM ((uint16_t *) 0x60000002)

Users may also redefine them in TouchGFXHAL.cpp entirely.

L8 images in 16- 24- or 32bpp configurations​

A call to OSWrappers::taskYield() was mistakenly introduced to STM32DMA classes when loading CLUT for L8 images. To fix this, users can do the following:

  1. Navigate to your Users/<user name>/STM32Cube/Repository/Packs/STMicroelectronics/X-CUBE-TOUCHGFX/4.17.0/CubeMX/templates/Target folder.
  2. Open the appropriate dma_Xbpp_implementation_tmp.ftl file based on your bit depth
  3. Delete or comment the call to OSWrappers::taskYield() call in the while ((READ_REG(DMA2D->FGPFCCR) & DMA2D_FGPFCCR_START) != 0U) loop, and regenerate code from STM32CubeMX to generate code using this modified template.
while ((READ_REG(DMA2D->FGPFCCR) & DMA2D_FGPFCCR_START) != 0U)
{
    // OSWrappers::taskYield();
}

TouchGFX 4.15.0​

MCU support​

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.

TouchGFX 4.14.0​

ARMCLANG Support​

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.

  1. Select ARM Compiler v6.x in project options.
  2. Link with the ARMCLANG library instead of the ARMCC library (configured by CubeMX).
  3. If configuring FreeRTOS from within CubeMX, then the FreeRTOS portable files should be taken from the portable/GCC folder rather than portable/RVDS (default for ARM Compiler v5.x) in order to be compatible with ARM Compiler v6.x.

Workflow​

The following workflow describes how to use v6.x ARM Compiler from Keil uVision with CubeMX generated projects and a TouchGFX ARMCLANG library.

  1. Select ARMCLANG (v. 6.x) in Keil uVision.

ARMCLANG Support

  1. 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 (port.c and portmacro.h) or download a FreeRTOS release and find the files in there.

    Replace port.c:

    port.c

    Change your include path settings to include portmacro.h from the portable/GCC folder (in this case for Cortex-M7):

    Portable include path

  2. TouchGFX designer Post-Generate step during "Generate Code" will automatically insert the correct library based on the compiler version you've chosen.

TouchGFX 4.13.0​

Bugs​

Font Converter​

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

touchgfx\framework\tools

Additional Compiler Support​

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 touchgfx_core_clang.lib inside.

touchgfx\lib\core\cortex_m7\Keil

Backwards Compatibility​

Deprecated Features​

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 TRANSPARENT_COL
  • Drawable::getType()
  • HAL::blitSetTransparencyKey()
  • HAL::registerTextCache()
  • HAL::cacheTextString()

TextureMapper is Disabled by Default​

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.

HAL SDL1 incompatible​

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 HALSDL.cpp:

HALSDL.cpp
void simulator_enable_stdio();
void simulator_enable_stdio()
{
    HWND consoleHwnd = GetConsoleWindow(); // Get handle of console window
    if (!consoleHwnd)                      // No console window yet?
    {
        HWND activeHwnd = GetActiveWindow(); // Remember which window is active

        AllocConsole();                   // Allocate a new console
        consoleHwnd = GetConsoleWindow(); // Get handle of console window

        FILE* dummy;
        freopen_s(&dummy, "CONIN$", "r", stdin); // Redirect stdin/stdout/stderr to the new console
        freopen_s(&dummy, "CONOUT$", "w", stdout);
        freopen_s(&dummy, "CONOUT$", "w", stderr);

        SwitchToThisWindow(activeHwnd, true); // Switch back to the originally active window
    }
    if (consoleHwnd)
    {
        ShowWindow(consoleHwnd, SW_SHOW); // Show/hide it!
    }
}
void simulator_printf(const char* format, va_list pArg);
void simulator_printf(const char* format, va_list pArg)
{
    // Create a console window, if window is visible.
    simulator_enable_stdio();
    if (GetConsoleWindow()) // Only print if we have a console window
    {
        vprintf(format, pArg);
    }
}

TouchGFX 4.12.3​

Backwards compatibility​

Screen transitions​

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.

Binary Fonts​

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 4.11.0​

Backwards compatibility​

In 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.

TouchGFX 4.10.0​

Upgrading from 4.9.x​

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 BoardConfiguration.cpp

BoardConfiguration.cpp
void hw_init() {
    ...
    //Enable CRC engine for STM32 Lock check
    __HAL_RCC_CRC_CLK_ENABLE();
}

Backwards compatibility​

Unused file \touchgfx\framework\include\touchgfx\canvas_widget_renderer\RGBA8.hpp removed.

Project Updater Issue​

IAR and Keil project updaters invoked from TouchGFX Designer do not respect custom file level optimization set in the respective IDE.

TextArea and ChromART (DMA2D)​

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 endFrame().

The contract for a widget is to either:

  1. Lock the framebuffer (returns a pointer to framebuffer).
  2. Draw something in the framebuffer. 
  3. 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.  

void STM32F4HAL::endFrame()
{
    if (dma.isDMARunning())
    {
        OSWrappers::tryTakeFrameBufferSemaphore();
    }
    HAL::endFrame();
}

TouchGFX 4.9.0​

Upgrading from 4.8.0​

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.

Caution
Please make sure you have a backup of your project before upgrading

Method 1: retain original file structure​

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:

  1. Unpack the new reduced touchgfx folder into your application, and modify your TouchGFX path to match this
  2. 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.

Method 2: import into new template​

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.

Method 3: Manual upgrade without Designer​

If you are not using the Designer, you can perform the upgrade by:

  1. Replacing the touchgfx folder used by your project with the one from the 4.9.0 installation.
  2. Download this zip and unpack it into the touchgfx folder, restoring the removed files.