STM32WBA Bluetooth® LE Stack Integration

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
Acronym Definition HCI Host Controller interface ACI Application Controller Interface N/A Not Applicable

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
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

Configuration FULL = Host Stack + ST LL Controller (stm32wba_ble_stack_full) BASIC = Host Stack + ST LL Controller Basic Feature (stm32wba_ble_stack_basic) LL_ONLY = ST LL Controller Only (stm32wba_ble_stack_llo) LL_ONLY_BASIC = ST LL Controller Only Basic Feature (stm32wba_ble_stack_llobasic) Link Layer library dependency LinkLayer_BLE_Full_lib LinkLayer_BLE_Basic_lib LinkLayer_BLE_Full_lib LinkLayer_BLE_Basic_lib Advertising Certified Certified Certified Certified Scanning Certified Certified Certified Certified Slave Connection Certified Certified Certified Certified Data length extension Certified Certified Certified Certified Privacy Certified Certified Certified Certified LE Encryption Certified Certified Certified Certified Legacy Pairing, LE secure connections Certified Certified Certified Certified Master Connection Certified Certified Certified Certified 2Mbit Certified Certified Certified Certified Long Range Certified Certified Certified Certified Channel Selection Algorithm #2 Certified Certified Certified Certified Direct Test Mode Certified Certified Certified Certified Config HCI only Certified Not Supported Certified Certified Extended Advertising Certified Not Supported Certified Not Supported Periodic Advertising Certified Not Supported Certified Not Supported AOA/AOD Enabled Not Supported Enabled Not Supported Periodic Sync Transfer Certified Not Supported Certified Not Supported Connected Isochronous Enabled Not Supported Enabled Not Supported Isochronous Broadcaster Enabled Not Supported Enabled Not Supported Isochronous Synchronized Enabled Not Supported Enabled Not Supported LE Power Control Enabled Not Supported Enabled Not Supported GATT Client Certified Certified N/A N/A Enhanced ATT Enabled Not Supported N/A N/A LE L2CAP Connection Oriented channel Certified Not Supported N/A N/A GATT Caching Enabled Not Supported N/A N/A Number of Links 20 20 20 20

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.

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
Functions Parameters Return Value BleStack_Init BleStack_init_t* init_params_p tBleStatus

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

BleStack_init_t parameters Definition Value uint16_t numAttrRecord Maximum number of attribute records related to all the required characteristics (excluding the services) that can be stored in the GATT database, for the specific Bluetooth® LE user application. Value = <number of user attributes> + 9 Min value = 9 Max value: depending on the GATT database defined by the user application. uint16_t numAttrServ Defines the maximum number of services that can be stored in the GATT database. Note that the GAP and GATT services are automatically added at initialization so this parameter must be the number of user services increased by two. Value = <number of user services> + 2 Min value = 2 Max value: depending on the GATT database defined by the user application. uint16_t attrValueArrSize Size of the storage area for the attribute values. By default, two services are present and must be included, with dedicated characteristics: Generic access service: service UUID 0x1800, with its three mandatory characteristics: Device name UUID 0x2A00. Appearance UUID 0x2A01. Peripheral preferred connection parameters. UUID 0x2A04. Generic attribute service. UUID 0x1801, with one optional characteristic: Service changed UUID 0x2A05. Each characteristic contributes to the attrValueArrSize value as follows: Characteristic value length plus: 5 bytes if characteristic UUID is 16 bits 19 bytes if characteristic UUID is 128 bits 2 bytes if characteristic has a server configuration descriptor 2 bytes * NUM_OF_LINKs if the characteristic has a client configuration descriptor 2 bytes if the characteristic has extended properties Depends on the number of attributes used by the application. uint8_t numOfLinks Maximum number of simultaneous connections that the device will support. Min value: 1 Max value: 20 uint8_t prWriteListSize Maximum number of supported “prepare ATT write request”. Value defined by the macro: DIVC (max_char_size, default_att_mtu - 5) * 2 max_char_size: Maximum characteristic’s value size BLE_DEFAULT_ATT_MTU = 23 uint8_t mblockCount Number of allocated memory blocks for the Bluetooth® LE stack. Value defined by the macro: BLE_MBLOCKS_CALC (PREP_WRITE_LIST_SIZE, MAX_ATT_MTU, NUM_LINKS) + MBLOCK_COUNT_MARGIN) With: PREP_WRITE_LIST_SIZE defined by the parameter prWriteListSize. MAX_ATT_MTU defined by the attMtu parameter. NUM_LINKS defined by the numOfLinks parameter. MBLOCK_COUNT_MARGIN the memory margin to take. uint16_t attMtu Maximum ATT MTU size supported. Min value: 23 Max value: 512 uint16_t max_coc_mps Used in APIs in l2cap_coc.c to process with a L2CAP connection, send/receive data… Maximum value of the connection-oriented channel Maximum Payload Size. Min value: 23 Max value: 248 uint8_t max_coc_nbr Used in APIs in l2cap_coc.c to process with a L2CAP connection, send/receive data… Maximum number of connection-oriented channels. Min value: 0 Max value: 64 uint8_t max_coc_initiator_nbr Used in APIs in l2cap_coc.c to process with a L2CAP connection, send/receive data… Maximum number of connection-oriented channels in initiator mode. Min value:0 Max value: max_coc_nbr uint8_t* bleStartRamAddress Start address of the RAM buffer allocated for Bluetooth® LE stack library. It must be a 32bit aligned RAM area. uint32_t total_buffer_size Size of the RAM buffer allocated for Bluetooth® LE stack library. Value defined by the macro: BLE_TOTAL_BUFFER_SIZE (NUM_LINKS, MBLOCK_COUNT) With: NUM_LINKS: the maximum number of links defined by the parameter numOfLinks. MBLOCK_COUNT: the number of allocated memory blocks, defined by the parameter mblockCount. uint8_t* bleStartRamAddress_GATT Start address of the RAM buffer allocated for GATT database. It must be a 32bit aligned RAM area. uint32_t total_buffer_size_GATT Size of the RAM buffer allocated for GATT database. Value defined by the macro: BLE_TOTAL_BUFFER_SIZE_GATT (NUM_ATTR_RECORD, NUM_ATTR_SERV, ATTR_VALUE_ARR_SIZE) With: NUM_ATTR_RECORD: defined by the parameter numAttrRecord. NUM_ATTR_SERV: defined by the parameter numAttrServ. ATTR_VALUE_ARR_SIZE: defined by the parameter attrValueArrSize. uint16_t options Options flags. Bitmap of the "BLE_OPTIONS_..." definitions: bit 0:   1: LL only  0: LL + host bit 1:   1: no service change desc.  0: with service change desc. bit 2:   1: device name Read-Only  0: device name R/W bit 3:   1: extended adv supported  0: extended adv not supported bit 5:   1: Reduced GATT db in NVM  0: Full GATT db in NVM bit 6:   1: GATT caching is used  0: GATT caching is not used bit 7:   1: LE Power Class 1  0: LE Power Class 2-3 bit 8:   1: appearance Writable  0: appearance Read-Only bit 9:   1: Enhanced ATT supported  0: Enhanced ATT not supported other bits: reserved BLE_OPTIONS_LL_ONLY = 0x0001U, BLE_OPTIONS_NO_SVC_CHANGE_DESC = 0x0002U, BLE_OPTIONS_DEV_NAME_READ_ONLY = 0x0004U, BLE_OPTIONS_EXTENDED_ADV = 0x0008U, BLE_OPTIONS_REDUCED_DB_IN_NVM = 0x0020U, BLE_OPTIONS_GATT_CACHING = 0x0040U, BLE_OPTIONS_POWER_CLASS_1 = 0x0080U, BLE_OPTIONS_APPEARANCE_WRITABLE = 0x0100U, BLE_OPTIONS_ENHANCED_ATT = 0x0200U uint32_t debug Debug flags BLE_DEBUG_RAND_ADDR_INIT = 0x00000010UL

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
Functions Parameters Return Value BleStack_Process None BLE_SLEEPMODE_RUNNING(0): -> BleStack_Process must be executed. BLE_SLEEPMODE_CPU_HALT(1): -> BleStack_Process does not have to be executed.

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 could 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 modes

