Infineon Logo AIROC™ BTSDK v4.9 - Documentation
 
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Functions
Advertising
Functions

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)
 Sets the advertisement mode of the host device based on the advertisement parameters initialized in wiced_bt_cfg_settings_t upon calling the stack initialization API (wiced_bt_stack_init). More...
 
wiced_bt_ble_advert_mode_t wiced_bt_ble_get_current_advert_mode (void)
 Get advertisement mode from host state machine, set by the API wiced_bt_start_advertisements. More...
 
wiced_result_t wiced_bt_ble_set_raw_advertisement_data (uint8_t num_elem, wiced_bt_ble_advert_elem_t *p_data)
 Set raw advertisement data of main advertising instance. 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 raw scan response data. More...
 
wiced_bool_t wiced_bt_ble_update_advertising_filter_accept_list (wiced_bool_t add, wiced_bt_device_address_t remote_bda)
 Add or remove a device to/from the advertising Filter Accept List. More...
 
wiced_bool_t wiced_btm_ble_update_advertisement_filter_policy (wiced_bt_ble_advert_filter_policy_t advertising_policy)
 Updates the filter policy when the local device is the advertiser. More...
 
wiced_result_t wiced_bt_ble_set_adv_tx_power (int8_t power)
 Sets the transmit power used for the main advertising instance triggered by wiced_bt_start_advertisements. More...
 
wiced_result_t wiced_bt_ble_read_adv_tx_power (wiced_bt_dev_cmpl_cback_t *p_cback)
 Sends an HCI command to the controller to read the transmit power level used in LE ADV packets of the main advertising instance (0). More...
 

Detailed Description

Function Documentation

wiced_bt_ble_advert_mode_t wiced_bt_ble_get_current_advert_mode ( void  )

Get advertisement mode from host state machine, set by the API wiced_bt_start_advertisements.

Parameters
void
Returns
advertisement mode enumerate in wiced_bt_ble_advert_mode_t
  • BTM_BLE_ADVERT_OFF
  • BTM_BLE_ADVERT_DIRECTED_HIGH
  • BTM_BLE_ADVERT_DIRECTED_LOW
  • BTM_BLE_ADVERT_UNDIRECTED_HIGH
  • BTM_BLE_ADVERT_UNDIRECTED_LOW
  • BTM_BLE_ADVERT_NONCONN_HIGH
  • BTM_BLE_ADVERT_NONCONN_LOW
  • BTM_BLE_ADVERT_DISCOVERABLE_HIGH
  • BTM_BLE_ADVERT_DISCOVERABLE_LOW
wiced_result_t wiced_bt_ble_read_adv_tx_power ( wiced_bt_dev_cmpl_cback_t *  p_cback)

Sends an HCI command to the controller to read the transmit power level used in LE ADV packets of the main advertising instance (0).

The read value is returned in a callback called asynchronously once the controller has a response for the host. The below callback can be used to receive the data by passing:

void read_adv_tx_power_callback( wiced_bt_tx_power_result_t *p_tx_power )
{
if ( ( p_tx_power->status == WICED_BT_SUCCESS ) &&
( p_tx_power->hci_status == HCI_SUCCESS ) )
{
WICED_BT_TRACE("ADV TX power = %i\r\n", p_tx_power->tx_power);
}
}
{
wiced_bt_ble_read_adv_tx_power( read_adv_tx_power_callback );
}
Parameters
[in]p_cbackcallback to receive ADV transmit power
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_set_adv_tx_power ( int8_t  power)

Sets the transmit power used for the main advertising instance triggered by wiced_bt_start_advertisements.

The power is specified in dbm. The device is only able to alter its tx power within the bounds of the power table set in the low-level FW. Different hardware will have different possible transmit powers.

Out of bound values will be dropped with no action taken. For example, if the current TX power is 0 and the max allowed is 4, inputting 5 or above will result in the power staying at 0 (not rounded down to 4).

Parameters
[in]poweradvertisement transmit power in dbm
Returns
  • WICED_SUCCESS command successfully sent to controller
  • BTM_ERR_PROCESSING transport buffer allocation failed
wiced_result_t wiced_bt_ble_set_raw_advertisement_data ( uint8_t  num_elem,
wiced_bt_ble_advert_elem_t *  p_data 
)

Set raw advertisement data of main advertising instance.

Advertising elements (wiced_bt_ble_advert_elem_t) are used to construct the raw ADV data that will be sent down to the controller. Multiple advertising elements can be used as long as the total length remains below 31, the max packet length for LE ADV packets. Below is an example of calling this API with a single element which transmits the name of the device a "HELLO":

