HAL1 to HAL2 - migration guide

Welcome to the user guide for migrating software applications from STM32Cube HAL1 to HAL2.

With the continuous development of the STM32Cube ecosystem, a new major version of the embedded software drivers, HAL2, is now available. HAL2 brings several improvements, especially in terms of usability and performance, while preserving the fundamental principles of the STM32Cube HAL drivers. To achieve these improvements, some breaking changes between HAL1 and HAL2 have been introduced. To assist with the transition and migration of projects from HAL1 to HAL2, the STM32Cube HAL1 to HAL2 migration tool and guide offers a comprehensive set of tools and documentation. These resources accelerate the transition, address breaking changes, and provide an API detection script, practical examples, and step-by-step guidance to ensure a smooth, efficient, and error-free upgrade path and it is structured into the following sections:

  • Getting started: introduces to the HAL1-to-HAL2 migration material and recommended migration journey.

  • HAL1 automatic detection script: explains the HAL1 API detection tool setup and use.

  • STM32 driver migration guides: these guides demonstrate the HAL2 changes compared to HAL1 in concepts and detailed driver-by-driver analyses.

  • Migration example: provides a practical example of a migration journey.

  • HAL migration checklist (link): allows users to track their progress and verify that all steps of the migration process are completed successfully.

Getting started

Getting started with HAL1-to-HAL2 migration.

Introducing the HAL1-to-HAL2 migration material. Discover the recommended HAL1-to-HAL2 migration journey.

Getting started
HAL1 automatic detection script

HAL1 automatic detection script principles and usage.

Discover the principles and usages of the HAL1 automatic detection script for a seamless transition to HAL2.

HAL1 automatic detection script
STM32 driver migration guides

Migration details for migrating STM32 drivers from HAL1 to HAL2.

Learn about the breaking changes in patterns and principles. Detailed migration guides for all HAL/LL drivers.

HAL1-to-HAL2 driver migration
Migration example

Migration process in practice, including IDE project configuration.

Tutorial on migrating an application with automatic and manual steps, based on the migration material.

Migration example

Note

This document focuses on the HAL2-based STM32Cube offer.

For any HAL1-based product, more detailed information is available in STM32Cube MCU & MPU packages.