1. Introduction
This wiki describes to an application developer the STM32WB0 series Bluetooth® LE stack library modularity feature and how to integrate the Bluetooth® LE stack library on a user application.
| Acronym definitions | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
2. Bluetooth® LE Stack v4.x overview
2.1. Release contents
The Bluetooth® LE stack v4.x is provided on the STM32_BLE middleware available on the STM32CubeWB0 FW package.
| Bluetooth® LE stack v4.x library architecture |
|---|
 |
The STM32_BLE Bluetooth® LE stack v4.x architecture provides the following features with related benefits:
- Code is modular and testable in isolation:
- High test coverage
- Hardware-dependent parts are provided in source form:
- Sleep timer module external to Bluetooth® Low Energy stack (Init API and tick API to be called on user main application)
- NVM module external to Bluetooth® Low Energy stack (Init API and tick API to be called on user main application)
- AES, PKA, RNG modules external to Bluetooth® Low Energy stack
- Certification targets the protocol part only:
- It reduces the number of stack versions, since hardware-related problems are mostly isolated in other modules.
- It reduces the number of certifications.
- It implements a flexible and robust radio activity scheduler
- It allows the robustness against late interrupt routines (for example, flash writes and/or interrupt disabled by the user).
- It reduces real-time constraint (less code in interrupt handler)
- The system gives more time to applications.
Bluetooth® Low Energy stack v4.x is a standard C library, in binary format, which provides a high-level interface to control STMicroelectronics devices Bluetooth® Low Energy functionalities. The Bluetooth® Low Energy binary library provides the following functionalities:
- Stack APIs for
- Bluetooth® Low Energy stack initialization
- Bluetooth® Low Energy stack application command interface (HCI command prefixed with hci_, and vendor-specific command prefixed with aci_)
- Bluetooth® Low Energy stack state machine handling
- Stack event dispatcher module
- Inform user application about Bluetooth® Low Energy stack events which have been registered and not registered
- Interrupt handler for radio IP
In order to get access to the Bluetooth® Low Energy stack functionalities, a user application is only requested to:
- Call the related stack APIs
- Handle the expected events through the provided stack dispatcher module
- Link the Bluetooth® Low Energy stack binary library to the user application, as described in following figure:
| Bluetooth® LE stack v4.x reference application |
|---|
 |
2.1.1. Folder structure
The Bluetooth® LE stack delivery contains four folders:
| Bluetooth® LE stack v4.x library folder structure |
|---|
 |
- The “doc” folder contains the current document and STM32WB0_BLE_Wireless_Interface.chm which describes the Bluetooth® LE stack v4.x Application Commands Interface (ACI) and the Host Commands Interface (HCI).
- The “include” folder contains the header files of the Bluetooth® LE stack library interface. These files contain some definitions of constants and types and the declarations of ACI and HCI functions.
- The “config” folder contains the Bluetooth® LE stack modular configuration options file.
- The “lib” folder contains the Bluetooth® LE stack library variants described in the following section.
2.1.2. Library variants
The Bluetooth® LE stack library is delivered in only two variants:
- One binary image containing the Bluetooth® LE Host + Controller Stack:
- Single binary image stm32wb0x_ble_stack.a which can be customized at compile time through Bluetooth® LE stack modularity feature
- One binary image addressing the Bluetooth® LE Controller Only Stack:
- stm32wb0x_ble_stack_controller_only.a which can be customized at compile time through Bluetooth® LE stack modularity feature
2.2. Bluetooth® LE stack v4.x stack library modularity
The modular configuration options allow the user to exclude some features from the available Bluetooth® Low Energy stack binary library and decrease the overall flash memory.
| Bluetooth® LE stack v4.x library modular options |
|---|
 |
