LE (Bluetooth Low Energy)

LE (Bluetooth Low Energy) Functions. 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)
	Function wiced_bt_start_advertisements. More...
wiced_bt_ble_advert_mode_t	wiced_bt_ble_get_current_advert_mode (void)
	Function wiced_bt_ble_get_current_advert_mode. More...
wiced_result_t	wiced_bt_ble_set_raw_advertisement_data (UINT8 num_elem, wiced_bt_ble_advert_elem_t *p_data)
	Function wiced_bt_ble_set_raw_advertisement_data. 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)
	Function wiced_bt_ble_set_raw_scan_response_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)
	Function wiced_bt_ble_observe. 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)
	Function wiced_bt_ble_scan. More...
wiced_bt_ble_scan_type_t	wiced_bt_ble_get_current_scan_state (void)
	Function wiced_bt_ble_get_current_scan_state. More...
void	wiced_bt_ble_security_grant (wiced_bt_device_address_t bd_addr, uint8_t res)
	Function wiced_bt_ble_security_grant. More...
wiced_bool_t	wiced_bt_ble_data_signature (wiced_bt_device_address_t bd_addr, uint8_t *p_text, uint16_t len, wiced_dev_ble_signature_t signature)
	Function wiced_bt_ble_data_signature. More...
wiced_bool_t	wiced_bt_ble_verify_signature (wiced_bt_device_address_t bd_addr, uint8_t *p_orig, uint16_t len, uint32_t counter, uint8_t *p_comp)
	Function wiced_bt_ble_verify_signature. More...
wiced_bool_t	wiced_bt_ble_set_background_connection_type (wiced_bt_ble_conn_type_t conn_type, wiced_bt_ble_selective_conn_cback_t *p_select_cback)
	Function wiced_bt_ble_set_background_connection_type. More...
wiced_bool_t	wiced_bt_ble_update_background_connection_device (wiced_bool_t add_remove, wiced_bt_device_address_t remote_bda)
	Function wiced_bt_ble_update_background_connection_device. More...
uint8_t *	wiced_bt_ble_check_advertising_data (uint8_t *p_adv, wiced_bt_ble_advert_type_t type, uint8_t *p_length)
	Function wiced_bt_ble_check_advertising_data. More...
wiced_bool_t	wiced_bt_ble_get_security_state (wiced_bt_device_address_t bd_addr, uint8_t *p_le_sec_flags, uint8_t *p_le_key_size)
	Function wiced_bt_ble_get_security_state. More...
wiced_bool_t	wiced_bt_ble_update_advertising_filter_accept_list (wiced_bool_t add, wiced_bt_device_address_t remote_bda)
	Function wiced_bt_ble_update_advertising_filter_accept_list. More...
wiced_bool_t	wiced_btm_ble_update_advertisement_filter_policy (wiced_bt_ble_advert_filter_policy_t advertising_policy)
	Function wiced_btm_ble_update_advertisement_filter_policy. 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)
	Function wiced_bt_ble_update_scanner_filter_list. More...
void	wiced_bt_ble_update_scanner_filter_policy (wiced_bt_ble_scanner_filter_policy_t scanner_policy)
	Function wiced_bt_ble_update_scanner_filter_policy. More...
wiced_bool_t	wiced_bt_ble_clear_filter_accept_list (void)
	Function wiced_bt_ble_clear_filter_accept_list. More...
uint8_t	wiced_bt_ble_get_filter_accept_list_size (void)
	Function wiced_bt_ble_get_filter_accept_list_size. More...
wiced_result_t	wiced_bt_ble_set_adv_tx_power (INT8 power)
	Function wiced_bt_ble_set_adv_tx_power. More...
wiced_result_t	wiced_bt_ble_read_adv_tx_power (wiced_bt_dev_cmpl_cback_t *p_cback)
	Function wiced_bt_ble_read_adv_tx_power. More...
wiced_result_t	wiced_bt_ble_set_channel_classification (const wiced_bt_ble_chnl_map_t ble_channel_map)
	Function wiced_bt_ble_set_channel_classification. More...
wiced_bt_dev_status_t	wiced_bt_ble_set_phy (wiced_bt_ble_phy_preferences_t *phy_preferences)
	Function wiced_bt_ble_set_phy. More...
wiced_result_t	wiced_bt_ble_get_connection_parameters (wiced_bt_device_address_t bda, wiced_bt_ble_conn_params_t *p_conn_parameters)
	Function wiced_bt_gatt_ble_get_connection_parameters. More...
