This article provides guidelines that allow users to migrate a Bluetooth® LE application built on a specific STM32CubeWB0 software package to a more recent version.
1. Introduction
The Bluetooth® LE application migration is mainly driven by the following items:
- STM32CubeMX .ioc file availability
- STM32CubeWB0 software package version and availability of the Projects\Common folder
- Bluetooth LE stack version and its impact on:
- Interrupt handlers and callbacks to use
- Bluetooth LE stack initialization parameters
- STM32CubeIDE version and related GCC version
Based on STM32CubeWB0 software package version and associated Bluetooth LE stack library version, some specific simple actions must be taken. This guide provides a practical and straightforward migration path for an STM32Cube-based application with a .ioc file. Some reference guidelines are also provided for Bluetooth LE applications without an .ioc file.
2. BLE Application migration guidelines
The following table provides the map between the STM32CubeWB0 SW package version, the associated reference STM32CubeMX tool version and the supported STM32_BLE Bluetooth LE stack version:
| STM32CubeWB0 SW package version vs Bluetooth LE stack & STM32CubeMX | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
For the safest minimal migration approach from a STM32CubeWB0 software package version to a more recent version with associated Bluetooth LE stack version, it is recommended to do the following:
- Copy the application folder (the one usually containing Core and STM32_BLE folder) into Project/{NUCLEO-WB0xxx}/Applications/BLE in the new STM32CubeWB0 package. To avoid overlap with an equivalent existing project in the new software package, rename the folder before the copy.
- Rename the original IDE project folder in order to regenerate a complete project in the new STM32CubeWB0 software package
- If available, open the related .ioc file with the reference STM32CubeMX PC tool version
The following sections describe the basic Bluetooth® LE application migration guidelines
3. BLE application Project/Common folder
Once the .ioc file is opened with the new reference STM32CubeMX tool (refer to Table "STM32CubeWB0 SW package version vs Bluetooth LE stack & STM32CubeMX"), the user must check if the COMMON_BLE utility is available in STM32CubeMX Utilities tab. It is strongly recommended to enable it. This allows to generate a IDE project with the direct reference to the centralized Projects\Common\BLE folder available on STM32CubeWB0 package.
If the STM32CubeMX .ioc file is not available, the user must:
- Open the IDE project
- Add the references to all the files located in Project/Common folder
- Update the related project include paths
- Cleanup the application project folder by removing the equivalent Projects\Common\BLE files previously available within the System application folder
The following table maps the STM32CubeWB0 software package version to the associated STM32CubeMX tool version and indicates whether the COMMON_BLE utility is available to use the centralized Project/Common folder for the selected Bluetooth® LE application.
| STM32CubeWB0 Projects\Common\BLE folder | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
4. RADIO RRM interrupt handler and callback
The STM32_BLE Bluetooth LE stack v4.1 or later requires a new RADIO RRM interrupt handler and callback:
- RADIO_RRM_IRQHandler associated to RADIO_RRM_IRQn interrupt line
- HAL_RADIO_RRMCallback() function which calls BLE_STACK_RRMHandler().
If the .ioc file is opened in STM32CubeMX with support for the STM32_BLE Bluetooth® LE stack version 4.1 or later, STM32CubeMX automatically generates the related RADIO_RRM_IRQHandler interrupt handler and callback code in the following files:
- stm32wb0x_it.c
- stm32wb0x_it.h
- stm32wb0x_hal_msp.c
- app_ble.c
- device startup file inside IDE toolchain project folder
If STM32CubeMX .ioc file is not available, the user must manually align these files with the equivalent files in the selected STM32CubeWB0 software package. All the required changes related to the new RADIO_RRM_IRQHandler must be applied by performing a file comparison one by one. The following table provides the map between the STM32CubeWB0 SW package version, the associated reference STM32CubeMX tool version and the availability of the new RADIO interrupt handler and callback functions:
| RADIO_RRM_IRQHandler and callback | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
5. BLE_STACK_InitParams: ExtraLLProcedureContexts parameter
Starting with STM32CubeWB0 v1.4.0 and the new Bluetooth LE stack v4.1, the ExtraLLProcedureContexts parameter is available in the BLE_STACK_InitParams structure. This parameter can be configured through STM32CubeMX v6.16 or later using the STM32_BLE configuration option CFG_BLE_EXTRA_LL_PROCEDURE_CONTEXTS available in Configuration > Application configuration > BLE stack tab. The following table provides the map between the STM32CubeWB0 SW package version, the associated reference STM32CubeMX tool version and the availability of the new ExtraLLProcedureContexts initialization parameter:
| ExtraLLProcedureContexts initialization parameter | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
If STM32CubeMX .ioc file is not available, the user must manually align the following files:
- Core/app_conf.h:
- Define CFG_BLE_EXTRA_LL_PROCEDURE_CONTEXTS macro and set it to 0
- Add the CFG_BLE_EXTRA_LL_PROCEDURE_CONTEXTS in BLE_DYN_ALLOC_SIZE
- STM32_BLE\App\app_ble.c
- Add .ExtraLLProcedureContexts = CFG_BLE_EXTRA_LL_PROCEDURE_CONTEXTS for BLE_STACK_InitParams
Refer to the app_conf.h and app_ble.c files from the new software package.
6. BLE_STACK_ProcessRequest() callback function
When using the STM32CubeMX .ioc file, the app_ble.c is automatically modified to use the new functionalities of the Bluetooth LE stack, like the BLE_STACK_ProcessRequest() callback.
If the STM32CubeMX .ioc file is not available, it is recommended (but not strictly required) to align the following functions in the app_ble.c file to take advantage of the BLE_STACK_ProcessRequest() callback:
- BLEStack_Process()
- HAL_RADIO_TIMER_TxRxWakeUpCallback(), HAL_RADIO_TIMER_CpuWakeUpCallback(), HAL_RADIO_TxRxCallback()
- BLE_STACK_ProcessRequest(), if available in the new app_ble.c
It is also recommended to make a general comparison with the app_ble.c file from applications in the new SW package to perform a complete alignment.
7. STM32CubeIDE v2.1.1 or later (GCC 14)
Starting with STM32CubeWB0 v1.5.0, the STM32CubeIDE project framework is updated to support STM32CubeIDE v2.1.1 with GCC14. As a consequence, cpu_context_switch.s in Projects\Common\BLE\Startup\ has been modified to handle new rules and syntax required by GCC14.
8. Reference documentation
The following documents are also recommended to be reviewed:
- Migrating from Bluetooth® LE stack v3.x to v4.x on STM32WB0 MCUs(AN6141)
- Introduction to the STM32WB0 Bluetooth® LE wireless interface (AN6142)
- STM32Cube MCU Package examples for STM32WB0 series(AN5976)
- How to build a Bluetooth® Low Energy application with STM32WB0 MCUs (AN5977)
- STM32WB0 Bluetooth® LE - STM32CubeMX application conception wiki article.