1. Applications description
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 8 advertising sets.
Additional files adv_ext_app.c and adv_ext_app.h has been added to support the new feature, composed of functions below:
- ADV_EXT_Config() configure the advertising sets, some are predifined and you can update according to your needs.
- ADV_EXT_Start() perform the configuration in several steps, details are displayed in the console.
- read number of set and memory parameters supported by BLE stack configuration
- perform the configuration of each sets using function aci_gap_adv_set_configuration()
- set a random address if requested using function hci_le_set_advertising_set_random_address()
- build the data to advertise if no data provided, function ADV_EXT_Build_data()
- transfert 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
- enable 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 will be 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
Application demonstrates scanning of advertising with extended API’s.
The output is printed over ST-Link UART @115200 bauds.
Nucleo buttons offers 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 have 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 defines.
- 2 parameters allows to define 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, 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 number of link must be at least up 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 will be 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 shall listen for AUX_CONNECT_REQ PDUs on the same secondary advertising channel index.
| Example of connectable set |
|---|
4. Advertising set management
Creation of an advertising set is composed of 3 main steps
- Configuration using aci_gap_set_configuration() function
- Data filling with Set_ext_data() application function composed of following commands
- An operation parameter must be identified (HCI_SET_ADV_DATA_OPERATION_FIRST / INTERMEDIATE / LAST or COMPLETE)
- Compute data pointer and data length
- Finally use commands aci_gap_adv_set_scan_resp_data() for scannable else use aci_gap_adv_set_adv_data()
- Start of the advertising set using aci_gap_adv_set_enable() function
5. Commands sequence
| Commands sequence |
|---|
6. ACI-HCI Messages
Detailed descripton 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 |