wiced_result_t	wiced_start_multi_advertisements (uint8_t advertising_enable, uint8_t adv_instance)
wiced_bt_dev_status_t	wiced_set_multi_advertisement_scan_response_data (uint8_t *p_data, uint8_t data_len, uint8_t adv_instance)
	Function wiced_set_multi_advertisement_scan_response_data. More...
wiced_result_t	wiced_set_multi_advertisement_params (uint8_t adv_instance, wiced_bt_ble_multi_adv_params_t *p_param)
	Function wiced_set_multi_advertisement_params. More...
wiced_result_t	wiced_set_multi_advertisement_data (uint8_t *p_data, uint8_t data_len, uint8_t adv_instance)
	Function wiced_set_multi_advertisement_data. More...
wiced_bool_t	wiced_bt_notify_multi_advertisement_packet_transmissions (uint8_t adv_instance, void(*clientCallback)(uint32_t), uint32_t advanceNoticeInMicroSeconds)
	Function wiced_bt_notify_multi_advertisement_packet_transmissions. More...
wiced_bt_dev_status_t	wiced_bt_ble_set_privacy_mode (wiced_bt_device_address_t remote_bda, wiced_bt_ble_privacy_mode_t privacy_mode)

Detailed Description

LE (Bluetooth Low Energy) Functions.

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
	)

Function wiced_bt_ble_check_advertising_data.

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_bool_t wiced_bt_ble_clear_filter_accept_list

(

void

)

Function wiced_bt_ble_clear_filter_accept_list.

Request clearing Filter Accept List in controller side

Returns

TRUE if request of clear is sent to controller side

wiced_bool_t wiced_bt_ble_data_signature	(	wiced_bt_device_address_t	bd_addr,
		uint8_t *	p_text,
		uint16_t	len,
		wiced_dev_ble_signature_t	signature
	)

Function wiced_bt_ble_data_signature.

Sign the data using AES128 CMAC algorith.

Parameters

[in]	bd_addr	target device the data to be signed for.
[in]	p_text	signing data
[in]	len	length of the signing data
[in]	signature	output parameter where data signature is going to be stored

Returns

TRUE if signing successful, otherwise FALSE.

wiced_result_t wiced_bt_ble_get_connection_parameters	(	wiced_bt_device_address_t	bda,
		wiced_bt_ble_conn_params_t *	p_conn_parameters
	)

Function wiced_bt_gatt_ble_get_connection_parameters.

To read LE connection parameters based on connection address received in gatt connection up indication.

Parameters

[in]	remote_bda	remote device address.
[in]	wiced_bt_ble_conn_params_t	- Connection Parameters

Returns

wiced_result_t

             WICED_BT_ILLEGAL_VALUE if p_conn_parameters is NULL.
             WICED_BT_UNKNOWN_ADDR  if device address is bad.
             WICED_BT_SUCCESS otherwise.

wiced_bt_ble_advert_mode_t wiced_bt_ble_get_current_advert_mode

(

void

)

Function wiced_bt_ble_get_current_advert_mode.

Get current advertising mode

Returns

Current advertising mode

wiced_bt_ble_scan_type_t wiced_bt_ble_get_current_scan_state

(

void

)

Function wiced_bt_ble_get_current_scan_state.

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_filter_accept_list_size

(

void

)

Function wiced_bt_ble_get_filter_accept_list_size.

Returns size of Filter Accept List size in controller side

Returns

size of Filter Accept List in current controller

wiced_bool_t wiced_bt_ble_get_security_state	(	wiced_bt_device_address_t	bd_addr,
		uint8_t *	p_le_sec_flags,
		uint8_t *	p_le_key_size
	)

Function wiced_bt_ble_get_security_state.

Get security mode 1 flags and encryption key size for LE peer.

Parameters

[in]	bd_addr	: peer address
[out]	p_le_sec_flags	: security flags (see wiced_bt_ble_sec_flags_e)
[out]	p_le_key_size	: encryption key size

Returns

TRUE if successful

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
	)

Function wiced_bt_ble_observe.

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.

Note : It will use Low Duty Scan configuration

wiced_result_t wiced_bt_ble_read_adv_tx_power

(

wiced_bt_dev_cmpl_cback_t *

p_cback

)

Function wiced_bt_ble_read_adv_tx_power.

Read LE Advertisement transmit power

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_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
	)

Function wiced_bt_ble_scan.

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.

void wiced_bt_ble_security_grant	(	wiced_bt_device_address_t	bd_addr,
		uint8_t	res
	)

Function wiced_bt_ble_security_grant.

