STM32WB Bluetooth® LE – advertising extensions


1. Applications description

Connectivity 2 devices 2.png

1.1. Setup

Projects are available into STM32CubeWB[1] package from version v1.14.0.

To run these applications you need 2 of following nucleo boards:

  • Flash the wireless stack according to your device:
  • stm32wb5x_BLE_Stack_full_extended_fw.bin (@0x080c7000 for CubeWB v1.14.0)
  • stm32wb1x_BLE_Stack_full_extended_fw.bin (@0x08019800 for CubeWB v1.14.0)
  • Flash applications BLE_p2pServer_Ext and BLE_p2pClient_Ext on your board couple.

These applications use specific linker files, see Wireless Stack Information Wiki page for more information.

1.2. BLE_p2pServer_Ext application

The application is based on BLE_p2pServer application.
In this application you can configure up to eight advertising sets.
Additional files adv_ext_app.c and adv_ext_app.h have been added to support the new feature, and are composed of the below functions:

  • ADV_EXT_Config() initializes advertising data, using predefined table that can be updated according to your needs.
  • ADV_EXT_Start() performs the configuration of advertising sets in several steps, details are displayed in the console.
    • reads number of set and memory parameters supported by BLE stack configuration
    • performs the configuration of each sets using function aci_gap_adv_set_configuration()
    • sets a random address if requested using function hci_le_set_advertising_set_random_address()
    • builds the data to advertise if no data provided, function ADV_EXT_Build_data()
    • transfers to the stack data to advertise, function ADV_EXT_Set_data()
      • aci_gap_adv_set_adv_data() function is used except for scannable sets where aci_gap_adv_set_scan_resp_data() is used
      • data has to be sent by slice of 251 bytes max
      • each slice has to be tagged HCI_SET_ADV_DATA_OPERATION_FIRST / INTERMEDIATE / LAST or COMPLETE
    • enables the advertising set with function aci_gap_adv_set_enable()

1.2.1. Advertising set configuration

A structure of type Adv_Set_Param_t holds parameters to define an advertising set, following parameters are available:

Type Name Description
uint8_t enable 0 to disable advertising set
uint8_t Adv_Set_t->Advertising_Handle Handle to identify the set
uint8_t Adv_Set_t->Duration Duration in 10ms unit, 0 is no duration
uint8_t Adv_Set_t->Max_Extended_Advertising_Events Number of events max, 0 is no maximun
uint8_t* data Pointer to the data set in the payload, if null data is generated
uint16_t data_len Number of data to use
uint8_t* username[] Complete local name
uint8_t sid ID of the advertising set
uint16_t property Mask to define set properties, connectable/scannable/legacy
uint16_t interval_min Low limit of advertising interval
uint16_t interval_max High limit of advertising interval
int8_t tx_power Advertising TX power in dBm
uint8_t adv_channels RF channel map selection
uint8_t address_type Own address type
uint8_t peer_address_type Address type of the peer device
uint8_t* p_peer_address Address of the peer device

1.3. BLE_p2pClient_Ext application

The application demonstrates scanning of advertising with extended API’s.
The output is printed over ST-Link UART @115200 bauds.
Nucleo buttons offer the following functions:

  • SW1: stop the scan and connect to a server if any detected.
  • SW2: toggle a filter on extended result only.
  • SW3: stop/start scanning, blue LED reflects scanning status.

Scanning is started using aci_gap_start_general_discovery_proc() function.
Scanning is stopped using aci_gap_terminate_gap_proc() function.
Scan events are received, analysed and printed on the console.

  • HCI_LE_EXTENDED_ADVERTISING_REPORT_SUBEVT_CODE are received.
  • payload is analysed to print COMPLETE_LOCAL_NAME AD element.
BLE_p2pClient_Ext console output sample
Connectivity scanner2.png

2. Feature specific configuration

An application has to give some specific parameters to the stack to use extended advertising. These parameters are located in app_conf.h file.

  • CFG_BLE_OPTIONS mask must have SHCI_C2_BLE_INIT_OPTIONS_EXT_ADV and SHCI_C2_BLE_INIT_OPTIONS_CS_ALGO2 defined.
  • Having two parameters allows to define the capacity of the stack for this feature, transmitted into ble_init_cmd_packet stucture.
    • CFG_BLE_MAX_ADV_SET_NBR is the max number of advertising set supported, up to 8 on STM32WB5x and up to 3 on STM32WB1x.
    • CFG_BLE_MAX_ADV_DATA_LEN is the max data length of each advertising set, up to 1650.

These 2 last parameters have limitations due to memory constraints, the table below gives the payload size max by adv set count.

