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.
Acronyms definitions | ||||||||
---|---|---|---|---|---|---|---|---|
|
2. Bluetooth® LE Stack Overview
2.1. Release contents
2.1.1. Folder structure
The Bluetooth® LE stack delivery contains 3 folders as following:
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 4 Bluetooth® LE stack library variants described in the following section.
2.1.2. Library variants
The Bluetooth® LE stack library is delivered in 4 variants:
- 2 variants containing the Bluetooth® LE host stack:
- Full stack (stm32wba_ble_stack_full.a)
- Basic stack (stm32wba_ble_stack_basic.a)
- 2 variants without the Bluetooth® LE host stack (controller only):
- Link Layer Only stack (stm32wba_ble_stack_llo.a)
- Link Layer Only Basic stack (stm32wba_ble_stack_llobasic.a)
Here are the 4 Bluetooth® LE stack variants details:
- Full stack (stm32wba_ble_stack_full.a) includes the ST LL Controller and the Host Stack, and contains all the legacy stack supported features plus the extended advertising, GATT caching, 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 (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 stack (stm32wba_ble_stack_basic.a) contains only basic supported features or Bluetooth® LE legacy features without extended advertising, neither GATT caching, 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.
- Link Layer Only stack (stm32wba_ble_stack_llo.a) contains all the features supported by the full stack but doesn’t include the Host Stack (GATT, GAP and L2CAP features).
- Link Layer Only Basic stack (stm32wba_ble_stack_llobasic.a) contains all the features supported by the basic stack but doesn’t include the Host Stack (GATT, GAP and L2CAP features).
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:
Bluetooth® LE stack variants | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Note: The features “Certified” are the supported features that have been officially certified. The feature “Enabled” are the supported features that have not been certified yet.
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, i.e., 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 (i.e. it must be linked with the following libraries):
- STM32WBAxx Link Layer libraries (c.f. 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 BLE stack library was compiled with the following options in IAR® environment:
- General options:
- Byte order: Little-endian
- FPU: VFPv5 single precision
- C/C++ Compilation options
- Extra compilation options (--aeabi && --guard_calls)
- --aeabi: Used to generate AEABI-compliant object code
- --guard_calls: Used mandatory for AEABI-compliant
- Plain 'char' is unsigned.
- Extra compilation options (--aeabi && --guard_calls)
As mentioned above, the BLE stack library is AEABI compliant; The advantage of adhering to AEABI is that the BLE stack library can be linked with any other AEABI-compliant module, even modules produced by tools provided by other vendors than IAR®.
For the enum type, the IAR® C/C++ compiler will use the smallest type required to hold enum constants, 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 2 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 | |||||||
---|---|---|---|---|---|---|---|
|
3.2. Bluetooth® LE stack process
3.3. Bluetooth® LE stack modes
3.3.1. Transparent Mode
3.3.2. Direct mode for commands and data sending
3.3.3. Bluetooth® LE Asynchronous ACI/HCI events and data reception
4. Bluetooth® LE Stack Porting
4.1. Stack Porting
4.2. Bluetooth® LE platform functions
4.2.1. NVM functions
4.2.2. Timer functions
4.2.3. AES functions
4.2.4. PKA functions
4.2.5. RNG functions
5. References
6. Wiki syntax examples
Header text | Header text | Header text |
---|---|---|
Example | Example | Example |
Example | Example | Example |
Example | Example | Example |
Bluetooth® LE Health Thermometer Service specification | ||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
ST Bluetooth® LE example project directory |
---|
ST Bluetooth® LE example project directory |
---|
Bluetooth®
texte - “doc” folder contains the current document and “STM32WBA_BLE_Wireless_Interface.html” which describes the BLE Application Commands Interface (ACI) and the Host Commands Interface (HCI).
- “include” folder contains the header files of the BLE 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 BLE stack (for more details see section 4.2)
- “lib” folder contains the 4 BLE stack library variants described in the following section.
BLA BLA BLA
ST Bluetooth® LE pour Nidhal |
---|
/**
******************************************************************************
* @file STM32WB_P2P_Server.ino
* @author WBL BLE Application Team
* @brief Arduino STM32WB P2P Server Application (Custom STM)
******************************************************************************