Infineon Logo AIROC BTSDK v4.4 - Documentation
 
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Advertisement & Scan

This section provides functions for LE advertisement and LE scan operations. More...

Functions

wiced_result_t wiced_bt_start_advertisements (wiced_bt_ble_advert_mode_t advert_mode, wiced_bt_ble_address_type_t directed_advertisement_bdaddr_type, wiced_bt_device_address_ptr_t directed_advertisement_bdaddr_ptr)
 Start advertising. More...
 
wiced_bt_ble_advert_mode_t wiced_bt_ble_get_current_advert_mode (void)
 Get current advertising mode. More...
 
wiced_result_t wiced_bt_ble_set_raw_advertisement_data (uint8_t num_elem, wiced_bt_ble_advert_elem_t *p_data)
 Set advertisement raw data to the controller. More...
 
int wiced_bt_ble_build_raw_advertisement_data (uint8_t *p_adv, int adv_len, wiced_bt_ble_advert_type_t adv_type, uint8_t *p_type_data, uint16_t type_len)
 Write advertisement raw data to application buffer. More...
 
uint8_t * wiced_bt_ble_check_advertising_data (uint8_t *p_adv, wiced_bt_ble_advert_type_t type, uint8_t *p_length)
 Parse advertising data (returned from scan results callback wiced_bt_ble_scan_result_cback_t). More...
 
uint8_t * wiced_bt_ble_get_next_adv_entry (uint8_t *p_adv, int *p_offset, wiced_bt_ble_advert_type_t type, uint8_t *p_length)
 When multiple entry for same adv type is available in the adv data this api will help to get next entry of specified advertisement data type when there is a single instance use wiced_bt_ble_check_advertising_data. More...
 
wiced_bool_t wiced_btm_ble_update_advertisement_filter_policy (wiced_bt_ble_advert_filter_policy_t advertising_policy)
 Update the filter policy of advertiser. More...
 
wiced_result_t wiced_bt_ble_set_adv_tx_power (int8_t power, wiced_bt_dev_vendor_specific_command_complete_cback_t *p_cb)
 Command to set LE Advertisement tx power. More...
 
wiced_result_t wiced_bt_ble_read_adv_tx_power (wiced_bt_dev_cmpl_cback_t *p_cback)
 Read LE Advertisement transmit power. More...
 
wiced_bt_dev_status_t wiced_bt_ble_set_raw_scan_response_data (uint8_t num_elem, wiced_bt_ble_advert_elem_t *p_data)
 Set scan response raw data. More...
 
wiced_bt_dev_status_t wiced_bt_ble_observe (wiced_bool_t start, uint8_t duration, wiced_bt_ble_scan_result_cback_t *p_scan_result_cback)
 This function makes the device start or stop operating in the observer role. More...
 
wiced_result_t wiced_bt_ble_scan (wiced_bt_ble_scan_type_t scan_type, wiced_bool_t duplicate_filter_enable, wiced_bt_ble_scan_result_cback_t *p_scan_result_cback)
 Start LE scanning. More...
 
wiced_bt_ble_scan_type_t wiced_bt_ble_get_current_scan_state (void)
 Get current scan state. More...
 
void wiced_bt_ble_update_scanner_filter_policy (wiced_bt_ble_scanner_filter_policy_t scanner_policy)
 Update the filter policy of scanning. More...
 

Detailed Description

This section provides functions for LE advertisement and LE scan operations.

Function Documentation

int wiced_bt_ble_build_raw_advertisement_data ( uint8_t *  p_adv,
int  adv_len,
wiced_bt_ble_advert_type_t  adv_type,
uint8_t *  p_type_data,
uint16_t  type_len 
)

Write advertisement raw data to application buffer.

Note
: This API does not write data to the controller
Parameters
[in]p_adv: buffer pointer at which the raw data in p_type_data is to be written
[in]adv_len: length of the buffer pointer pointed to by p_adv, should be atleast (2 + type_len) for a successful write operation
[in]adv_typeadveritsement type
[in]p_type_dataadvertisement data of adv_type
[in]type_len: length of advertisement data at p_type_data of adv_type
Returns
length of the p_adv buffer written.
uint8_t* wiced_bt_ble_check_advertising_data ( uint8_t *  p_adv,
wiced_bt_ble_advert_type_t  type,
uint8_t *  p_length 
)

