This document provides general information about the X-CUBE-WBA expansion software package for STM32Cube, which runs on the STM32U3 device and includes drivers for STM32WBA25, STM32WBA55, STM32WBA65 Bluetooth® LE Network/Radio coprocessor devices.
1. Introduction
The STM32WBA devices series are multiprotocol wireless 32-bit MCU Arm®-based Cortex®-M33 microcontrollers which supports the Bluetooth® LE protocol.
The STM32WBA device series can also be configured as Bluetooth® LE network or radio coprocessor by providing a hardware interface to an external microcontroller based on two protocols:
- SPI controller protocol with interrupt signal (proprietary protocol)
- UART (based on standard UART transport layer)
The following table describes the USART1 lines used on STM32WBA series devices:
| USART1 lines | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||
The following table describes the SPI lines used on STM32WBA series devices:
| SPI lines | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
Refer to Getting started with X-CUBE-WBA Bluetooth LE software expansion for STM32Cube (UM3529)[1], Section 4.4 SPI protocol for a description of the proprietary SPI protocol.
Refer to the Guidelines for Bluetooth® LE stack programming on STM32WB/STM32WBA MCUs (PM0271)[2] for information about the STM32WB/STM32WBA devices Bluetooth LE stack.
The STM32WBA device series supports the following network coprocessor options:
- Network coprocessor controller-only (also called Radio Coprocessor RCP)
- Network coprocessor host and controller (NCP)
In a network coprocessor controller-only approach, the LE controller and the host reside in two separate microcontrollers. Communication between the two microcontrollers is carried out through a standard serial interface, e.g. UART or SPI. The host can send HCI commands to communicate with the LE controller. The HCI interface and the HCI commands are standardized by the Bluetooth Core Specification. The Zephyr framework is tailored for a radio controller (controller-only) approach.
| Bluetooth LE radio coprocessor controller |
|---|
 |
In a network coprocessor host + controller approach, the LE controller and the host reside in a single microcontroller. User application is implemented on an external microcontroller, and communication between the two microcontrollers is done through a standard serial interface, e.g. UART or SPI. A specific application interface is provided for accessing the Bluetooth LE host and controller.
| Bluetooth LE network coprocessor host and controller |
|---|
 |
2. X-CUBE-WBA: Bluetooth LE software expansion for STM32Cube
The X-CUBE-WBA SW package is a fully compliant expansion for STM32Cube enabling development of applications using the Bluetooth LE connectivity provided on STM32WBA device series (STM32WBA25, STM32WBA55, STM32WBA65). It provides a reference SW framework for the STM32U3 external microcontroller hosted on a NUCLEO-U385RG-Q board connected to a X-NUCLEO-WBA25A1 including a STM32WBA25 device.
The following hardware components are required in order to run the X-CUBE-WBA examples:
- One STM32 Nucleo development platform (suggested order code: NUCLEO-U385RG-Q).
- One STM32WBA25 module expansion board (order code: X-NUCLEO-WBA25A1).
- One USB type C cable to connect the STM32U3 Nucleo to a PC.
The X-NUCLEO-WBA25A1 expansion board must be plugged into the NUCLEO-U385RG-Q through its ARDUINO® Uno V3 connectors.
| X-NUCLEO-WBA25A1 board |
|---|
 |
| NUCLEO-U385RG-Q board |
|---|
 |
X-NUCLEO-WBA25A1 interfaces with the STM32 Nucleo microcontroller (as the STM32U3 on NUCLEO-U385RG-Q board) via UART or full duplex SPI with an interrupt line interface. The firmware loaded on the module defines the host interface and, to modify it, user can simply change the firmware without modifying the hardware.
The X-CUBE-WBA SW package is based on the hardware abstraction layer for the STM32 microcontroller, STM32CubeHAL.
| X-CUBE-WBA SW package architecture |
|---|
 |