Grant or deny access. Used in response to an BTM_SECURITY_REQUEST_EVT event.

Parameters

[in]	bd_addr	: peer device bd address.
[in]	res	: BTM_SUCCESS to grant access; BTM_MODE_UNSUPPORTED, if local device does not allow pairing; BTM_REPEATED_ATTEMPTS otherwise

Returns

None

wiced_result_t wiced_bt_ble_set_adv_tx_power

(

INT8

power

)

Function wiced_bt_ble_set_adv_tx_power.

Command to set LE Advertisement tx power

Parameters

[in]

power

: power value in db (min:-24 max:4)

Returns

wiced_result_t

wiced_bool_t wiced_bt_ble_set_background_connection_type	(	wiced_bt_ble_conn_type_t	conn_type,
		wiced_bt_ble_selective_conn_cback_t *	p_select_cback
	)

Function wiced_bt_ble_set_background_connection_type.

Set LE background connection procedure type.

Parameters

[in]	conn_type	BTM_BLE_CONN_NONE, BTM_BLE_CONN_AUTO, or BTM_BLE_CONN_SELECTIVE
[in]	p_select_cback	callback for BTM_BLE_CONN_SELECTIVE

Returns

TRUE if background connection set

wiced_result_t wiced_bt_ble_set_channel_classification

(

const wiced_bt_ble_chnl_map_t

ble_channel_map

)

Function wiced_bt_ble_set_channel_classification.

Set channel classification for the available 40 channels.

Channel n is bad = 0. Channel n is unknown = 1.

At least one channel shall be marked as unknown.

Parameters

[in]

ble_channel_map

Returns

wiced_result_t

             WICED_BT_SUCCESS if successfully initiated
             WICED_BT_NO_RESOURCES if could not allocate resources to start the command
             WICED_BT_UNSUPPORTED if does not support the feature

Set channel classification for the available 40 channels.

Channel n is bad = 0. Channel n is unknown = 1.

At least one channel shall be marked as unknown.

Parameters

[in]

ble_channel_map

Returns

wiced_result_t

             WICED_BT_SUCCESS if successfully initiated
             WICED_BT_NO_RESOURCES if could not allocate resources to start the command

wiced_bt_dev_status_t wiced_bt_ble_set_phy

(

wiced_bt_ble_phy_preferences_t *

phy_preferences

)

Function wiced_bt_ble_set_phy.

Host to configure the LE link to 1M or 2M and LE coding to be used

Parameters

[in]

wiced_bt_ble_phy_preferences_t

- Phy preferences

Returns WICED_BT_SUCCESS is returned if the request was successfully sent to HCI. WICED_BT_ILLEGAL_VALUE if phy_preferences is NULL WICED_BT_NO_RESOURCES if device address is bad BTM_NO_RESOURCES if could not allocate resources to start the command

wiced_result_t wiced_bt_ble_set_raw_advertisement_data	(	UINT8	num_elem,
		wiced_bt_ble_advert_elem_t *	p_data
	)

Function wiced_bt_ble_set_raw_advertisement_data.

Set advertisement raw data.

Parameters

[in]	data_mask	: number of ADV data element
[in]	p_data	: advertisement raw data

Returns

void

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
	)

Function wiced_bt_ble_set_raw_scan_response_data.

Set scan response raw data

Parameters

[in]	data_mask	: number of scan response data element
[in]	p_data	: scan response raw data

Returns

status of the operation

wiced_bool_t wiced_bt_ble_update_advertising_filter_accept_list	(	wiced_bool_t	add,
		wiced_bt_device_address_t	remote_bda
	)

Function wiced_bt_ble_update_advertising_filter_accept_list.

Add or remove device from advertising Filter Accept List

Parameters

[in]	add	TRUE to add; FALSE to remove
[in]	remote_bda	remote device address.

Returns

void

wiced_bool_t wiced_bt_ble_update_background_connection_device	(	wiced_bool_t	add_remove,
		wiced_bt_device_address_t	remote_bda
	)

Function wiced_bt_ble_update_background_connection_device.

This function is called to add or remove a device into/from background connection procedure. The background connection procedure is decided by the background connection type, it can be auto connection, or selective connection.

Parameters

[in]	add_remove	TRUE to add; FALSE to remove.
[in]	remote_bda	device address to add/remove.

Returns

TRUE if successful

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
	)

Function wiced_bt_ble_update_scanner_filter_list.

Add or remove device from scanner Filter Accept List

Parameters