Parse advertising data (returned from scan results callback wiced_bt_ble_scan_result_cback_t).

Look for specified advertisement data type.

Parameters
[in]p_adv: pointer to advertisement data
[in]type: advertisement data type to look for
[out]p_length: length of advertisement data (if found)
Returns
pointer to start of requested advertisement data (if found). NULL if requested data type not found.
wiced_bt_ble_advert_mode_t wiced_bt_ble_get_current_advert_mode ( void  )

Get current advertising mode.

Returns
Current advertising mode (refer wiced_bt_ble_advert_mode_e)
wiced_bt_ble_scan_type_t wiced_bt_ble_get_current_scan_state ( void  )

Get current scan state.

Returns
wiced_bt_ble_scan_type_t
BTM_BLE_SCAN_TYPE_NONE Not scanning
BTM_BLE_SCAN_TYPE_HIGH_DUTY High duty cycle scan
BTM_BLE_SCAN_TYPE_LOW_DUTY Low duty cycle scan
uint8_t* wiced_bt_ble_get_next_adv_entry ( uint8_t *  p_adv,
int *  p_offset,
wiced_bt_ble_advert_type_t  type,
uint8_t *  p_length 
)

When multiple entry for same adv type is available in the adv data this api will help to get next entry of specified advertisement data type when there is a single instance use wiced_bt_ble_check_advertising_data.

Parameters
[in]p_adv: pointer to advertisement data
[in]p_offset: offset from the start of the adv data recevied, also returns next offset to start searching from
[in]type: advertisement data type to look for
[out]p_length: length of advertisement data (if found)
Returns
pointer to next requested advertisement data (if found). NULL if requested data type not found.
wiced_bt_dev_status_t wiced_bt_ble_observe ( wiced_bool_t  start,
uint8_t  duration,
wiced_bt_ble_scan_result_cback_t p_scan_result_cback 
)

This function makes the device start or stop operating in the observer role.

The observer role device receives advertising events from a broadcast device.

Note
This API uses following parameters from the configuration settings wiced_bt_cfg_ble_t::p_ble_scan_cfg,
wiced_bt_cfg_ble_scan_settings_t::low_duty_scan_interval,
wiced_bt_cfg_ble_scan_settings_t::low_duty_scan_window,
wiced_bt_cfg_ble_scan_settings_t::scan_mode,
wiced_bt_cfg_ble_scan_settings_t::scan_mode
Parameters
[in]start: TRUE to start the observer role
[in]duration: the duration for the observer role
[in]p_scan_result_cback: scan result callback
Returns
status of the operation
wiced_result_t wiced_bt_ble_read_adv_tx_power ( wiced_bt_dev_cmpl_cback_t p_cback)

Read LE Advertisement transmit power.

Note
: This API can be used to get Tx power for Legacy advertisements. It will return an error if the application is using Extended Advertisements. See Bluetool Core spec 5.2, Vol 4, Part E, section 3.1.1 Legacy and extended advertising
Parameters
[in]p_cback: Result callback (wiced_bt_tx_power_result_t will be passed to the callback)
Returns
             WICED_BT_PENDING if command issued to controller.
             WICED_BT_NO_RESOURCES if couldn't allocate memory to issue command
             WICED_BT_BUSY if command is already in progress
             WICED_BT_ILLEGAL_VALUE if the callback is NULL
wiced_result_t wiced_bt_ble_scan ( wiced_bt_ble_scan_type_t  scan_type,
wiced_bool_t  duplicate_filter_enable,
wiced_bt_ble_scan_result_cback_t p_scan_result_cback 
)

Start LE scanning.

The scan_type parameter determines what scanning parameters and durations to use (as specified by the application configuration).

Scan results are notified using p_scan_result_cback