We have two ways to send commands and receive events in ST’s Bluetooth^® LE stack: Transparent Mode or Direct Call 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
Functions Parameters Return Value BleStack_Request uint8_t* buffer [IN/OUT]: Buffer of bytes in the Bluetooth® LE standard format HCI/ACI command packet or ACL data packet. The response packet is returned in the same buffer and the size (in bytes) of the response is given by the function’s return value. The size (uint16_t) of the response packet returned in the buffer parameter.

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,<br>
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];

3.3.2. Direct mode for commands and data sending

Instead of calling BleStack_Request as in transparent mode, the ACI/HCI commands can be called by using dedicated functions for each command.
Please refer to the document STM32WBA_BLE_Wireless_Interface.html
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.

Example:

// Send HCI Reset command
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.3. Bluetooth^® LE Asynchronous ACI/HCI events and data reception

To handle ACI/HCI events in its application, the user can choose between two different methods:

1. Use event callbacks framework (via dedicated event callback)
2. Use nested "switch case" event handler (via the BLECB_Indication callback)

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.

3.3.3.1. ACI/HCI dedicated events callbacks

There is one callback per event. All callback functions can be found in include/auto/ble_events.h file.
If an event is handled in its dedicated callback, the event cannot be handled in the BLECB_Indication callback anymore.

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 */
}

3.3.3.2. BLECB_Indication callback

All events which are not handled in their dedicated callback 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
Functions Parameters Return Value BLECB_Indication const uint8_t* data: The data buffer uint16_t length: The length of the data buffer const uint8_t* ext_data: The extended data buffer. This buffer is used only for ISO data and ACL data events uint16_t ext_length: The length of the extended data buffer uint8_t: Up to the user to define the return values.

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;
}

6. Wiki syntax examples

Bluetooth® LE Health Thermometer Service specification
Service Characteristic Property UUID size +1 Health Thermometer Service 0x1809 +1 Temperature Measurement Indicate 0x2A1C 13 Temperature Type Read 0x2A1D 1 Intermediate Temperature Notify 0x2A1E 13 Measurement Interval Read,Write,Indicate 0x2A21 2 Device Information Service 0x180A Manufacturer Name String Read 0x2A29 32 Model Number String Read 0x2A24 32 System ID Read 0x2A23 8