The X-CUBE-WBA SW package contains the following folders:
- Documentation: contains a compiled HTML file (X_CUBE_WBA.chm generated from the source code with detailed documentation regarding the software components and APIs)
- Drivers: contains the HAL drivers, the board-specific drivers for each supported board or hardware platform, including those for the on-board components and the CMSIS layer, which is a vendor independent hardware abstraction layer for the Cortex-M processor series.
- Middlewares: libraries and protocols related to host software and applications to interface the STM32WBA device.
- Projects: contains some sample applications with readme files, showing how to use the STM32WBA25 devices, for the NUCLEO-U385RG-Q platform with three development environments, IAR Embedded Workbench for ARM, RealView Microcontroller Development Kit (MDK-ARM) and STM32CubeIDE.
| X-CUBE-WBA SW package structure |
|---|
 |
The SW package allows easy portability across different MCU families.
2.1. X-CUBE-WBA: Bluetooth LE stack images and supported features
The X-CUBE-WBA provides the binary images required for configuring the selected STM32WBA device as:
- a network coprocessor host + controller device (UART and SPI mode binary images).
- a controller-only device (HCI controller-only configuration; UART and SPI mode binary images).
The following images are provided within the X-CUBE-WBA installation folder, under Utilities folder with associated readme files.
Network coprocessor configuration binary images:
- BLE_TransparentMode_SPI_STM32WBA2_NCP.bin
- BLE_TransparentMode_SPI_STM32WBA5_NCP.bin
- BLE_TransparentMode_SPI_STM32WBA6_NCP.bin
- BLE_TransparentMode_UART_STM32WBA2_NCP.bin
- BLE_TransparentMode_UART_STM32WBA5_NCP.bin
- BLE_TransparentMode_UART_STM32WBA6_NCP.bin
Radio coprocessor configuration binary images:
- BLE_TransparentMode_SPI_STM32WBA2_RCP.bin
- BLE_TransparentMode_SPI_STM32WBA5_RCP.bin
- BLE_TransparentMode_SPI_STM32WBA6_RCP.bin
- BLE_TransparentMode_UART_STM32WBA2_RCP.bin
- BLE_TransparentMode_UART_STM32WBA5_RCP.bin
- BLE_TransparentMode_UART_STM32WBA6_RCP.bin
The following Bluetooth LE stack features are supported, respectively, on Network coprocessor configuration and HCI Controller-only configurations:
- Advertising
- Scanning
- Central / Peripheral Connection
- Data length extension
- Privacy
- LE Encryption
- Legacy Pairing, LE secure connections
- 2Mbit
- Long Range
- Channel Selection Algorithm #2
- Direct Test Mode
- GATT Client / Server (only on NCP image)
- Extended Advertising/Scanning
- Periodic Advertising/Synchronization
- AOA/AOD
- Periodic Advertising Sync Transfer
- GATT Caching (only on NCP image)
- LE L2CAP Connection Oriented channel (only on NCP image)
- Enhanced ATT (only NCP image)
- Isochronous Broadcaster / Synchronizer (only on STM32WBA55/STM32WBA65)
- Connected Isochronous (only on STM32WBA55/STM32WBA65)
- LE Power Control
- Connection Subrating
- Advertising Coding Selection
- Channel Classification Enhancement
- Periodic Advertising ADI support
- Periodic Advertising with Responses (PAwR) (only on STM32WBA25)
- LE Frame Space Update (only on STM32WBA25)
- Monitoring Advertisers (only on STM32WBA25)
- LL Extended Feature Set (only on STM32WBA25)
The number of supported Bluetooth LE links is up to eight on both Network configuration and HCI Controller-only configurations.
The X-NUCLEO-WBA25A1 kit is pre-programmed with the Network coprocessor, UART mode binary image.
If the user wants to load any of available binary images on the STM32WBA25 device mounted on the X-NUCLEO-WBA25A1 expansion board, the following procedure should be followed:
- Connect the X-NUCLEO-WBA CN8 pins and the ST-LINK/V3 pins as described on following figure:
| Jumper connection between X-NUCLEO-WBA25A1 and ST-LINK/V3 |
|---|
 |
