STM32WB Bluetooth® LE – advertising extensions

1. Applications description

1.1. Setup

Projects are available into STM32CubeWB package from version v1.14.0.

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

• P-NUCLEO-WB55
• NUCLEO-WB15CC

• 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

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

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

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

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

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

6. ACI-HCI Messages

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

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