[in]	add	TRUE to add; FALSE to remove
[in]	remote_bda	remote device address.
[in]	addr_type	: remote device address type .

Returns

WICED_TRUE if successful else WICED_FALSE

void wiced_bt_ble_update_scanner_filter_policy

(

wiced_bt_ble_scanner_filter_policy_t

scanner_policy

)

Function wiced_bt_ble_update_scanner_filter_policy.

Update the filter policy of scanning.

Parameters

[in]

scanner_policy

scanning filter policy

Returns

void

wiced_bool_t wiced_bt_ble_verify_signature	(	wiced_bt_device_address_t	bd_addr,
		uint8_t *	p_orig,
		uint16_t	len,
		uint32_t	counter,
		uint8_t *	p_comp
	)

Function wiced_bt_ble_verify_signature.

Verify the data signature

Parameters

[in]	bd_addr	target device the data to be signed for.
[in]	p_orig	original data before signature.
[in]	len	length of the signing data
[in]	counter	counter used when doing data signing
[in]	p_comp	signature to be compared against.

Returns

TRUE if signature verified correctly; otherwise FALSE.

wiced_bool_t wiced_bt_notify_multi_advertisement_packet_transmissions	(	uint8_t	adv_instance,
		void(*)(uint32_t)	clientCallback,
		uint32_t	advanceNoticeInMicroSeconds
	)

Function wiced_bt_notify_multi_advertisement_packet_transmissions.

Allows the application to register a callback that will be invoked just before an ADV packet is about to be sent out and immediately after.

Parameters

[in]	adv_instance	: 1 to MULTI_ADV_MAX_NUM_INSTANCES
[in]	clientCallback	: Pointer to a function that will be invoked in application thread context with WICED_BT_ADV_NOTIFICATION_READY for before ADV and WICED_BT_ADV_NOTIFICATION_DONE after ADV packet is complete.
[in]	advanceNoticeInMicroSeconds	: Number of microseconds before the ADV the notification is to be sent. Will be rounded down to the nearest 1.25mS. Has to be an even multiple of 625uS.

Returns

wiced_bool_t

             TRUE if command succeeded

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
	)

Function wiced_bt_start_advertisements.

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.

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

)

Function wiced_btm_ble_update_advertisement_filter_policy.

Update the filter policy of advertiser.

Parameters

[in]

advertising_policy

advertising filter policy

Returns

TRUE if successful

wiced_result_t wiced_set_multi_advertisement_data	(	uint8_t *	p_data,
		uint8_t	data_len,
		uint8_t	adv_instance
	)

Function wiced_set_multi_advertisement_data.

Set multi advertisement data for each adv_instance

Parameters

[in]	p_data	: Advertising Data ( Max length 31 bytess)
[in]	data_len	: Advertising Data len ( Max 31 bytes )
[in]	adv_instance	: 1 to MULTI_ADV_MAX_NUM_INSTANCES

Returns

wiced_result_t

             WICED_BT_SUCCESS if successfully initiated
             WICED_BT_NO_RESOURCES if could not allocate resources to start the command
             WICED_BT_ILLEGAL_VALUE if parameter(s) are out of range

wiced_result_t wiced_set_multi_advertisement_params	(	uint8_t	adv_instance,
		wiced_bt_ble_multi_adv_params_t *	p_param
	)

Function wiced_set_multi_advertisement_params.

Set multi advertisement parameters for each adv_instance

All the parameters below referred to as "spec" is the Bluetooth 4.2 core specification, page 1277 (LE Set Advertising Parameter Command)

Parameters

[in]	adv_instance	: 1 to MULTI_ADV_MAX_NUM_INSTANCES
[in]	p_param	: pointer to the adv parameter structure.

Returns

wiced_result_t

             WICED_BT_SUCCESS if successfully initiated
             WICED_BT_NO_RESOURCES if could not allocate resources to start the command
             WICED_BT_ILLEGAL_VALUE if parameter(s) are out of range

wiced_bt_dev_status_t wiced_set_multi_advertisement_scan_response_data	(	uint8_t *	p_data,
		uint8_t	data_len,
		uint8_t	adv_instance
	)

Function wiced_set_multi_advertisement_scan_response_data.

Set multi advertisement data for each adv_instance

Parameters

[in]	p_data	: Scan Rsp Data ( Max length 31 bytess)
[in]	data_len	: Scan Rsp Data len ( Max 31 bytes )
[in]	adv_instance	: 1 to MULTI_ADV_MAX_NUM_INSTANCES

Returns

wiced_bt_dev_status_t

             TRUE if command succeeded