Scanning

Functions
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)
	This API allows the device to register a callback to receive connectable ADV packets from peripheral devices. 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 API allows the device to register a callback to receive both connectable and non-connectable ADV packets. More...
wiced_bt_ble_scan_type_t	wiced_bt_ble_get_current_scan_state (void)
	Returns the current scan state that was set using wiced_bt_ble_scan. More...
uint8_t *	wiced_bt_ble_check_advertising_data (uint8_t *p_adv, wiced_bt_ble_advert_type_t type, uint8_t *p_length)
	After receiving ADV data from another device using wiced_bt_ble_scan or wiced_bt_ble_observe, this API can optionally be used to parse the received ADV data. More...
wiced_bool_t	wiced_bt_ble_update_scanner_filter_list (wiced_bool_t add, wiced_bt_device_address_t remote_bda, wiced_bt_ble_address_type_t addr_type)
	Add or remove a device from the scanner Filter Accept List. More...
void	wiced_bt_ble_update_scanner_filter_policy (wiced_bt_ble_scanner_filter_policy_t scanner_policy)
	Controls the use of the scanner Filter Accept List. More...

Detailed Description

Function Documentation

uint8_t* wiced_bt_ble_check_advertising_data	(	uint8_t *	p_adv,
		wiced_bt_ble_advert_type_t	type,
		uint8_t *	p_length
	)

After receiving ADV data from another device using wiced_bt_ble_scan or wiced_bt_ble_observe, this API can optionally be used to parse the received ADV data.

For example, if the application wants to check for the existence of an ASCII string name contained in the ADV packet, it would pass the value BTM_BLE_ADVERT_TYPE_NAME_COMPLETE into the 'type' param. If the ADV packet contains the proper field, the function will return a pointer to the ASCII string within the given ADV packet.

Refer to wiced_bt_ble_scan header for sample code using this API.

Parameters

[in]	p_adv	pointer to raw ADV data received
[in]	type	ADV data type to parse
[out]	p_length	if found, length of data, else NULL

Returns

• If found, pointer to start of requested advertisement data.
• NULL if requested data type not found.

wiced_bt_ble_scan_type_t wiced_bt_ble_get_current_scan_state

(

void

)

Returns the current scan state that was set using wiced_bt_ble_scan.

Parameters

void

Returns

• BTM_BLE_SCAN_TYPE_NONE no scan running
• BTM_BLE_SCAN_TYPE_HIGH_DUTY high duty cycle scan
• BTM_BLE_SCAN_TYPE_LOW_DUTY low duty cycle scan

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 API allows the device to register a callback to receive both connectable and non-connectable ADV packets.

It is fundamentally the same as the API wiced_bt_ble_scan, except that the scan results are filtered to allow non-connectable packets. Furthermore, the scan parameters used by the observe API are the 'low_duty' parameters set in wiced_bt_cfg_settings_t, which is passed to wiced_bt_stack_init.

Refer to wiced_bt_ble_scan for an example of the callback to be used.

Parameters

[in]	start	WICED_TRUE==start, WICED_FALSE==stop
[in]	duration	num_seconds to scan
[in]	p_scan_result_cback	callback to receive packets asynchronously

Returns

• WICED_SUCCESS
• WICED_ERROR

Note

This API should not be used at the same time as 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
	)

This API allows the device to register a callback to receive connectable ADV packets from peripheral devices.

It is fundamentally the same as the API wiced_bt_ble_observe, except that the scan results are filtered to only allow connectable packets. The scan interval, window, duration, and type (active or passive), are initialized in wiced_bt_cfg_settings_t upon calling the stack initialization API (wiced_bt_stack_init). The packets received in the callback can be limited to a small, known set of devices using wiced_bt_ble_update_scanner_filter_policy.

Below is an example of how to start receiving scan results in a callback and print the name of the advertised device if found in the received packet:

