Best-practices / FAQ: TrueSTUDIO + STM32CubeMx

Posted by Mattias Norlander on Nov 12, 2018 9:43:55 AM

Where to start? This is not a blog article about how to work with STM32CubeMX. There is plenty of information available on that topic on This blog rather tries to describe the specific challenges that may arise when trying to use STM32CubeMX with TrueSTUDIO. Do not miss the FAQ at the end which are the most common issues that first-time users run into. But first a table of content and some concept definition and orientation...

Table of Content:

Tool descriptions and quick orientation STM32CubeMX + TrueSTUDIO FAQ


Tools descriptions and quick orientation

STM32Cube is a comprehensive software tool suite for STM32 provided by ST. This ecosystem of tools is continuously growing and incorporating more tools, drivers, stacks and example projects. The two most important components of the STM32 Ecosystem are:


STM32Cube MCU Package

This is simply put a zip-file that provides drivers, stacks and example project for a specific STM32 device series. They are named STM32CubeF1, STM32CubeL4, etc.


This package can be used stand-alone with any IDE although example projects are only provided for SW4STM32, EWARM and MDK-ARM. Even though the example projects are not explicitly developed for TrueSTUDIO, TrueSTUDIO is still able to import/convert these projects from the SW4TM32 format. This blog article will not talk about example projects, instead read more on how to import example projects here.



STM32CubeMX is a graphical tool that allows a very easy configuration of STM32 microcontrollers and the generation of the corresponding initialization C code through a step-by-step process.


The tool provides simple pinout configuration with automatic conflict resolution, clock tree with dynamic validation of configuration, peripherals and middleware functional modes and initialization with dynamic validation of parameter constraints, and power sequence with estimate of consumption results.

STM32CubeMX cannot be used in any meaningful way without the STM32Cube MCU Package for the MCU device that your are targeting. But the tool helps you download the latest version automatically.

In conclusion STM32CubeMX/STM32Cube is the starting point for STM32 development and allows the customer to quickly get started with both example projects and your own first STM32CubeMX managed project. Read more here.


STM32CubeMX TrueSTUDIO plug-in vs Stand-alone application

STM32CubeMX exists both as an Eclipse plug-in that can be installed in TrueSTUDIO and as a stand-alone application. So which version should you use? This question does not have one simple answer.

Eclipse plug-in version has the benefit of giving you one IDE with all tools integrated - this option appeal to some people.

Stand-alone version means that TrueSTUDIO and STM32CubeMX runs as two separate applications. Some of the benefits with this approach are: That you can open/run multiple instances of STM32CubeMX. If either TrueSTUDIO or STM32CubeMX should crash, the other tool will not. STM32CubeMX will not slow down TrueSTUDIO by running inside, Eclipse is already a quite heavy framework to run on resource constrained laptops. TrueSTUDIO is built on one Eclipse version. STM32CubeMX Eclipse plug-in is not necessarily built and tested for the same version.

All-in-all our recommendation would be to use the stand-alone version.


Word of caution: Multiple tools - same data!

STM32CubeMX generates a stand-alone TrueSTUDIO project. A TrueSTUDIO project consists of a folder containing a .project and a .cproject file as a bare minimum. Additionally, HAL-drivers, CMSIS libraries, linker and debugger scripts are generated into the project folder. Each time the STM32CubeMX user clicks "Generate code" this code is re-generated. STM32CubeMX cannot see if you are using an external tool TrueSTUDIO or another, that is simultaneously reading/writing to the same file. If this happens things can go wrong. Files can potentially be destroyed/disappear.

So, what are the options/recommendations as to how to safe-guard yourself from file erase disaster?

1. Version control

The obvious solution to back-up the project files and the code is of course to version control using some version control software. Important to consider is however that if the version control metadata is stored inside the project folder which would be the default with for example git, then the revision history is not backed-up and safe until you have pushed it to a remote - which as a minimum should be outside the project folder. If the version control system allows storing the metadata outside the project root folder this is an even better option.

2. Sandboxing

Some users use an STM32CubeMX generated project only as a project skeleton in your TrueSTUDIO workspace. These users also create a standard TrueSTUDIO wizard project and copy the relevant STM32CubeMX generated TrueSTUDIO project resources across after each cycle of "Generate code". This may sound tedious, but it also a way of making sure that you are in control of which changes are introduced into your project code rather than STM32CubeMX. To make the file copying task efficient you can right-click on two equivalent files or folders Compare with > Each other. This will give you a diff of the selected resources on folder/file and file content level. Easy to navigate and ´then easy to just select the few resources that were changed by the re-generate cycle in STM32CubeMX.

