1. Setup
Projects are available into STM32CubeWB[1] package from version v1.14.0.
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 an application:
- - BLE_p2pServer_Ext application
- - BLE_p2pClient_Ext application
New Scatter file to use (provided in M4 projects) :
For STM32BW55 :
The RAM_A shared range shall be reduced to memory range [0x20030000:0x200307FF]
The Mail-box buffers(MB_MEM1, MB_MEM2) shall be located in RAM_B shared defined in memory range [0x20038000:0x2003A7FF]
The RAM_B shared shall be addded to Total_RAM_region
2. Applications description
3. Feature parameters
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.
- 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. Depending on your application you can use for instance:
- STM32WB55
- -3 x 1650
- -8 x 200
- STM32WB15
- -2 x 1650
- -8 x 200
Note number of link must be at least up to the number of advertising set supported.
4. Auxiliary packet introduction
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 |
|---|
5. Advertising Extended NoConn_NoScan
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 |
|---|
6. Advertising Extended 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 |
|---|
7. Advertising Extended 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 |
|---|
8. ACI-HCI Messages
8.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 |
8.2. Events
| Command | 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 |
9. Implementation in BLE_p2pServer_Ext application
A new file has been added (compared to BLE_p2pServer application) : adv_ext_app.c which includes the definition of
ADV_EXT_Config() and ADV_EXT_Start() functions which are called at the end of APP_BLE_Init()
ADV_EXT_Config :
4 types of extended advertising sets are defined :
- Extended scannable
- Extended connectable
- Extended no connectable, no scannable
- Legacy (extended API)
Modifications can be done here to initialize different extended advertising sets
ADV_EXT_Start :
Reads the number of supported advertising sets (defined with CFG_BLE_MAX_ADV_SET_NBR)
Reads the max data number of advertising sets (defined with CFG_BLE_MAX_ADV_DATA_LEN)
- Sets the extended advertising configuration for advertising sets (aci_gap_adv_set_configuration)
- Sets random address if necessary
- Fills extended advertising data in adv_set_param table (ADV_EXT_Build_Data)
- Prepare aci_gap_adv_set_scan_resp_data commands to fill scan response data or aci_gap_adv_set_adv_data to fill extended advertising PDUs
At aci/hci level, the command should not exceed 255 bytes, data to be sent must be cut into slices of 251 bytes (in ADV_EXT_Set_Data)
The aci commands are sent with a parameter (adv_operation) that could be equal to
- HCI_SET_ADV_DATA_OPERATION_FIRST
- HCI_SET_ADV_DATA_OPERATION_INTERMEDIATE
- HCI_SET_ADV_DATA_OPERATION_LAST
9.1. Advertising set configuration
A structure holds parameters to create an advertising set, following parameters are available:
- uint8_t enable
- Adv_Set_t
- uint8_t Advertising_Handle Handle to identify the set
- uint16_t Duration Duration in 10ms unit, 0 is no duration
- uint8_t Max_Extended_Advertising_Events Number of events max, 0 is no maximun
- uint8_t* data Pointer to the data set in the payload
- uint16_t data_len Number of data to use
- uint8_t sid ID of the advertising set
- uint16_t property Mask to define the property of the set, connectable / scannable / legacy
- uint16_t interval_min Low limit of adv interval
- uint16_t interval_max High limit of adv interval
- uint8_t tx_power Advertising TX power. Units: dBm
- uint8_t adv_channels Advertising channel map
- 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
- char username[30] Complete local name
9.2. 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
9.3. Commands sequence
| Commands sequence |
|---|
10. Implementation in P2P Client extended
Application demonstrates the scan of advertising with extended API’s
Application must run with BLE full extended stack
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 the 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.
- Adv payload is analysed to print COMPLETE_LOCAL_NAME AD element.
