How to Upgrade TouchGFX version
This article explains how to upgrade TouchGFX to a new version for your existing application. It covers updating the TouchGFX framework files, your BoardConfiguration and your TouchGFX environment shell. Not all these steps are necessary for all updates.
The newest version of TouchGFX can be obtained by filling out an evaluation request form on touchgfx.com. Licensed users will notified via email when a new TouchGFX version is available.
Overview of TouchGFX Versioning
TouchGFX releases follow a semantic versioning scheme, where backwards compatibility is ensured as long as the major version number does not change. This means that if you have an existing application that runs on e.g. TouchGFX 4.3.0, you can upgrade to TouchGFX 4.5.0 without changing anything in the application. The same goes for the HAL code and BoardConfiguration, which can also be re-used without modifications. In the event of critical bugs, performance or feature issues which cannot be implemented without an API breaking change, these will be explicitly mentioned in the Known Issues article. It is therefore recommended to take a look at the known issues list when upgrading, to see if there is any particular concerns for your application.
- TouchGFX Designer 4.8.0 is not able to open Designer projects created with beta versions of the Designer. Future versions will be backwards compatible
Upgrading TouchGFX (MSI installer)
It is possible to have several versions of TouchGFX installed. When a new version is available, you can choose to uninstall the old one via Add/Remove programs if you only want the new one installed.
Running the MSI installer will guide you through the installation process.
- The installation path must not contain spaces.
- Keep installation path short, as some IDEs have problems with long file paths
Upgrading TouchGFX (zip)
The new TouchGFX version can also be obtained as a .zip file. This distribution does not contain the TouchGFX Designer application. It is therefore intended mainly for users on Linux. Check this installation guide for getting TouchGFX and Linux up and running.
The zip file contains the following:
- “app” folder containing various examples and demos
- “doc” folder containing API documentation for this version
- “touchgfx” folder containing the TouchGFX framework and tools
- “changelog.txt” describing the changes and additions for this release
The “app” folder will likely contain new examples and maybe new demos. Be sure to check them out to see how any new widgets/features are used, but otherwise this folder can be disregarded.
The “doc” and “touchgfx” folders from the new release should replace those you already use in your application. If you have made any changes to the “touchgfx” folder (for instance, added a new BoardConfiguration, or modified an existing one), make sure that you merge these changes into the new release.
Depending on your hardware platform, you might need to update your BoardConfiguration.cpp file. If you are using an unmodified BoardConfiguration.cpp from a previous TouchGFX release, just update the file to the newest version (which will happen automatically if you replace the entire “touchgfx” folder). But in case you have made changes to the file, you should compare your version of BoardConfiguration.cpp with the new version of the file (from the board you originally based your own version on). There are two cases where there might be changes to the standard BoardConfiguration.cpp files which you need to include in your version:
Retrofitting hardware configuration changes
In rare cases there might be a fix to a problem in the low-level hardware configuration of the board, which you need to make sure also gets propagated to your BoardConfiguration if appropriate. For instance, in TouchGFX 4.5.0 a bug in the MPU configuration of the STM32F7-based boards was fixed, so any existing applications using a BoardConfiguration.cpp based on a previous release must make sure to include this fix in their BoardConfiguration. The changelog.txt file will explicitly mention such concerns for a release.
Enabling new optional features
Often TouchGFX releases will contain new configuration features that are optional to use and needs to be explicitly enabled for them to have effect on your existing application. Examples of these are the finger size feature (introduced in 4.4.0) and the frame rate compensation feature (introduced in 4.5.0). Such features will be mentioned in the changelog.txt file accompanying the new release, and you can see how it is enabled in any of the BoardConfiguration.cpp files distributed with the new release. Pick the one most closely resembling your platform.
TouchGFX environment shell
When using the MSI installer, you will automatically get a new version of the environment shell. If you have made any changes to your old one (like .profile settings etc.) you need to manually copy these to the new installation.
As mentioned earlier, always check the Known Issues article to see if there is anything specifically that needs to be done by you, depending on which old and new TouchGFX version you are using.