General Description

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

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...

Function Documentation

◆ wiced_bt_start_advertisements()

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 was set for an earlier advertisement. To attempt an UNDIRECTED_ADV after a DIRECTED_ADV, refer to instructions in note 1.

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_bt_ble_get_current_advert_mode()

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_set_raw_advertisement_data()

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_ble_build_raw_advertisement_data()

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_type	adveritsement type
[in]	p_type_data	advertisement 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.

◆ wiced_bt_ble_check_advertising_data()

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_get_next_adv_entry()

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_btm_ble_update_advertisement_filter_policy()

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_policy advertising filter policy

Returns: TRUE if successful

◆ wiced_bt_ble_set_adv_tx_power()

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_bt_ble_read_adv_tx_power()

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_bt_ble_set_raw_scan_response_data()

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

◆ wiced_bt_ble_observe()

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_bt_ble_scan()

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_bt_ble_get_current_scan_state()

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

◆ wiced_bt_ble_update_scanner_filter_policy()

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_policy scanning filter policy

Returns: void

General Description

Functions

Function Documentation

◆ wiced_bt_start_advertisements()

◆ wiced_bt_ble_get_current_advert_mode()

◆ wiced_bt_ble_set_raw_advertisement_data()

◆ wiced_bt_ble_build_raw_advertisement_data()

◆ wiced_bt_ble_check_advertising_data()

◆ wiced_bt_ble_get_next_adv_entry()

◆ wiced_btm_ble_update_advertisement_filter_policy()

◆ wiced_bt_ble_set_adv_tx_power()

◆ wiced_bt_ble_read_adv_tx_power()

◆ wiced_bt_ble_set_raw_scan_response_data()

◆ wiced_bt_ble_observe()

◆ wiced_bt_ble_scan()

◆ wiced_bt_ble_get_current_scan_state()

◆ wiced_bt_ble_update_scanner_filter_policy()