Payload bytes by adv set count 1 2 3 4 5 6 7 8
STM32WB5x 1650 1650 1650 1035 621 414 207 207
STM32WB1x 1650 828 414 n.a. n.a. n.a. n.a. n.a.


Note: the number of links must be at least equal to the number of advertising set supported.

3. Advertising auxiliary packets

The PDU payload of primary advertising channels can vary in length from 6 to 37 bytes (6 bytes for addresses, remaining 31 bytes for data). In Extended Advertising, secondary advertising channels are used to reach up to 1650 bytes of payload.

The advertising packets on primary channels contain the information in which secondary advertising channel and the offset to the start time the auxiliary data is transmitted.

Aux packet
Connectivity Aux packet.png

3.1. No Connectable No Scannable

Primary and auxiliary segments-NO SCANNABLE/NO CONNECTABLE Segments timing implementation:

  • Both primary/auxiliary segments belong to the same scheduled slot for all fragmentations policy (length depends on data size)
  • Channel of AUX_ADV_IND (+request and response) are randomly selected when set is ACTIVATED
  • Chained channels follow a hopping of 1 increment
Example of no scannable/no connectable set
Connectivity noscan noconn 2.png

3.2. Scannable

Primary and auxiliary segments-SCANNABLE The scannable undirected event type using the ADV_EXT_IND PDU allows any scanner to respond with a scan request to receive scan response data on the secondary advertising physical channel.

  • Only Auxiliary segment could be scanned, and Data could only be contained in the scan response.
  • A scanner may send a scan request using the AUX_SCAN_REQ PDU on the same secondary advertising channel index as the received AUX_ADV_IND
Example of scannable set
Connectivity scannable 2.png

3.3. Connectable

Primary and auxiliary segments- CONNECTABLE The connectable directed advertising event type using ADV_EXT_IND allows an initiator to respond with a connect request on the secondary advertising physical channel to establish an ACL connection

  • After every AUX_ADV_IND PDU related to this event, it sends the advertiser that should listen to AUX_CONNECT_REQ PDUs on the same secondary advertising channel index.
Example of connectable set
Connectivity Connectable 2.png

4. Advertising sets building

The creation of an advertising set is done thanks to two new added functions:

  • ADV_EXT_Config() : initializes advertising data table (fill adv_set_param[] table to provide advertising data base)

and

  • ADV_EXT_Start() : performs the configuration of advertising sets in several steps
    • reads the number of supported advertising sets
    • reads the advertising sets data length
    • sets the extended advertising configuration
    • sets the extended advertising random address
    • provides default advertising data if necessary using ADV_EXT_Build_data()
    • transmits advertising data to the stack using ADV_EXT_Set_data()

5. Commands sequence

Commands sequence
Connectivity cmd sequence.png

6. ACI-HCI Messages

A detailed description of all stack messages are available in the wireless stack interface documentation [2]

6.1. Commands

Command Comment Use in application
aci_gap_adv_set_configuration Set the extended advertising configuration for one advertising set BLE_p2pServer_Ext
aci_gap_adv_set_adv_data Set the data used in extended advertising PDUs that have a data field BLE_p2pServer_Ext
aci_gap_adv_set_scan_resp_data Provide scan response data used during extended advertising BLE_p2pServer_Ext
aci_gap_adv_set_enable Enable or disable one or more extended advertising sets BLE_p2pServer_Ext
hci_le_read_maximum_advertising_data_length read the maximum length of data supported by the Controller for use as advertisement data or scan response data in an extended advertising event BLE_p2pServer_Ext
hci_le_read_number_of_supported_advertising_sets read the maximum number of advertising sets supported by the Controller at the same time during extended advertising BLE_p2pServer_Ext
aci_gap_adv_set_random_address Set the random device address of an advertising set configured to use specific random address BLE_p2pServer_Ext
aci_gap_adv_remove_set Remove an advertising set from the controller Not used
aci_gap_adv_clear_sets Aci_gap_adv_clear_sets Not used
hci_le_set_extended_scan_parameters set the extended scan parameters to be used on the advertising physical channels BLE_p2pClient_Ext
hci_le_set_extended_scan_enable enable or disable extended scanning BLE_p2pClient_Ext

6.2. Events

Event Comment Use in applications
hci_le_extended_advertising_report_event Indicate that a Bluetooth device has responded to an active scan or has broadcast advertisements that were received during a passive scan BLE_p2pClient_Ext
hci_le_advertising_set_terminated_event Indicate that the Controller has terminated advertising in the advertising sets specified by the Advertising_Handle parameter Not used
hci_le_scan_request_received_event Indicate that a SCAN_REQ PDU or an AUX_SCAN_REQ PDU has been received by the advertiser BLE_p2pClient_Ext
hci_le_scan_timeout_event Indicates that scanning has ended because the duration has expired Not used

7. References