Note
This API uses following parameters from the configuration settings of wiced_bt_cfg_ble_t::p_ble_scan_cfg,
wiced_bt_cfg_ble_scan_settings_t::high_duty_scan_interval,
wiced_bt_cfg_ble_scan_settings_t::high_duty_scan_window,
wiced_bt_cfg_ble_scan_settings_t::high_duty_scan_duration,
wiced_bt_cfg_ble_scan_settings_t::low_duty_scan_interval,
wiced_bt_cfg_ble_scan_settings_t::low_duty_scan_window,
wiced_bt_cfg_ble_scan_settings_t::low_duty_scan_duration,
wiced_bt_cfg_ble_scan_settings_t::scan_mode
Parameters
[in]scan_type: BTM_BLE_SCAN_TYPE_NONE, BTM_BLE_SCAN_TYPE_HIGH_DUTY, BTM_BLE_SCAN_TYPE_LOW_DUTY
[in]duplicate_filter_enable: TRUE or FALSE to enable or disable duplicate filtering
[in]p_scan_result_cback: scan result callback
Returns
wiced_result_t
WICED_BT_PENDING : if successfully initiated
WICED_BT_BUSY : if already in progress
WICED_BT_ILLEGAL_VALUE : if parameter(s) are out of range
WICED_BT_NO_RESOURCES : if could not allocate resources to start the command
WICED_BT_WRONG_MODE : if the device is not up.
wiced_result_t wiced_bt_ble_set_adv_tx_power ( int8_t  power,
wiced_bt_dev_vendor_specific_command_complete_cback_t p_cb 
)

Command to set LE Advertisement tx power.

Parameters
[in]power: power value in db
[in]p_cb: Result callback (wiced_bt_set_adv_tx_power_result_t will be passed to the callback)
Returns
wiced_result_t WICED_BT_PENDING if callback is not NULL. WICED_BT_SUCCESS if callback is NULL
wiced_result_t wiced_bt_ble_set_raw_advertisement_data ( uint8_t  num_elem,
wiced_bt_ble_advert_elem_t p_data 
)

Set advertisement raw data to the controller.

Application can invoke wiced_bt_start_advertisements after setting the adv data. Max length of the advertising data to be set is 31 bytes. API returns an error if the length of data being set exceeds 31 bytes

Parameters
[in]num_elem: number of ADV data element
[in]p_data: advertisement raw data
Returns
wiced_result_t
wiced_bt_dev_status_t wiced_bt_ble_set_raw_scan_response_data ( uint8_t  num_elem,
wiced_bt_ble_advert_elem_t p_data 
)

Set scan response raw data.

Parameters
[in]num_elem: number of scan response data elements
[in]p_data: scan response raw data
Returns
status of the operation
void wiced_bt_ble_update_scanner_filter_policy ( wiced_bt_ble_scanner_filter_policy_t  scanner_policy)

Update the filter policy of scanning.

Parameters
[in]scanner_policyscanning filter policy
Returns
void
wiced_result_t wiced_bt_start_advertisements ( wiced_bt_ble_advert_mode_t  advert_mode,
wiced_bt_ble_address_type_t  directed_advertisement_bdaddr_type,
wiced_bt_device_address_ptr_t  directed_advertisement_bdaddr_ptr 
)

Start advertising.

Use wiced_bt_ble_set_raw_advertisement_data to configure advertising data prior to starting avertisements. The advertisements are stopped upon successful LE connection establishment.

Note
1. Steps for undirected ADVs viz., BTM_BLE_ADVERT_UNDIRECTED_HIGH, BTM_BLE_ADVERT_UNDIRECTED_LOW, and non connectable advs viz., BTM_BLE_ADVERT_NONCONN_HIGH, BTM_BLE_ADVERT_NONCONN_LOW a) Set ADV data b) Set Scan Response data if adv type is scannable
2. if adv type is set to Directed then the stack resets any advertisement data which has been set for an earlier advertisement. Refer note 1 prior to attempting an undirected advertisement

The advert_mode parameter determines what advertising parameters and durations to use (as specified by the application configuration).

Parameters
[in]advert_mode: advertisement mode
[in]directed_advertisement_bdaddr_type: BLE_ADDR_PUBLIC or BLE_ADDR_RANDOM (if using directed advertisement mode)
[in]directed_advertisement_bdaddr_ptr: Directed advertisement address (NULL if not using directed advertisement)
Returns
status
wiced_bool_t wiced_btm_ble_update_advertisement_filter_policy ( wiced_bt_ble_advert_filter_policy_t  advertising_policy)

Update the filter policy of advertiser.

Parameters
[in]advertising_policyadvertising filter policy
Returns
TRUE if successful