Frequently Asked Questions ¶

1. Is the selected STM32 series supported by HAL2 and the new generation of examples? ¶

The newest STM32 series, beginning with STM32C5, are supported by HAL2 and the new generation of examples. Refer to the Getting started with STM32Cube ecosystem documentation for more details about the overall ecosystem offering and the supported series. Refer to STM32 MCU Developer Zone for more details about the overall embedded software offering and the supported series.

2. Can I use these examples with STM32CubeMX ? ¶

No, the HAL2-based examples are not compatible with STM32CubeMX. They are designed to be used with STM32CubeMX2, the new generation of STM32CubeMX.

3. Can I replace HAL2 with HAL1 in these examples? ¶

No, the HAL2-based examples are not compatible with HAL1. They leverage the latest features of HAL2 and require its specific APIs and architecture.

4. Can I migrate existing HAL1-based examples to HAL2 ? ¶

Yes, you can migrate any existing HAL1-based projects to HAL2, but it requires a manual process of adapting the code to the new APIs and architecture of HAL2. You can refer to HAL1 to HAL2 migration guide for more details on the differences between HAL1 and HAL2, and the migration process.

5. How to find the project for my IDE in STM32 Example Library ? ¶

In the Select IDE column of STM32 Example Library, you can select the project for your IDE by looking for the corresponding value:

For STM32CubeIDE for Visual Studio Code, choose cmake.
For IAR Embedded Workbench® for Arm®, choose EWARM.
For Keil® MDK for Arm®, choose open-cmis.

To understand the IDE support in HAL2-based examples, refer to What is an example?.

6. Can I download several examples in one go from STM32 Example Library ? ¶

No, you cannot download several examples in one go from STM32 Example Library. You need to download each example separately, and you will get several times the same dependencies (HAL, DFP, …).

For such needs, we recommend using STM32 Package Creator, which allows you to define your own custom package with the features you want, and download it in one go. This will provide you with a single package containing all the examples you need, along with the necessary dependencies, without duplication.

See How to get STM32Cube Software Examples? for more information about the delivery channels and the contents obtained with each of them.

7. How to obtain the STM32CubeMX2 configuration files for the examples? ¶

Almost all examples are provided with STM32CubeMX2 configuration files ( .ioc2) by default. You can check in the Configurable column of STM32 Example Library if the example you are interested in is provided with a STM32CubeMX2 configuration file. If the example is provided with a STM32CubeMX2 configuration file, you can download it from STM32 Example Library together with the example project (no specific selection required). The STM32CubeMX2 configuration files are also provided (when available) in the STM32Cube MCU Package.

8. Where are the STM32CubeMX user sections in the HAL2-based examples? ¶

The HAL2-based examples are designed with a clear separation between the user code and the generated code. Therefore, the concept of STM32CubeMX user section is not required in HAL2-based examples.

The benefits of this new architecture are explained in Example architecture and How to port the example to another board.

If you want to add your own changes in the code generated by STM32CubeMX2, you can leverage the conflict resolution mechanisms of STM32CubeMX2. Read more about this in the STM32CubeMX2 user manual.

9. Why am I facing compilation issues with some examples and IAR Embedded Workbench® for Arm®? ¶

Few projects might be difficult to compile with IAR Embedded Workbench® for Arm® when working with a STM32Cube MCU Package. On a Windows machine, the 260-character path length limit can break some IAR Embedded Workbench® for Arm® builds. In this case IAR Embedded Workbench® for Arm® might report a build error like: Filename longer than 260 characters.

The simpler solution is to download the project from STM32 Example Library, as the project obtained from STM32 Example Library will not have the long path issue. Otherwise, refer to the Getting started documentation of the selected STM32Cube MCU Package for precise instructions on how to circumvent this problem.

10. How to map the structure of the HAL1-based examples to the structure of the HAL2-based examples? ¶

In HAL1 examples, most logic is grouped in Src/main.c, with generated user sections, plus dedicated files such as stm32tnxx_hal_msp.c and stm32tnxx_it.c. In HAL2 examples, this logic is split into layers with clear ownership:

application/main.c keeps the infrastructure flow and calls mx_system_init().
application/example.c contains the use-case code (app_init(), app_process(), app_deinit()).
[board_name]/generated/hal/mx_*.c contains STM32 and peripheral resource configuration generated by STM32CubeMX2.

Read more about the architecture of HAL2-based examples in Example architecture.

The table below summarizes the main equivalences.

HAL1 and HAL2 code structure mapping [1] ¶
Major topic	HAL1-based examples (STM32CubeMX)	HAL2-based examples (STM32CubeMX2)
Where is the user code from `main.c`?	In `Src/main.c` user sections ( `USER CODE BEGIN` blocks).	The scenario code moves to `application/example.c`. `application/main.c` remains small and stable, and mainly orchestrates system init and `app_*` calls.
Where is the system clock configuration?	In `SystemClock_Config()` in `Src/main.c`.	In generated RCC services under `[board_name]/generated/hal/`, mainly `mx_rcc.c` called by `mx_system_init()`.
Where is HAL initialized?	`HAL_Init()` is called in `Src/main.c`.	`HAL_Init()` is called inside `mx_system_init()` in `[board_name]/generated/hal/mx_system.c`.
Where is the equivalent of `MX_PPP_Init()`?	In `Src/main.c` as `MX_PPP_Init()` functions generated by STM32CubeMX.	In `[board_name]/generated/hal/mx_[pppi].c` as `mx_[pppi]_init()` services. Application code uses aliases from `mx_hal_def.h`, for example `mx_example_gpio_init` or `mx_example_spi_init`.
Where is the equivalent of `HAL_PPP_MspInit()` and `HAL_PPP_MspDeInit()`?	In `Src/stm32tnxx_hal_msp.c` through weak callbacks called by `HAL_PPP_Init()` and `HAL_PPP_DeInit()`.	There is no separate MSP callback file by default. Low-level resource setup and release (GPIO, DMA, IRQ, kernel clocks) are implemented directly in `mx_[pppi].c` init and deinit services. Peripheral clocks are centralized in `mx_rcc_peripherals_clock_config()`.
Where are the ITs?	Usually in `Src/stm32tnxx_it.c`. Peripheral IRQ handlers call HAL IRQ handlers.	Peripheral IRQ handlers are generated with their resource unit, for example in `[board_name]/generated/hal/mx_spi1.c`. Core NVIC setup is in `mx_cortex_nvic.c` and SysTick is provided in `mx_system.c`.

In short, the functional scenario is moved into application/example.c. Each HAL1 initialization block is moved to the related mx_ generated service and its alias in mx_hal_def.h. HAL2-based examples are designed to avoid the need for user modifications in generated code, and to maximize the stability of user code.

HAL2-based examples are also thoroughly documented in their README.md files. These README.md files contain important information about the scenario and how to use the example. See How to read an example to discover how to read an example and get the most out of it.