Each time you click Generate code in STM32CubeMX STM32CubeMX will take a fresh copy of the HAL drivers and CMSIS libraries from the STM32CubeFw folder that is setup to be used by this project. As a result, you cannot make any changes to these drivers/libraries unless using the sandboxing method described above.

All files which you are "intended" to be able to modify such as main.c or stm32l4xx_it.c contain blocks where you are allowed to insert USER CODE:




If you write code anywhere outside these USER CODE blocks it will be removed by STM32CubeMX on the next cycle of generation of code.



The most (only?) interesting part of this blog article is probably the misunderstandings that we most often hear from the STM32CubeMX/TrueSTUDIO beginner end-users. These are:


The debugger "jumps around randomly" or "breakpoints don't work" or "Execution stuck at a certain code line"

These are all symptoms of the same underlying problem. STM32CubeMX generates a build configuration named Debug which has the optimization setting set to -Os (optimize for size). When applying any optimization level above -O0 or -Og the debugger will be unable to disassemble and map a certain instruction 1-to-1 to a C code line. Since source code no longer matches Assembly instructions. This will throw the debugger off totally. Stepping may not work, breakpoints may not work and it may seem as if execution is stuck at some random code line when it actually is in the while(1)-loop in main(). The fix is however simple:


Change the optimization level to -O0 or -Og (if you need to shrink the binary size to fit into memory). One could question the default setting in STM32CubeMX - why generate a project with a build configuration named Debug that obviously does not debug well? The main reason is that some of the STM32 libraries such as the motorcontroller library requires -Os minimum to work at all. I guess we will see in the future if optimization level can be set on folder/file level by STM32CubeMX which actually is supported by TrueSTUDIO.


Enable parallel build

Parallel build is not enabled by default in any freshly created TrueSTUDIO project. Thus, it is up to the user to toggle this feature on. The Parallel build feature allows the TrueSTUDIO build system to launch several instances of GCC at the same time. Each instance will build one c-file.


With parallel build each core can work on compiling one c-file parallelizing this task and thereby significantly reducing the build time for the project.


The general recommendation is to choose to run as many jobs as your CPU has cores. So as an example; a computer with 2 cores and hyper-threading, enabling 4 cores, will most likely perform best when using 4 jobs.


Does STM32CubeMx support C++ projects?

The answer is that STM32CubeMX can currently not generate project files for TrueSTUDIO supporting C++. There are however as always work-arounds. In the Eclipse/CDT world (TrueSTUDIO world) there is a concept called "natures" for each project. A project with "cnature" will setup the GCC C Compiler in TrueSTUDIO to build all files. A project with "ccnature" will add the C++ Compiler tool and replace the C Linker with the C++ Linker. The user will need to manually setup include paths/symbols/etc for the C++ Compiler. It is quite easy to copy the relevant settings across, since the C Compiler still is visible as a tool .

The C++ Linker however replaces the C Linker, therefore it is not possible to copy the settings across once the project is converted from C to C++. Therefore, make sure to copy/screenshot the Linker settings before you convert the project. 


ccnature is added by right-clicking on the project > New > Convert to a C/C++ project (Adds C/C++ nature).


Then select the Executable project type and Toolchains.: Atollic ARM Tools, and click Finish!


Voila - the project now has C++ Compiler and C++ Linker. C-files will be compiled by the C Compiler and .cc and .cpp-files will be compiled by C++ Compiler. This behaviour cannot be changed. As you can see the Directories list in the screenshot is empty. It is however simple to go to C Compiler > Directories, select all, CTRL+C and then CTRL+V in C++ Compiler > Directories to copy all of them, or whatever subset your application needs. Symbols can also be batch copied across, the rest of the settings must be manually verified.

Then verify that the C++ Linker still uses the correct linker script under C++ Linker > General. And add the necessary libraries, if any.

STM32CubeMX is still going to generate the main.c file which will be where execution of the application ends up after executing the reset logic. The easiest way to take you from C --> C++ context is simply by adding a start.cpp file containing a function declared as extern "C" that can be called from main() in main.c:

extern "C" int start_cpp() {

  /* Starting point for all C++ code */

  while(1); /* Assuming you don't wish to return to main() in main.c */


Add a call in main() to start_cpp() and make sure the call will not be removed by a Generate Code event in STM32CubeMX:



  /* USER CODE END ? */


That concludes the major questions that arises when one starts working with STM32CubeMX and TrueSTUDIO for the first time. Did we miss any important information that beginners may need to know? Drop a comment below!

Topics: Atollic TrueSTUDIO, STM32CubeMX, STM32Cube