In particular, Bluetooth® Low Energy stack v4.x provides the capability to enable/disable, at compile time, the following Bluetooth® Low Energy stack features based on a user-specific application scenario:
- Enable/disable controller privacy
- Enable/disable LE secure connections
- Enable/disable scan capability
- Enable/disable data length extension (valid only for the device supporting the data length extension feature)
- Enable/disable LE 2M and LE coded PHYs features
- Enable/disable extended advertising and scanning features
- Enable/disable L2CAP, connection-oriented data service feature (L2CAP-COS)
- Enable/disable periodic advertising
- Enable/disable periodic advertising with responses
- Enable/disable constant tone extension (where applicable)
- Enable/disable LE power control and path loss monitoring
- Enable/disable the connection capability, configuring support to connections:
- If the connection option is disabled, connections are not supported; the device is a broadcaster only if the scan capability option is disabled, or a broadcaster and observer only if the scan capability option is enabled.
- If the connection option is enabled, connections are supported; the device can only act as broadcaster or peripheral if the scan capability option is disabled, or any role (broadcaster, observer, peripheral, and scan) if the scan capability option is enabled.
- Enable/disable the connection subrating
- Enable/disable the channel classification
- Enable/disable the broadcast isochronous streams
- Enable/disable the connected isochronous streams
The scan capability option is linked to the new connection option as follows:
- Observer disabled (scan capability option disabled) or enabled (scan capability option enabled) if the connection option is disabled
- Observer and central disabled (scan capability option disabled) or enabled (scan capability option enabled) if the connection option is enabled
2.2.1. How to select the Bluetooth® Low Energy stack modular configuration options
The following Bluetooth® Low Energy stack preprocessor configuration options defined on file app_conf.h are used to activate/disactivate each modular configuration option (1: ENABLED; 0: DISABLED):
CFG_BLE_CONTROLLER_SCAN_ENABLED CFG_BLE_CONTROLLER_PRIVACY_ENABLED CFG_BLE_SECURE_CONNECTIONS_ENABLED CFG_BLE_CONTROLLER_DATA_LENGTH_EXTENSION_ENABLED CFG_BLE_CONTROLLER_2M_CODED_PHY_ENABLED CFG_BLE_CONTROLLER_EXT_ADV_SCAN_ENABLED CFG_BLE_L2CAP_COS_ENABLED CFG_BLE_CONTROLLER_PERIODIC_ADV_ENABLED CFG_BLE_ONTROLLER_PERIODIC_ADV_WR_ENABLED CFG_BLE_CONTROLLER_CTE_ENABLED CFG_BLE_CONTROLLER_POWER_CONTROL_ENABLED CFG_BLE_CONNECTION_ENABLED CFG_BLE_CONTROLLER_CHAN_CLASS_ENABLED CFG_BLE_CONTROLLER_BIS_ENABLED CFG_BLE_CONNECTION_SUBRATING_ENABLED CFG_BLE_CONTROLLER_CIS_ENABLED
Notes:
- The modular configurations options can be generated on app_conf.h file through the STM32CubeMX tool, STM32_BLE Middleware, by using the Configuration, Application Configuration - Modular Options tab.
- The file app_conf.h is generated on STM32_BLE Projects Projects\NUCLEO-WB0xyz\Applications\BLE\{BLE_Application_Name}\Core\Inc, where NUCLEO-WB0xyz can be:
- NUCLEO-WB09KE
- NUCLEO-WB07CC
- NUCLEO-WB05KZ
2.3. Library dependencies
The Bluetooth® LE stack v4.x library depends on (that is, must be linked with the following libraries):
- Middlewares\ST\STM32_BLE\cryptolib\\cryptolib.a
The cryptolib.a library provides the AES CMAC encryption functionality required by Bluetooth® Low Energy stack.
2.4. Application compilation options
These compilation options are compulsory:
- Plain 'char' is unsigned
- Short enum:
- For IAR® compiler, this option is set by default
- Keil µvision® environment with ARM® CC compiler, the following option shall be added: -fshort-enums
In Keil µvision® environment with ARM® CC compiler, the following linker options are added:
- --diag_suppress L6312W
- --diag_suppress L6314W
- --diag_suppress L6329W
In CubeIDE environment with GCC compiler, the following linker options are added:
- -z noexecstack
3. Bluetooth® LE stack user interface
In order to use the main functions of the Bluetooth® LE stack library, the user application code must include “ble_stack.h”.
3.1. Bluetooth® LE stack initialization
| BLE_STACK_Init function | ||||||
|---|---|---|---|---|---|---|
|
BLE_STACK_Init: The Bluetooth® LE stack initialization routine. This function is used to define the memory and configure the Bluetooth® LE stack.
All BLE_STACK_Init' parameters are described below:
| BLE_STACK_Init function's parameters | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Example:
BLE_STACK_InitTypeDef BLE_STACK_InitParams = {
.BLEStartRamAddress = (uint8_t*)dyn_alloc_a,
.TotalBufferSize = BLE_DYN_ALLOC_SIZE,
.NumAttrRecords = CFG_BLE_NUM_GATT_ATTRIBUTES,
.MaxNumOfClientProcs = CFG_BLE_NUM_OF_CONCURRENT_GATT_CLIENT_PROC,
.NumOfRadioTasks = CFG_BLE_NUM_RADIO_TASKS,
.NumOfEATTChannels = CFG_BLE_NUM_EATT_CHANNELS,
.NumBlockCount = CFG_BLE_MBLOCKS_COUNT,
.ATT_MTU = CFG_BLE_ATT_MTU_MAX,
.MaxConnEventLength = CFG_BLE_CONN_EVENT_LENGTH_MAX,
.SleepClockAccuracy = CFG_BLE_SLEEP_CLOCK_ACCURACY,
.NumOfAdvDataSet = CFG_BLE_NUM_ADV_SETS,
.NumOfSubeventsPAwR = CFG_BLE_NUM_PAWR_SUBEVENTS,
.MaxPAwRSubeventDataCount = CFG_BLE_PAWR_SUBEVENT_DATA_COUNT_MAX,
.NumOfAuxScanSlots = CFG_BLE_NUM_AUX_SCAN_SLOTS,
.FilterAcceptListSizeLog2 = CFG_BLE_FILTER_ACCEPT_LIST_SIZE_LOG2,
.L2CAP_MPS = CFG_BLE_COC_MPS_MAX,
.L2CAP_NumChannels = CFG_BLE_COC_NBR_MAX,
.NumOfSyncSlots = CFG_BLE_NUM_SYNC_SLOTS,
.CTE_MaxNumAntennaIDs = CFG_BLE_NUM_CTE_ANTENNA_IDS_MAX,
.CTE_MaxNumIQSamples = CFG_BLE_NUM_CTE_IQ_SAMPLES_MAX,
.NumOfSyncBIG = CFG_BLE_NUM_SYNC_BIG_MAX,
.NumOfBrcBIG = CFG_BLE_NUM_BRC_BIG_MAX,
.NumOfSyncBIS = CFG_BLE_NUM_SYNC_BIS_MAX,
.NumOfBrcBIS = CFG_BLE_NUM_BRC_BIS_MAX,
.NumOfCIG = CFG_BLE_NUM_CIG_MAX,
.NumOfCIS = CFG_BLE_NUM_CIS_MAX,
.isr0_fifo_size = CFG_BLE_ISR0_FIFO_SIZE,
.isr1_fifo_size = CFG_BLE_ISR1_FIFO_SIZE,
.user_fifo_size = CFG_BLE_USER_FIFO_SIZE
};
/* Bluetooth<sup>®</sup> LE stack init */
ret = BLE_STACK_Init(&BLE_STACK_InitParams);
if (ret != BLE_STATUS_SUCCESS) {
APP_DBG_MSG("Error in BLE_STACK_Init() 0x%02x\r\n", ret);
Error_Handler();
}
3.2. Bluetooth® LE stack process
The BLEStack_Process function runs all host stack layers’ dedicated processes through the BLE_STACK_Tick(). The function is scheduled as a sequencer task within the APP_BLE_Init() function, where the VTimer_Process() and NVM_Process() are also scheduled for calling, respectively, the HAL_RADIO_TIMER_Tick() and the NVMDB_Tick() functions. HAL_RADIO_TIMER_Tick() is the radio timer module tick function used to handle the related RADIO TIMER state machine. The NVMDB_Tick() is the NVM module tick function used to handle the related NVM module state machine.
| BleStack_Process function | ||||||
|---|---|---|---|---|---|---|
|
UTIL_SEQ_RegTask(1U << CFG_TASK_BLE_STACK, UTIL_SEQ_RFU, BLEStack_Process);
UTIL_SEQ_RegTask(1U << CFG_TASK_VTIMER, UTIL_SEQ_RFU, VTimer_Process);
UTIL_SEQ_RegTask(1U << CFG_TASK_NVM, UTIL_SEQ_RFU, NVM_Process);
ModulesInit();
The BLEStack_Process function call BLE_STACK_Tick() function as follows:
static void BLEStack_Process(void)
{
APP_DEBUG_SIGNAL_SET(APP_STACK_PROCESS);
BLE_STACK_Tick();
APP_DEBUG_SIGNAL_RESET(APP_STACK_PROCESS);
}
The API BLE_STACK_Tick() function must be called in order to process the internal Bluetooth® Low Energy stack state machines and when there are Bluetooth® Low Energy stack activities ongoing. The BLE_STACK_Tick() function executes the processing of all host stack layers and it has to be executed regularly to process incoming link layer packets and to process host layers procedures.
3.3. Bluetooth® LE stack events
The ACI/HCI asynchronous events coming from the Bluetooth® LE stack must be handled in the BLE_STACK_Event. It checks the event type (GATT event handler, proprietary non-GATT events, standard events, or unregistered events).
This function will be called by the Bluetooth® LE stack with the following parameters:
| BLE_STACK_Event function | ||||||
|---|---|---|---|---|---|---|
|
The Bluetooth® Low Energy stack library framework provides an event dispatcher module, which allows the user application to register an event handler to get notification of GATT events to be processed. The event dispatcher framework is implemented on ble_evt.[ch] files available in the Middlewares\ST\STM32_BLE\evt_handler folder. When the event dispatcher is used (recommended option), the application should register a callback for each service and each client implemented, since a GATT event is usually relevant to only one service and/or one client. When a GATT event is received, it is notified to the registered handlers. When no registered handler acknowledges positively the GATT event, it is reported to the application. A GAP event is not relevant to either a service or a client. For this reason, it is always sent to the application.
Notes:
1. The maximum number of GATT registered handlers is controlled by BLE_CFG_MAX_NBR_GATT_EVT_HANDLERS macros.
2. This handler is called from BLEStack_Process() context.
The BLEEVT_RegisterHandler API registers a handler to be called when a generic non-GATT event is received from the Bluetooth® LE core stack. A Bluetooth® profile can use this function to be notified when an event is received.
| BLEEVT_RegisterHandler function | ||||||
|---|---|---|---|---|---|---|
|
Notes:
1. The maximum number of these registered handlers is controlled by BLE_CFG_MAX_NBR_EVT_HANDLERS macros.
2. If the handler returns BLEEVT_Ack, no other registered handlers are called.
3. This handler is called from BLEStack_Process() context.
The BLEEVT_App_Notification API callback is triggered when either:
- A standard HCI event is received from the Bluetooth® LE core device
- A proprietary event not positively acknowledged by the registered handler is received from the Bluetooth® LE core device
Note: This callback is triggered in the BLEStack_Process() context.
BLEEVT_App_Notification
| BLEEVT_App_Notification function | ||||||
|---|---|---|---|---|---|---|
|
Example:
void BLEEVT_App_Notification(const hci_pckt *hci_pckt)
{
.....
.....
case HCI_LE_CONNECTION_COMPLETE_SUBEVT_CODE:
{
hci_le_connection_complete_event_rp0 *p_conn_complete;
p_conn_complete = (hci_le_connection_complete_event_rp0 *) p_meta_evt->data;
connection_complete_event(p_conn_complete->Status,
p_conn_complete->Connection_Handle,
p_conn_complete->Peer_Address_Type,
p_conn_complete->Peer_Address,
p_conn_complete->Connection_Interval,
p_conn_complete->Peripheral_Latency,
p_conn_complete->Supervision_Timeout);
}
break;
.....
.....
}
3.3.1. Commands and events interfaces
Each ACI/HCI command has its own interface, e.g. the HCI reset command can be called through the “hci_reset” interface.
The HCI commands and the ACI commands interfaces for GAP, GATT, HAL, L2CAP layers can be found in Middlewares\ST\STM32_BLE\stack\include\ble_api.h.
The HCI events and the ACI events interfaces for GAP, GATT, HAL, L2CAP layers can be found in Middlewares\ST\STM32_BLE\stack\include\ble_events.h.
4. Bluetooth® LE stack porting
The Bluetooth® LE stack uses some generic HW features, but allows the application to define them by using HW drivers or emulating some of them by SW code.
All the required porting interfaces by the Bluetooth® LE stack are defined in the bleplat.h
The following features are used and need to be implemented on the application side:
- NVM: non-volatile memory used by the security database of the Bluetooth® LE stack
- Sleep Timer: used by several components of the Bluetooth® LE stack
- AES: advanced encryption standard used by the security manager layer of the Bluetooth® LE stack
- PKA: public key accelerator used by the controller in the Bluetooth® LE stack
- RNG: random number generation used by the controller in the Bluetooth® LE stack
4.1. Bluetooth® LE platform functions
All the BLEPLAT functions are called from the Bluetooth® LE stack process or commands. Those functions return one of the following status values:
| BLEPLAT functions' returns | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
All the BLEPLAT PKA functions are called from the Bluetooth® LE stack process or commands. Those functions return one of the following status values:
| BLEPLAT PKA functions' returns | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
4.1.1. NVM functions
The NVM functions are used to store security database information (security and GATT records) in the NVM, read from the NVM, compare data with the stored data in the NVM and clear the security database or some of it.
| BLEPLAT NVM functions | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
4.1.2. Timer functions
The timer functions are used by the Bluetooth® LE stack to handle all procedures which are time dependent.
| BLEPLAT Timer functions | |||||||||
|---|---|---|---|---|---|---|---|---|---|
|
4.1.3. AES functions
The AES functions are used by the Bluetooth® LE stack to encrypt a 128-bit single block or to compute CMAC which is needed by Bluetooth® LE security manager.
| BLE PLAT AES functions | ||||||
|---|---|---|---|---|---|---|
|
4.1.4. PKA functions
The PKA functions are used by the Bluetooth® LE stack to compute the P-256 public key and the DH key used for Bluetooth® LE secure connections.
| BLEPLAT PKA functions | |||||||||
|---|---|---|---|---|---|---|---|---|---|
|
4.1.5. RNG functions
This function is called by the Bluetooth® LE stack to retrieve random values.
| BLEPLAT RNG function | |||||||||
|---|---|---|---|---|---|---|---|---|---|
|
5. References
Bluetooth® Low Energy stack v4.x Programming Guidelines (PM0274)