1. Introduction
This wiki describes to an application developer how to integrate the STM32WBAxx Bluetooth® LE stack library.
It covers only the Bluetooth® LE stack library integration, and it does not include the Link Layer integration aspects.
| Acronym definitions | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
2. Bluetooth® LE Stack Overview
2.1. Release contents
2.1.1. Folder structure
The Bluetooth® LE stack delivery contains three folders:
| Bluetooth® LE library folder structure |
|---|
 |
- “doc” folder contains the current document and STM32WBA_BLE_Wireless_Interface.html which describes the Bluetooth® LE Application Commands Interface (ACI) and the Host Commands Interface (HCI).
- “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. It also contains the declarations of some external modules functions used by the Bluetooth® LE stack. For more details, see section 4.2.
- “lib” folder contains the four Bluetooth® LE stack library variants described in the following section.
2.1.2. Library variants
The Bluetooth® LE stack library is delivered in four variants:
- Two variants containing the Bluetooth® LE Host Stack:
- Full Stack (stm32wba_ble_stack_full.a)
- Basic Plus Stack (stm32wba_ble_stack_basic_plus.a)
- Basic Stack (stm32wba_ble_stack_basic.a)
- Peripheral Only stack (stm32wba_ble_stack_po.a)
- Two variants without the Bluetooth® LE Host Stack (they only contain the LE Controller):
- Link Layer Only Stack (stm32wba_ble_stack_llo.a)
- Link Layer Only Basic Stack (stm32wba_ble_stack_llobasic.a)
| Bluetooth® LE stack variants |
|---|
 |