- Download and unpack the X-CUBE-WBA containing the STM32WBA firmware image.
- Download and install the STM32CubeProgrammer (v2.22.0 or later only).
- Connect the ST-LINK/V3 debugger to your PC.
- Open the STM32CubeProgrammer and follow these steps:
- Select the STlink-V3 SWD probe and select Connect icon.
- Erase the STM32WBA flash memory from [Erase Flash Memory]>[Full Chip Erase].
- Load the selected firmware contained in the X-CUBE-WBA/Utilities folder and press the [Start Programming] button on STM32CubeProgrammer tool.
| STM32CubeProgrammer |
|---|
 |
3. X-CUBE-WBA application examples
The following application examples are provided within the X-CUBE-WBA SW package on folder Projects\NUCLEO-U385RG-Q\Applications:
- Beacon application: it is a smart Bluetooth LE device that transmits a small data payload over-the-air using Bluetooth advertising packets configured with specific manufacturing data. It is used to locate place and objects. To locate the beacon, it is necessary to have a beacon scanner application running on a Bluetooth LE smartphone.
- BLE_FOTA application: it shows how to use the dual bank flash features to allow firmware-over-the-air update of a running program without using the bootloader. The BLE_FOTA receives the new firmware from the "ST BLE Sensor" application running on a Bluetooth LE smartphone.
- SampleApp application: it shows how to simply use the Bluetooth LE stack creating a client and server connection. It also provides the user with a complete example on how to perform an ATT MTU exchange procedure, so that the server and the client can agree on the supported max MTU.
- SensorDemo_BLESensor-App application: it shows how to implement a peripheral device tailored for interacting with the "ST BLE Sensor" application for Android/iOS devices.
- Virtual_COM_Port application: it allows interaction with the STM32CubeWiSE-Bluetooth LE Explorer tool, allowing to get access to the STM32WBA devices Bluetooth LE stack capabilities.
Refer to the application readme.html/md files available on each application example folder for detailed description about how the application works.
3.1. How to build a new X-CUBE-WBA project
If the user needs to start with a new IDE project, refer to the below guide as a reference:
- Create a new project in the selected IDE EWARM/MDK-ARM/STM32CubeIDE
- Select the STM32 device part number on which the application runs
- Add required files at the project location:
- Drivers
- CMSIS
- STM32xx_HAL_Driver
- Add IDE startup file – startup_stm32xx.s
- Add Middleware files
- Add Application files
- Drivers
Based on IDE properties, on C/C++ Compiler preprocessor tab add the folders paths and defined symbols For more details, refer to the respective IDE’s user manual.
In the context of EWARM IDE the following folders paths should be added on Projects, Options, C/C++ Compiler, Preprocessor, Additional include path:
- $PROJ_DIR$/../BLE_NCP/App
- $PROJ_DIR$/../BLE_NCP/Target
- $PROJ_DIR$/../Core/Inc
- $PROJ_DIR$/../../../../../../Drivers/STM32U3xx_HAL_Driver/Inc
- $PROJ_DIR$/../../../../../../Drivers/STM32U3xx_HAL_Driver/Inc/Legacy
- $PROJ_DIR$/../../../../../../Drivers/CMSIS/Device/ST/STM32U3xx/Include
- $PROJ_DIR$/../../../../../../Drivers/CMSIS/Include
- $PROJ_DIR$/../../../../../../Middlewares/ST/BLE_CP/includes
- $PROJ_DIR$/../../../../../../Middlewares/ST/BLE_CP/hci/hci_tl_patterns/Basic
- $PROJ_DIR$/../../../../../../Middlewares/ST/BLE_CP/utils
In the context of EWARM IDE the following symbols should be added on Projects, Options, C/C++ Compiler, Preprocessor, Defined symbols
- USE_HAL_DRIVER
- STM32U385xx
At this stage, the user should be in the position to compile and test the project.
| X-CUBE_WBA IDE project structure: EWARM example |
|---|
 |
4. References