{
static char name[] = "HELLO";
wiced_bt_ble_advert_elem_t adv_elem =
{
.advert_type = BTM_BLE_ADVERT_TYPE_NAME_COMPLETE,
.len = strlen( name );
.p_data = ( uint8_t* )name;
};
wiced_bt_ble_set_raw_advertisement_data(1, adv_elem);
}
Parameters
[in]num_elemnum elements in p_data (not bytes)
[in]p_datapointer to one or more wiced_bt_ble_advert_elem_t
Returns
  • WICED_SUCCESS success
  • BTM_NO_RESOURCES dynamic memory allocation fail
  • BTM_WRONG_MODE reserved error code
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 raw scan response data.

Identical functionality as setting regular ADV data using wiced_bt_ble_set_raw_advertisement_data. The only difference is that this data will be sent out only upon scan request (when the scanner is performing an 'active scan').

Parameters
[in]num_elemnum elements in p_data (not bytes)
[in]p_datapointer to one or more wiced_bt_ble_advert_elem_t
Returns
  • WICED_SUCCESS success
  • BTM_NO_RESOURCES dynamic memory allocation fail
  • BTM_WRONG_MODE reserved error code
wiced_bool_t wiced_bt_ble_update_advertising_filter_accept_list ( wiced_bool_t  add,
wiced_bt_device_address_t  remote_bda 
)

Add or remove a device to/from the advertising Filter Accept List.

The purpose of this advertisement Filter Accept List is to filter out connection requests and scan requests from other devices before bubbling them up to the application layer. After adding devices to the Filter Accept List, the filter policy must be set using wiced_btm_ble_update_advertisement_filter_policy.

Parameters
[in]addWICED_TRUE==add, WICED_FALSE==remove
[in]remote_bdaaddress of device to add/remove from Filter Accept List
Returns
  • WICED_TRUE indicates success
  • WICED_FALSE indicates Filter Accept List full or wrong ADV mode
Note
This API cannot be used while the Filter Accept List is in use. If the device is currently advertising using the Filter Accept List, disable it before using this API.
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 
)

Sets the advertisement mode of the host device based on the advertisement parameters initialized in wiced_bt_cfg_settings_t upon calling the stack initialization API (wiced_bt_stack_init).

Before calling this API, set the raw ADV data using wiced_bt_ble_set_raw_advertisement_data.

Parameters
[in]advert_modewiced_bt_ble_advert_mode_t
  • BTM_BLE_ADVERT_OFF
  • BTM_BLE_ADVERT_DIRECTED_HIGH
  • BTM_BLE_ADVERT_DIRECTED_LOW
  • BTM_BLE_ADVERT_UNDIRECTED_HIGH
  • BTM_BLE_ADVERT_UNDIRECTED_LOW
  • BTM_BLE_ADVERT_NONCONN_HIGH
  • BTM_BLE_ADVERT_NONCONN_LOW
  • BTM_BLE_ADVERT_DISCOVERABLE_HIGH
  • BTM_BLE_ADVERT_DISCOVERABLE_LOW
[in]directed_advertisement_bdaddr_typePeer addr type for directed ADV
  • BLE_ADDR_PUBLIC
  • BLE_ADDR_RANDOM
[in]directed_advertisement_bdaddr_ptrPeer addr for directed ADV
Returns
  • WICED_SUCCESS
  • WICED_ERROR
wiced_bool_t wiced_btm_ble_update_advertisement_filter_policy ( wiced_bt_ble_advert_filter_policy_t  advertising_policy)

Updates the filter policy when the local device is the advertiser.

The purpose of this advertisement Filter Accept List is to filter out connection requests and scan requests from other devices before bubbling them up to the application layer. Before enabling the advertisement Filter Accept List, the Filter Accept List must be populated using wiced_bt_ble_update_advertising_filter_accept_list.

Parameters
[in]clientCallbackwiced_bt_ble_advert_filter_policy_t
  • BTM_BLE_ADV_POLICY_ACCEPT_CONN_AND_SCAN
  • BTM_BLE_ADV_POLICY_ACCEPT_CONN_FILTER_SCAN
  • BTM_BLE_ADV_POLICY_FILTER_CONN_ACCEPT_SCAN
  • BTM_BLE_ADV_POLICY_FILTER_CONN_FILTER_SCAN
Returns
  • WICED_TRUE indicates success
  • WICED_FALSE indicates feature not supported or wrong ADV mode
Note
The element ble_filter_accept_list_size of the struct wiced_bt_cfg_settings_t must be set to a positive value in order for this API to function. This config struct is to be passed at stack init (wiced_bt_stack_init).