HAL migration journey steps checklist
Copyright (c) 2026 STMicroelectronics
Copyright (c) 2026 STMicroelectronics
Enabling users to monitor their progress and ensure that all steps of the migration journey are completed successfully.
1- Copy the document within this repository.
2- Start the migration and carefully follow the steps outlined below.
3- Check the checkbox in the status column when each step is completed.
| Migration journey step index | Migration journey steps | Migration steps index | Migration task per journey steps | Links | Status |
|---|---|---|---|---|---|
| 0 | Before starting migration | 0.1 | Open the HAL migration guide documentation and carefully read the Getting Started section. | Link | |
| Before starting migration | 0.2 | Open the HAL migration guide documentation and carefully read the Migration Example section. | Link | ||
| Duplicate the initial project | 0.3 | Copy the whole application based on HAL1 within new folder. | Link | ||
| 1 | Replace HAL1 drivers by HAL2 | 1.1 | Remove HAL1 drivers (HAL and LL) files in your application folder and bring the HAL2 equivalent drivers (HAL and LL): - HAL2, HAL driver location: STM32Cube_SW_Package_TN_2.0.0\stm32tnxx_drivers\hal. - HAL2, LL drivers location: STM32Cube_SW_Package_TN_2.0.0\stm32tnxx_drivers\ll. | Link | |
| 1.2 | Copy the dfp folder within your application folder: - DFP, DFP driver location: STM32Cube_SW_Package_TN_2.0.0\stm32tnxx_dfp. | N/A | |||
| 2 | Update device selection in the IDE project | 2.1 | Open the duplicated application and update the application device within IDE settings. | N/A | |
| 3 | Update Linker and startup files | 3.1 | Open STM32CubeMX2, select application device, Configure the used peripherals and generate project. | Link | |
| 3.2 | Update the Linker, startup, system_stm32tnxx.c and stm32tnxx_hal_conf.h files within your application. | Link | |||
| 3.3 | Add the stm32_external_env.h within your application. | Link | |||
| 3.4 | Replace #include stm32tnxx_hal.h by #include stm32_hal.h within all application files. | Link | |||
| 3.5 | Check the availability of each #include stm32tnxx_ll_ppp.h and remove the include when the file is removed. | Link | |||
| 3.6 | Update the linker path within the IDE. | Link | |||
| 3.7 | Replace the startup, system_stm32tnxx.c files within IDE file selection. | Link | |||
| 4 | Update drivers inclusion path in the IDE project | 4.1 | Update the inclusion paths within IDE settings: - HAL and LL drivers - DFP drivers - CMSIS | Link | |
| 5 | Update drivers source files selection in the IDE project | 5.1 | Update the source file selection within IDE projects: - Remove all HAL1 drivers (HAL and LL). - Add required HAL2 drivers: the exact HAL2 files list can be retrieved from STM32CubeMX2 generated project created in the step 3.1. | Link | |
| 6 | Update Pre-Processor Defines for drivers in the IDE project | 6.1 | Update HAL pre-processor defines as per HAL2 drivers needs: the exact HAL2 pre-processor defines list can be retrieved from STM32CubeMX2 generated project created in the step 3.1.
Note: Make sure to not impact pre-processor defines that are not related to HAL. |
Link | |
| 7 | Execute the automatic HAL1 detection script | 7.1 | Open the HAL migration guide documentation and read the HAL1 Automatic Detection script section. | Link | |
| 7.2 | Execute the HAL1 Automatic Detection script.
Note: Make sure to install Python and the required Python dependencies if you will execute the script in Python format. |
Link | |||
| 7.3 |
Verify within command line that the execution is started and completed successfully: "Command Prompt (cmd)" terminal Example command with project path:
$ hal1_detection.exe -psrc "C:\STM32Cube_FW_H5_V1.5.0\Projects\STM32H563ZI\Examples\ADC\ADC_SingleConversion_TriggerSW_DMA" -m all
HAL1 automatic detection started successfully
HAL1 automatic detection applicative files number: 6
HAL1 automatic detection progression: 100%|################################################################| 6/6
HAL1 automatic detection applicative detected files number: 3
HAL1 automatic detection log file is generated under:
C:/HAL2_Migrator/hal1_detection_script_log/log_05-02-2026_10-35-48.html
HAL1 automatic detection execution time: 0.679 seconds
HAL1 automatic detection execution completed successfully
"Git Bash" terminal Example command with project path:
$ ./hal1_detection.exe -psrc "C:\STM32Cube_FW_H5_V1.5.0\Projects\STM32H563ZI\Examples\ADC\ADC_SingleConversion_TriggerSW_DMA" -m all
HAL1 automatic detection started successfully
HAL1 automatic detection applicative files number: 6
HAL1 automatic detection progression: 100%|################################################################| 6/6
HAL1 automatic detection applicative detected files number: 3
HAL1 automatic detection log file is generated under:
C:/HAL2_Migrator/hal1_detection_script_log/log_16-10-2025_10-35-48.html
HAL1 automatic detection execution time: 0.679 seconds
HAL1 automatic detection execution completed successfully
|
Link | |||
| 7.4 |
After completing the IDE settings update and running the HAL1 detection script, the detection results are logged in the folder: HAL2_Migrator\hal1_detection_script_log. |
Link | N/A | ||
| 8 | Resolve HAL1 Detected References | 8.1 | For information, the HAL migration guide documentation provides a detailed description of the HAL1 to HAL2 architecture concepts within the Breaking Changes in Concepts section. | Link | N/A |
| 8.2 | Open the corresponding Errata Sheet of the target series and check for any required SW workaround. Then, in the next steps, do not forget to consider these workarounds, if any, while resolving the detected HAL references. | N/A | |||
| 8.3 | Identifying and Handling User Code Sections Ensure that you identify the user code sections delimited by USER CODE BEGIN and USER CODE END. These sections can contain two types of content, which should be handled as follows: User Code Containing HAL1 API Usage and Calls: - Any code within the user code section that references HAL1 APIs will be fully detected and highlighted by the HAL1 detection script log. - The user must handle these detected references as described in step 8.5. User Code Containing Pure Applicative Code (No HAL1 API References): - Any code within the user code section that does not reference HAL1 APIs will not be detected by the HAL1 detection script and will be completely ignored. - After completing the HAL1-to-HAL2 migration and obtaining the equivalent HAL2 code, the user must manually inject the pure applicative code into the appropriate location, based on the needs of their application and based on the HAL1 to HAL2 architecture concepts: see also step 8.1. | N/A | |||
| 8.4 |
Open the log file generated under HAL2_Migrator\hal1_detection_script_log to start resolving HAL1 detected references.
Note:
- The log file generated by the HAL1 detection script is an HTML file that contains the user application code where HAL1 APIs are detected. |
Link | |||
| 8.5 | For each reference, resolve the detected HAL1-based part of code:
- Open the corresponding documentation link and follow the migration guides to ensure that the application code based on HAL1 is properly replaced with its HAL2 equivalent.
Note: When it comes to the HAL initialization code and sequence for each peripheral, the complete and appropriate code is provided by the STM32CubeMX2-generated project in Step 3.1. This code includes the full initialization sequence of the given peripheral, covering the HAL_PPP_MspInit and HAL_PPP_MspDeInit parts (e.g., GPIO, NVIC, etc.). Given this, the HAL_PPP_MspInit and HAL_PPP_MspDeInit callbacks should be removed by the user once the full peripheral initialization sequence has been copied from the STM32CubeMX2-generated project. - Compile the application and ensure that there are no compilation errors related to migrated code. |
Link | |||
| 8.6 | Run and test the migrated application. | N/A |