void scan_cback( wiced_bt_ble_scan_results_t *scan_res, uint8_t *adv_data )
{
    uint8_t length;
    uint8_t *p_data;

    if ( p_scan_result )
    {
        p_data = wiced_bt_ble_check_advertising_data( p_adv_data,
            BTM_BLE_ADVERT_TYPE_NAME_COMPLETE, &length );

        if(length)
        {
            WICED_BT_TRACE("%B %s RSSI: %i\r\n",
                p_scan_result->remote_bd_addr, (char *)p_data,
                p_scan_result->rssi );
        }
        else
        {
            WICED_BT_TRACE("%B UNK RSSI: %i\r\n",
                p_scan_result->remote_bd_addr, p_scan_result->rssi );
        }
    }
    else
    {
        WICED_BT_TRACE( "Scan completed\r\n" );
    }
}

{
    wiced_bt_ble_scan( BTM_BLE_SCAN_TYPE_HIGH_DUTY, WICED_TRUE, scan_cback);
}

Parameters

[in]	scan_type	BTM_BLE_SCAN_TYPE_NONE: disable scan BTM_BLE_SCAN_TYPE_HIGH_DUTY: use scan params prefixed high_duty_conn_scan_* BTM_BLE_SCAN_TYPE_LOW_DUTY: use scan params prefixed low_duty_conn_scan_*
[in]	duplicate_filter_enable	WICED_TRUE==enable, WICED_FALSE==disable
[in]	p_scan_result_cback	callback to receive packets asynchronously

Returns

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

Note

This API should not be used at the same time as wiced_bt_ble_observe.

wiced_bool_t wiced_bt_ble_update_scanner_filter_list	(	wiced_bool_t	add,
		wiced_bt_device_address_t	remote_bda,
		wiced_bt_ble_address_type_t	addr_type
	)

Add or remove a device from the scanner Filter Accept List.

Behavior of Filter Accept List is controlled by wiced_bt_ble_update_scanner_filter_policy.

Parameters

[in]	add	WICED_TRUE==add, WICED_FALSE==remove
[in]	remote_bda	address of device to add/remove
[in]	addr_type	wiced_bt_ble_address_type_t BLE_ADDR_PUBLIC BLE_ADDR_RANDOM BLE_ADDR_PUBLIC_ID BLE_ADDR_RANDOM_ID

Returns

• WICED_TRUE success
• WICED_FALSE error, transport buffer allocation failure

Note

This API cannot be used while the Filter Accept List is in use. If the device is currently scanning using the Filter Accept List, disable it before using this API.

void wiced_bt_ble_update_scanner_filter_policy

(

wiced_bt_ble_scanner_filter_policy_t

scanner_policy

)

Controls the use of the scanner Filter Accept List.

Using wiced_bt_ble_scan and wiced_bt_ble_observe will by default allow any device's advertising packets to be received (dropping directed ADV packets whose target address does not match our local address). Enabling the Filter Accept List allows the callback to only be triggered in the event that an ADV packet is scanned from a small list of devices.

Directed packets using an RPA are optionally included in the search results. The default behavior is that directed ADV will always be dropped if the target address does not match the local address. When RPA (rotating address) is in use, we must then add the option of allowing directed packets to an RPA through the filter so that the host can resolve the address (if the address resolution is occurring on the host side).

Parameters

[in]

scanner_policy

wiced_bt_ble_scanner_filter_policy_t BTM_BLE_SCAN_POLICY_ACCEPT_ADV_RSP: (default) WL OFF, drops dir to RPA BTM_BLE_SCAN_POLICY_FILTER_ADV_RSP: WL ON, drops dir to RPA BTM_BLE_SCAN_POLICY_ACCEPT_RPA_DIR_ADV_RSP: WL OFF, passes dir to RPA BTM_BLE_SCAN_POLICY_FILTER_RPA_DIR_ADV_RSP: WL ON, passes dir to RPA

Returns

void