Here are the four Bluetooth® LE stack variants details:
- Full Stack (stm32wba_ble_stack_full.a) includes the LE Controller and the Host Stack, both with all the supported features. It contains all the legacy stack supported features plus the advertising extensions, GATT caching, Enhanced ATT, ACI HCI flow control, isochronous support for audio, L2CAP connection oriented channels.
Note: This Bluetooth® LE stack variant can be configured to run in controller only mode (the Host Stack is bypassed). See the parameter “options” of the initialization structure BleStack_init_t parameters in section 3.1 to enable/disable the controller only mode.
- Basic Plus Stack (stm32wba_ble_stack_basic_plus.a) includes the LE Controller and the Host Stack, both with the basic supported features along with additional features as Extended Advertising/Scanning, LE Power Control and Connection Subrating, Enhanced ATT, L2CAP connection oriented channels and GATT caching features.
- Basic Stack (stm32wba_ble_stack_basic.a) includes the LE Controller and the Host Stack, both with the basic supported features. It contains only Bluetooth® LE legacy features without the advertising extensions, neither GATT caching, nor Enhanced ATT, nor ACI HCI flow control, nor isochronous support, nor L2CAP connection oriented channels. The Host Stack is included, and it supports all the basic GATT, GAP and L2CAP features.
- Peripheral Only stack (stm32wba_ble_stack_po.a) includes only the LE Controller and the Host Stack, both with the basic features but only for peripheral role. The Host Stack is included, and it supports all the basic GATT, GAP and L2CAP features.
- Link Layer Only stack (stm32wba_ble_stack_llo.a) includes only the LE Controller with all the supported features. It contains all the features supported by the Full Stack but doesn’t include the Host Stack.
- Link Layer Only Basic Stack (stm32wba_ble_stack_llobasic.a) includes only the LE Controller with the basic supported features. It contains all the features supported by the Basic Stack but doesn’t include the Host Stack.
For more information, please refer to STM32WBA_BLE_Wireless_Interface.html to know which ACI and HCI command/event is supported by each stack configuration.
The table below details the supported features for each Bluetooth® LE stack variants:
| Supported features of each Bluetooth® LE stack variants | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
(1): These values were computed with STM32CubeWBA Firmware Package v1.3.0 using Keil® environment with optimization size option.
(2): It might be limited to 8 or 20 links depending on the Link Layer library used.
2.2. Real-Time environment
The Bluetooth® LE stack library is independent from the real-time software environment as well as any real-time resources.
The functions of this library used during run time are:
- The Bluetooth® LE stack commands (HCI, ACI...),
- The Bluetooth® LE stack process,
- The Bluetooth® LE stack callback functions called by the link layer or the platform software (PKA, Timer...).
All these functions must be called from the same level of execution, that is, from the same task when using a real-time operating system or from the main loop in a bare metal environment.
2.3. Library dependencies
The Bluetooth® LE stack library depends on (that is, must be linked with the following libraries):
- STM32WBAxx Link Layer libraries (refer to table Bluetooth® LE stack variants in section 2.1.2 for Link Layer library configuration dependency).
- Standard C library:
- Only basic memory functions are used (memcpy, memset, memmove, memcmp).
2.4. Library compilation options
The Bluetooth® LE stack library was compiled with the following options in Keil® environment:
- General options:
- Byte order: Little-endian
- FPU: VFPv5 single precision
- C/C++ Compilation options
- Compilation options:
- --library_interface=aeabi_clib: Used to generate AEABI-compliant object code
- --mno-unaligned-access: Used to enforce aligned memory access
- Plain 'char' is unsigned.
- Compilation options:
As mentioned above, the Bluetooth® LE stack library is AEABI compliant; The advantage of adhering to AEABI is that the Bluetooth® LE stack library can be linked with any other AEABI-compliant module, even modules produced by tools provided by other vendors than Keil®.
For the enum type, the Keil® C/C++ compiler will use the smallest type required to hold enum constants (-fshort-enums), preferring signed rather than unsigned.
2.5. 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 two following linker options shall be added:
- --diag_suppress 6654
- --diag_suppress 6775
In CubeIDE environment with GCC compiler, there is no need to add specific compiler options or linker options.
3. Bluetooth® LE Stack User Interface
In order to use the main functions of the Bluetooth® LE stack library, the user application code needs to include “blestack.h”.
In addition, to be able to directly call Bluetooth® LE commands (see section 3.3.2), the application needs to also include “blecore.h”.
3.1. Bluetooth® LE stack initialization
| BleStack_Init function | ||||||
|---|---|---|---|---|---|---|
|
BleStack_Init: The Bluetooth® LE stack initialization routine. This function is used to define the memory and configure the Bluetooth® LE stack.
All BleStack_Init parameters are described below:
| BleStack_Init function's parameters | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Example:
BleStack_init_t pInitParams;
pInitParams.numAttrRecord = CFG_BLE_NUM_GATT_ATTRIBUTES;
pInitParams.numAttrServ = CFG_BLE_NUM_GATT_SERVICES;
pInitParams.attrValueArrSize = CFG_BLE_ATT_VALUE_ARRAY_SIZE;
pInitParams.prWriteListSize = CFG_BLE_ATTR_PREPARE_WRITE_VALUE_SIZE;
pInitParams.attMtu = CFG_BLE_MAX_ATT_MTU;
pInitParams.max_coc_nbr = CFG_BLE_MAX_COC_NUMBER;
pInitParams.max_coc_mps = CFG_BLE_MAX_COC_MPS;
pInitParams.max_coc_initiator_nbr = CFG_BLE_MAX_COC_INITIATOR_NBR;
pInitParams.numOfLinks = CFG_BLE_NUM_LINK;
pInitParams.mblockCount = CFG_BLE_MBLOCK_COUNT;
pInitParams.bleStartRamAddress = (uint8_t*)buffer;
pInitParams.total_buffer_size = BLE_DYN_ALLOC_SIZE;
pInitParams.bleStartRamAddress_GATT = (uint8_t*)gatt_buffer;
pInitParams.total_buffer_size_GATT = BLE_GATT_BUF_SIZE;
pInitParams.debug = 0x10; // static random address generation
pInitParams.options = 0x0000;
return_status = BleStack_Init(&pInitParams);
3.2. Bluetooth® LE stack process
The BleStack_Process function runs all Host stack layers’ dedicated processes.
| BleStack_Process function | ||||||
|---|---|---|---|---|---|---|
|
The BleStack_Process function shall be called in the following conditions:
- This function shall be called regularly to handle all stack callbacks when needed. If it returns BLE_SLEEPMODE_RUNNING, it shall be re-called. If it returns BLE_SLEEPMODE_CPU_HALT, there is no need to call this function again and the MCU can go to sleep mode.
- The Link Layer has been scheduled.
- An ACI/HCI command, ACL data or ISO data has been sent to the Bluetooth® LE stack (either by calling BleStack_Request or by direct call to a specific command).
- By the platform software at the timer expiry or the end of PKA activity.
Example:
return_status = BleStack_Process();
if (return_status == BLE_SLEEPMODE_RUNNING)
// BleStack_Process shall be re-called again
else
// The MCU can go to sleep mode
3.3. Bluetooth® LE stack ACI/HCI interface
We have two ways to send commands and receive events in ST’s Bluetooth® LE Stack: Transparent Mode or Direct Mode.
3.3.1. Transparent Mode
To use Bluetooth® LE stack in Transparent Mode, a buffer that contains the ACI/HCI command or ACL data packet shall be passed as parameter to the function BleStack_Request.
The ACI/HCI command will be executed. The response event (command complete/ command status) is returned in the same buffer, and the size (in bytes) of the response event is given by the function’s return value.
| BleStack_Request function | ||||||
|---|---|---|---|---|---|---|
|
Example:
// It is recommended to initiate the buffer at maximum length that Bluetooth® LE stack supports.
uint8_t reset_cmd[255] = {0x01, 0x03, 0x0C, 0x00};
/* Bluetooth® LE stack will execute Reset command, the Command Complete Event will be returned in reset_cmd array,
the total length of event is returned in event_length. */
uint16_t event_length = BleStack_Request(reset_cmd);
// The response packet will be in Bluetooth® LE standard format.
uint8_t cmd_status = reset_cmd[6];
The ACI/HCI asynchronous events must be handled in the BLECB_Indication callback.
This function will be called by the Bluetooth® LE stack with the following parameters:
| BLECB_Indication function | ||||||
|---|---|---|---|---|---|---|
|
Example:
uint8_t BLECB_Indication(const uint8_t* data, uint16_t length,
const uint8_t* ext_data, uint16_t ext_length)
{
if (data[0] == HCI_LE_META_EVT_CODE)
{
// Check the subevent_code and the parameter length
if ((data[2] == HCI_LE_CONNECTION_COMPLETE_SUBEVT_CODE) && (data[1] == 0x13))
{
hci_le_connection_complete_event_rp0 *p_conn_complete;
p_conn_complete = (hci_le_connection_complete_event_rp0 *) (data + 3);
printf("Connection DONE - Connection handle: 0x%04X\n", p_conn_complete->Connection_Handle);
printf("Connection established with @:%02x:%02x:%02x:%02x:%02x:%02x\n",
p_conn_complete->Peer_Address[5],
p_conn_complete->Peer_Address[4],
p_conn_complete->Peer_Address[3],
p_conn_complete->Peer_Address[2],
p_conn_complete->Peer_Address[1],
p_conn_complete->Peer_Address[0]
);
printf("Connection parameters:\n- Connection Interval: %.2f ms\n- Connection latency: %d\n- Supervision Timeout: %d ms\n",
p_conn_complete->Conn_Interval * 1.25,
p_conn_complete->Conn_Latency,
p_conn_complete->Supervision_Timeout * 10
);
}
}
return 0;
}
3.3.2. Direct mode
The Direct Mode provides a dedicated API for each ACI/HCI command and event.
Instead of using BleStack_Request / BLECB_Indication like in transparent mode, the ACI/HCI commands/events can be used through the dedicated functions. Those functions are listed and detailed in the document STM32WBA_BLE_Wireless_Interface.html.
To use the direct mode, the BLE wrapper shall be compiled, that means “ble_wrap.c” needs to be included section 3.3.2.1.
3.3.2.1. Bluetooth® LE stack wrapper
The Bluetooth® LE stack includes a wrapper to execute pre and post processing for each BLE command.
The wrapper is implemented in the include/auto/ble_wrap.c file and defines each pre-processing and post-processing macro.
Each wrapper macro can be defined at application level to execute dedicated code. By default all specific macros are defined to the generic macros : "BLE_WRAP_PREPROC" and "BLE_WRAP_POSTPROC".
The "BLE_WRAP_PREPROC" and "BLE_WRAP_POSTPROC" are empty macros; it is up to the user to redefine those macros to execute pre and post processing respectively for every command.
Wrapper implementation:
/* Generic BLE command pre-processing macro */
#ifndef BLE_WRAP_PREPROC
#define BLE_WRAP_PREPROC( )
#endif
/* Generic BLE command post-processing macro */
#ifndef BLE_WRAP_POSTPROC
#define BLE_WRAP_POSTPROC( )
#endif
/* HCI_DISCONNECT pre-processing macro */
#ifndef BLE_WRAP_HCI_DISCONNECT_PREPROC
#define BLE_WRAP_HCI_DISCONNECT_PREPROC BLE_WRAP_PREPROC
#endif
/* HCI_DISCONNECT post-processing macro */
#ifndef BLE_WRAP_HCI_DISCONNECT_POSTPROC
#define BLE_WRAP_HCI_DISCONNECT_POSTPROC BLE_WRAP_POSTPROC
#endif
…
/* HCI_DISCONNECT wrapper function */
tBleStatus hci_disconnect( uint16_t Connection_Handle,
uint8_t Reason )
{
BLE_WRAP_HCI_DISCONNECT_PREPROC( );
tBleStatus status = HCI_DISCONNECT( Connection_Handle,
Reason );
BLE_WRAP_HCI_DISCONNECT_POSTPROC( );
return status;
}
Application example:
/* User can define the specific macros to call their own functions */
/* HCI_DISCONNECT pre-processing macro */
#define BLE_WRAP_HCI_DISCONNECT_PREPROC user_disconnect_preproc()
/* HCI_DISCONNECT post-processing macro */
#define BLE_WRAP_HCI_DISCONNECT_POSTPROC user_disconnect_postproc()
[OR]
/* User can define the generic macros to call their own functions */
#define BLE_WRAP_PREPROC user_preproc()
#define BLE_WRAP_POSTPROC user_postproc()
3.3.2.2. Commands and data sending
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 functions can be found in include/auto/ble_hci_le.h file.
The ACI commands for GAP functions can be found in include /auto/ble_gap_le.h file.
The ACI commands for GATT functions can be found in include /auto/ble_gatt_le.h file.
The ACI commands for HAL functions can be found in include /auto/ble_hal_aci.h file.
The ACI commands for L2CAP functions can be found in include /auto/ble_l2cap_le.h file.
Also, it exists a way to use the ACI/HCI commands without using the BLE Wrapper. Those interfaces have the same name as the one listed before, but in uppercase: e.g. HCI Reset command is “HCI_RESET” instead of “hci_reset”.
Those functions can be found in include /auto/ble_raw_api.h file.
Example:
// Send HCI Reset command
tBleStatus reset_status = hci_reset();
// Send HCI Reset command without using the BLE Wrapper
tBleStatus reset_status = HCI_RESET();
// Send ACI GATT delete include service command
uint16_t Serv_Handle = 0x2456;
uint16_t Include_Handle = 0x8795;
tBleStatus gatt_status = aci_gatt_del_include_service(Serv_Handle, Include_Handle);
3.3.2.3. Asynchronous events and data reception
To handle ACI/HCI events in its application, the user can choose between two different methods:
1- “FIFO event handling”
Handle the ACI/HCI events through the BLE Wrapper callback functions (listed in include/auto/ble_events.h file).In the “BLECB_Indication” function, it is required to push the event data into a FIFO. Then, it is possible to call the “BLE_EventProcess” function each time an event is popped from the FIFO.The “BLE_EventProcess” function calls the dedicated event callback. To handle the event, its dedicated callback needs to be redefined (e.g. “hci_disconnection_complete_event” callback)
2- “Raw event handling”
Handle the ACI/HCI event directly when the BLE Stack raises it without using the BLE Wrapper. It requires to redefine the dedicated event callbacks (e.g. “HCI_DISCONNECTION_COMPLETE_EVENT” callback).If an event is handled in its dedicated callback, the event cannot be handled in the BLECB_Indication callback anymore.
Based on its own application scenario, the user should identify the required Bluetooth® LE events to be detected and handled and the application ‘s specific actions as a response to such events.
When implementing a Bluetooth® LE application, the most common and widely used Bluetooth® LE events are the ones related to the discovery, connection, terminate procedures, services and characteristics discovery procedures, attribute modified events on a GATT server and attribute notification/ indication events on a GATT client.
There is one callback per event. All callback functions can be found in include/auto/ble_events.h (for method 1) and include /auto/ble_raw_api.h (for method 2).
Example:
tBleStatus hci_disconnection_complete_event(uint8_t Status, uint16_t Connection_Handle, uint8_t Reason)
{
/* USER CODE BEGIN */
// What to do when the device is disconnected.
/* USER CODE END */
}
Known limitation: In “LL only” mode or when using Direct Mode for the event callback, the RAM containing the reported data doesn’t support unaligned access. In these cases, it is advised to use the ble_memcpy/ble_memset/ble_memcmp functions (declared in "mem_intf.h" from link layer libraries) instead of memcpy/memset/memcmp functions when accessing those data.
4. Bluetooth® LE Stack Porting
The Bluetooth® LE stack uses some generic HW features but lets the application 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 BLE stack.
- Timer: used by several components of the BLE stack.
- AES: Advanced Encryption Standard used by the security manager layer of the BLE stack.
- PKA: Public Key Accelerator used by the controller in the BLE stack.
- RNG: Random Number Generation used by the controller in the BLE stack.
4.1. Bluetooth® LE platform initialization
| BLEPLAT_Init function | ||||||
|---|---|---|---|---|---|---|
|
This function is called by the Bluetooth® LE stack when it is initialized or reset (via hci_reset). The user shall call here the functions to reset the Timer, AES, PKA, NVM and RNG needed for the Bluetooth® LE stack.
The user must implement the functions mentioned below that are called by the Bluetooth® LE stack at runtime.
4.2. Bluetooth® LE platform functions
All the BLEPLAT functions are called from the Bluetooth® LE stack process or commands. Those functions shall return one of the following status values:
| BLEPLAT functions' returns | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
4.2.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.2.2. Timer functions
The timer functions are used by the Bluetooth® LE stack to handle all procedures which are time dependent.
The timer should have an accuracy of 1 ms and it is recommended to be able to count up to 24 hours.
| BLEPLAT Timer functions | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
4.2.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.2.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.2.5. RNG functions
This function is called by the Bluetooth® LE stack to retrieve “n” x 32*bit words of random values.
| BLEPLAT RNG function | ||||||
|---|---|---|---|---|---|---|
|
5. References
STM32WBA_BLE_Wireless_Interface.html