Bluetooth Host Stack Library
LE Periodic Mode Advertising and Scanning

General Description

This section contains LE Periodic advertisement and scanning defines, structures and functions.

Note
Applications using extended and periodic mode advertising and scanning shall use only extended mode APIs cannot invoke any of the Legacy mode APIs for advertisement and scanning

Data Structures

struct  wiced_ble_padv_subevent_data_req_event_data_t
 Periodic Advertising with Response (PAWR) Subevent Data Request Event Data. More...
 
struct  wiced_ble_padv_rsp_report_event_data_t
 Periodic Advertising with Response (PAWR) Response Report Event Data. More...
 
struct  wiced_ble_padv_subevent_data_t
 Configuration for Periodic Advertising with Response (PAWR) subevent indication data which is sent by the central device at the start of each subevent. More...
 
struct  wiced_ble_padv_subevent_rsp_data_t
 Configuration for Periodic Advertising with Response (PAWR) response data. More...
 
struct  wiced_ble_padv_params_t
 Parameters for LE Set Periodic Advertising Parameter command. More...
 
struct  wiced_ble_padv_create_sync_params_t
 Peridic Adv Create Sync parameters. More...
 
struct  wiced_ble_padv_sync_established_event_data_t
 Periodic Advertising Sync Established Event Data Sync established to periodic advertiser event data format. More...
 
struct  wiced_ble_padv_sync_transfer_event_data_t
 Periodic Adv Sync Transfer Received Event Data. More...
 
struct  wiced_ble_padv_report_event_data_t
 Periodic advertising report data format. More...
 
struct  wiced_ble_padv_sync_transfer_param_t
 Periodic adv sync transfer params. More...
 

Macros

#define WICED_BT_MAX_PAWR_SUBEVENT_DATA_LEN   251
 Maximum PAWR Subevent data len.
 

Typedefs

typedef uint16_t wiced_ble_padv_prop_t
 Periodic adv property (see wiced_ble_padv_prop_e)
 
typedef uint8_t wiced_ble_padv_sync_options_t
 Options used in create periodic sync to periodic adv command (see wiced_ble_padv_sync_options_e)
 
typedef uint16_t wiced_ble_padv_sync_handle_t
 Sync_Handle to be used to identify the periodic advertiser. More...
 
typedef uint8_t wiced_ble_padv_clock_accuracy_t
 Advertiser clock accuracy (see wiced_ble_padv_clock_accuracy_e)
 
typedef uint8_t wiced_ble_padv_sync_transfer_mode_t
 Mode used in create periodic sync to periodic adv command (see wiced_ble_padv_sync_transfer_mode_e)
 

Enumerations

enum  wiced_ble_padv_prop_e { WICED_BLE_PADV_PROPERTY_INCLUDE_TX_POWER = (1 << 6) }
 Periodic adv property. More...
 
enum  wiced_ble_padv_sync_options_e {
  WICED_BLE_PADV_CREATE_SYNC_OPTION_IGNORE_PA_LIST = 0,
  WICED_BLE_PADV_CREATE_SYNC_OPTION_USE_PA_LIST = 1,
  WICED_BLE_PADV_CREATE_SYNC_OPTION_DISABLE_REPORTING = 2,
  WICED_BLE_PADV_CREATE_SYNC_OPTION_ENABLE_DUPLICATE_FILTERING = 4
}
 Options used in create sync to periodic adv command The Options parameter is used to determine whether the Periodic Advertiser List is used, whether HCI_LE_Periodic_Advertising_Report events for this periodic advertising train are initially enabled or disabled, and whether duplicate reports are filtered or not. More...
 
enum  wiced_ble_padv_clock_accuracy_e {
  PERIODIC_ADVERTISER_CLK_ACCURACY_500PPM,
  PERIODIC_ADVERTISER_CLK_ACCURACY_250PPM,
  PERIODIC_ADVERTISER_CLK_ACCURACY_150PPM,
  PERIODIC_ADVERTISER_CLK_ACCURACY_100PPM,
  PERIODIC_ADVERTISER_CLK_ACCURACY_75PPM,
  PERIODIC_ADVERTISER_CLK_ACCURACY_50PPM,
  PERIODIC_ADVERTISER_CLK_ACCURACY_30PPM,
  PERIODIC_ADVERTISER_CLK_ACCURACY_20PPM
}
 Advertiser clock accuracy. More...
 
enum  wiced_ble_padv_sync_transfer_mode_e {
  WICED_BLE_PERIODIC_IGNORE_PA_SYNC_TRANSFER_EVT,
  WICED_BLE_PERIODIC_ENABLE_PA_SYNC_TRANSFER_DISABLE_PA_REPORT_EVT,
  WICED_BLE_PERIODIC_ENABLE_PA_SYNC_TRANSFER_ENABLE_PA_REPORT_EVT
}
 Mode used in Periodic Advertising Sync Transfer Parameters. More...
 

Functions

wiced_bt_dev_status_t wiced_ble_padv_set_adv_params (wiced_ble_ext_adv_handle_t adv_handle, wiced_ble_padv_params_t *p_adv_params)
 Function wiced_ble_padv_set_adv_params This API is called on a central to set the PAWR parameters. More...
 
wiced_bt_dev_status_t wiced_ble_padv_set_adv_data (wiced_ble_ext_adv_handle_t adv_handle, uint16_t adv_data_length, uint8_t *p_adv_data)
 Sends the HCI command to write the periodic adv data. More...
 
wiced_bt_dev_status_t wiced_ble_padv_enable_adv (wiced_ble_ext_adv_handle_t adv_handle, wiced_bool_t enable)
 Sends the HCI command to enable/disable periodic advertisements. More...
 
wiced_bt_dev_status_t wiced_ble_padv_create_sync (wiced_ble_padv_create_sync_params_t *p_sync_params)
 Sends the HCI command to synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets. More...
 
wiced_bt_dev_status_t wiced_ble_padv_cancel_sync (void)
 Sends HCI command to cancel the create sync command while it is pending. More...
 
wiced_bt_dev_status_t wiced_ble_padv_terminate_sync (uint16_t sync_handle)
 Sends the HCI command to stop reception of periodic advertising identified by the sync_handle. More...
 
wiced_bt_dev_status_t wiced_ble_padv_add_device_to_list (wiced_bt_ble_address_type_t advertiser_addr_type, wiced_bt_device_address_t advetiser_addr, wiced_ble_ext_adv_sid_t adv_sid)
 Sends the HCI command to add the given advertiser to Periodic Advertiser list. More...
 
wiced_bt_dev_status_t wiced_ble_padv_remove_device_from_list (wiced_bt_ble_address_type_t advertiser_addr_type, wiced_bt_device_address_t advetiser_addr, wiced_ble_ext_adv_sid_t adv_sid)
 Sends the HCI command to remove the given advertiser from Periodic Advertiser list. More...
 
wiced_bt_dev_status_t wiced_ble_padv_clear_list (void)
 Sends the HCI command to remove to remove all devices from the the Periodic Advertisers list. More...
 
wiced_bt_dev_status_t wiced_ble_padv_set_rcv_enable (wiced_ble_padv_sync_handle_t sync_handle, wiced_bool_t enable)
 Sends the HCI command to enable or disable receiving periodic ADV data for a sync handle. More...
 
wiced_bt_dev_status_t wiced_ble_padv_transfer_sync (wiced_bt_device_address_t peer_bda, uint16_t service_data, wiced_ble_padv_sync_handle_t sync_handle)
 Sends the HCI command to send synchronization information about the periodic advertising train identified by the Sync_Handle parameter to given device. More...
 
wiced_bt_dev_status_t wiced_ble_padv_transfer_set_info (wiced_bt_device_address_t peer_bda, uint16_t service_data, wiced_ble_ext_adv_handle_t adv_handle)
 Sends the HCI command to send synchronization information about the periodic advertising in an advertising set to the connected device. More...
 
wiced_bt_dev_status_t wiced_ble_padv_set_sync_transfer_params (wiced_bt_device_address_t peer_bda, wiced_ble_padv_sync_transfer_param_t *p_st)
 Sends the HCI command to set synchronize periodic transfer parameter. More...
 
wiced_bt_dev_status_t wiced_ble_padv_set_default_sync_transfer_params (wiced_ble_padv_sync_transfer_param_t *p_st)
 Sends the HCI command to set Default synchronize periodic transfer parameter. More...
 
wiced_bt_dev_status_t wiced_ble_padv_set_subevent_data (wiced_ble_ext_adv_handle_t adv_handle, uint8_t num_subevents, wiced_ble_padv_subevent_data_t *p_se_data, uint16_t max_response_len)
 Function wiced_ble_padv_set_subevent_data. More...
 
wiced_bt_dev_status_t wiced_ble_padv_set_subevent_rsp_data (uint16_t sync_handle, wiced_ble_padv_subevent_rsp_data_t *p_rsp_data)
 Function wiced_ble_padv_set_subevent_rsp_data. More...
 
wiced_bt_dev_status_t wiced_ble_padv_set_sync_subevent (uint16_t sync_handle, uint16_t properties, uint8_t num_subevents, uint8_t *p_subevents)
 Function wiced_ble_padv_set_sync_subevent. More...
 

Typedef Documentation

◆ wiced_ble_padv_sync_handle_t

typedef uint16_t wiced_ble_padv_sync_handle_t

Sync_Handle to be used to identify the periodic advertiser.

Range: 0x0000-0x0EFF

Enumeration Type Documentation

◆ wiced_ble_padv_prop_e

Periodic adv property.

Enumerator
WICED_BLE_PADV_PROPERTY_INCLUDE_TX_POWER 

Speicify Tx power in periodic adv events.

◆ wiced_ble_padv_sync_options_e

Options used in create sync to periodic adv command The Options parameter is used to determine whether the Periodic Advertiser List is used, whether HCI_LE_Periodic_Advertising_Report events for this periodic advertising train are initially enabled or disabled, and whether duplicate reports are filtered or not.

If the Periodic Advertiser List is not used, the Advertising_SID, Advertiser Address_Type, and Advertiser Address parameters specify the periodic advertising device to listen to; otherwise they shall be ignored.

Enumerator
WICED_BLE_PADV_CREATE_SYNC_OPTION_IGNORE_PA_LIST 

Use the Advertising_SID, Advertising_Address_Type, and Advertising Address parameters specified in create sync command to determine which advertiser to listen to.

WICED_BLE_PADV_CREATE_SYNC_OPTION_USE_PA_LIST 

Use the Periodic Advertiser List to determine which advertiser to listen to.

WICED_BLE_PADV_CREATE_SYNC_OPTION_DISABLE_REPORTING 

Disable receiving periodic advertising reports.

WICED_BLE_PADV_CREATE_SYNC_OPTION_ENABLE_DUPLICATE_FILTERING 

Enable duplicate filtering for the periodic advertising reports.

◆ wiced_ble_padv_clock_accuracy_e

Advertiser clock accuracy.

Enumerator
PERIODIC_ADVERTISER_CLK_ACCURACY_500PPM 

Advertiser clock accuracy 500 ppm.

PERIODIC_ADVERTISER_CLK_ACCURACY_250PPM 

Advertiser clock accuracy 250 ppm.

PERIODIC_ADVERTISER_CLK_ACCURACY_150PPM 

Advertiser clock accuracy 150 ppm.

PERIODIC_ADVERTISER_CLK_ACCURACY_100PPM 

Advertiser clock accuracy 100 ppm.

PERIODIC_ADVERTISER_CLK_ACCURACY_75PPM 

Advertiser clock accuracy 75 ppm.

PERIODIC_ADVERTISER_CLK_ACCURACY_50PPM 

Advertiser clock accuracy 50 ppm.

PERIODIC_ADVERTISER_CLK_ACCURACY_30PPM 

Advertiser clock accuracy 30 ppm.

PERIODIC_ADVERTISER_CLK_ACCURACY_20PPM 

Advertiser clock accuracy 20 ppm.

◆ wiced_ble_padv_sync_transfer_mode_e

Mode used in Periodic Advertising Sync Transfer Parameters.

Enumerator
WICED_BLE_PERIODIC_IGNORE_PA_SYNC_TRANSFER_EVT 

No attempt is made to synchronize to the Periodic Advertising (PA) and no HCI_LE_Periodic_Advertising_Sync_Transfer_Received event is sent to the Host (default)

WICED_BLE_PERIODIC_ENABLE_PA_SYNC_TRANSFER_DISABLE_PA_REPORT_EVT 

An HCI_LE_Periodic_Advertising_Sync_Transfer_Received event is sent to the Host.

HCI_LE_Periodic_Advertising_Report events will be disabled.

WICED_BLE_PERIODIC_ENABLE_PA_SYNC_TRANSFER_ENABLE_PA_REPORT_EVT 

An HCI_LE_Periodic_Advertising_Sync_Transfer_Received event is sent to the Host.

HCI_LE_Periodic_Advertising_Report events will be enabled.

Function Documentation

◆ wiced_ble_padv_set_adv_params()

wiced_bt_dev_status_t wiced_ble_padv_set_adv_params ( wiced_ble_ext_adv_handle_t  adv_handle,
wiced_ble_padv_params_t p_adv_params 
)

Function wiced_ble_padv_set_adv_params This API is called on a central to set the PAWR parameters.

Parameters
[in]adv_handleHandle of the Advertising Set
[out]p_adv_paramsPointer to p_adv_params
Returns
wiced_result_t WICED_BT_SUCCESS contents of features are valid WICED_BT_ERROR otherwise.

◆ wiced_ble_padv_set_adv_data()

wiced_bt_dev_status_t wiced_ble_padv_set_adv_data ( wiced_ble_ext_adv_handle_t  adv_handle,
uint16_t  adv_data_length,
uint8_t *  p_adv_data 
)

Sends the HCI command to write the periodic adv data.

Parameters
[in]adv_handleadvertisement set handle
[in]adv_data_lengthperiodic data length
[in]p_adv_datapointer to the periodic data
Returns
wiced_bt_dev_status_t WICED_BT_ILLEGAL_VALUE : If paramer is wrong
WICED_BT_UNSUPPORTED : If command not supported
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If successful

◆ wiced_ble_padv_enable_adv()

wiced_bt_dev_status_t wiced_ble_padv_enable_adv ( wiced_ble_ext_adv_handle_t  adv_handle,
wiced_bool_t  enable 
)

Sends the HCI command to enable/disable periodic advertisements.

Parameters
[in]adv_handle- handle of the advertising set
[in]enable- true to enable, false to disable
Returns
wiced_bt_dev_status_t WICED_BT_ILLEGAL_VALUE : If paramer is wrong
WICED_BT_UNSUPPORTED : If command not supported
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If successful

◆ wiced_ble_padv_create_sync()

wiced_bt_dev_status_t wiced_ble_padv_create_sync ( wiced_ble_padv_create_sync_params_t p_sync_params)

Sends the HCI command to synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets.

Parameters
[in]p_sync_params: Parameters for sync to periodic adv
Returns
wiced_bt_dev_status_t

WICED_BT_UNSUPPORTED : If command not supported
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If successful

◆ wiced_ble_padv_cancel_sync()

wiced_bt_dev_status_t wiced_ble_padv_cancel_sync ( void  )

Sends HCI command to cancel the create sync command while it is pending.

Returns
wiced_bt_dev_status_t WICED_BT_UNSUPPORTED : If command not supported
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If successful

◆ wiced_ble_padv_terminate_sync()

wiced_bt_dev_status_t wiced_ble_padv_terminate_sync ( uint16_t  sync_handle)

Sends the HCI command to stop reception of periodic advertising identified by the sync_handle.

Parameters
[in]sync_handle- Sync handle received in WICED_BLE_PERIODIC_ADV_SYNC_ESTABLISHED_EVENT.
Returns
wiced_bt_dev_status_t

WICED_BT_UNSUPPORTED : If command not supported
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If successful

◆ wiced_ble_padv_add_device_to_list()

wiced_bt_dev_status_t wiced_ble_padv_add_device_to_list ( wiced_bt_ble_address_type_t  advertiser_addr_type,
wiced_bt_device_address_t  advetiser_addr,
wiced_ble_ext_adv_sid_t  adv_sid 
)

Sends the HCI command to add the given advertiser to Periodic Advertiser list.

Note : Caller shall not attempt to add more than max list size Shall not attempt to call this API, while create to periodic sync command is pending.

Parameters
[in]advertiser_addr_type: Periodic advertiser addr type
[in]advetiser_addr: Periodic advertiser addr
[in]adv_sid: Periodic advertiser sid
Returns
wiced_bt_dev_status_t WICED_BT_ILLEGAL_VALUE : If paramer is wrong
WICED_BT_UNSUPPORTED : If command not supported
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_PENDING : If command queued to send down
WICED_BT_SUCCESS : If successful

◆ wiced_ble_padv_remove_device_from_list()

wiced_bt_dev_status_t wiced_ble_padv_remove_device_from_list ( wiced_bt_ble_address_type_t  advertiser_addr_type,
wiced_bt_device_address_t  advetiser_addr,
wiced_ble_ext_adv_sid_t  adv_sid 
)

Sends the HCI command to remove the given advertiser from Periodic Advertiser list.

Note : Shall not attempt to call this API, while create to periodic sync command is pending.

Parameters
[in]advertiser_addr_type: Periodic advertiser addr type
[in]advetiser_addr: Periodic advertiser addr
[in]adv_sid: Periodic advertiser sid
Returns
wiced_bt_dev_status_t WICED_BT_ILLEGAL_VALUE : If paramer is wrong
WICED_BT_UNSUPPORTED : If command not supported
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If successful

◆ wiced_ble_padv_clear_list()

wiced_bt_dev_status_t wiced_ble_padv_clear_list ( void  )

Sends the HCI command to remove to remove all devices from the the Periodic Advertisers list.

Note : Shall not attempt to call this API, while create to periodic sync command is pending.

Returns
wiced_bt_dev_status_t WICED_BT_UNSUPPORTED : If command not supported
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If successful

◆ wiced_ble_padv_set_rcv_enable()

wiced_bt_dev_status_t wiced_ble_padv_set_rcv_enable ( wiced_ble_padv_sync_handle_t  sync_handle,
wiced_bool_t  enable 
)

Sends the HCI command to enable or disable receiving periodic ADV data for a sync handle.

Parameters
[in]sync_handle: Sync handle
[in]enable: Boolean for enable/disable.
Returns
wiced_bt_dev_status_t WICED_BT_UNSUPPORTED : If command not supported
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If command queued to send down

◆ wiced_ble_padv_transfer_sync()

wiced_bt_dev_status_t wiced_ble_padv_transfer_sync ( wiced_bt_device_address_t  peer_bda,
uint16_t  service_data,
wiced_ble_padv_sync_handle_t  sync_handle 
)

Sends the HCI command to send synchronization information about the periodic advertising train identified by the Sync_Handle parameter to given device.

Parameters
[in]peer_bda- Peer Bluetooth Address
[in]service_data- Service Data value
[in]sync_handle: Sync handle
Returns
wiced_bt_dev_status_t WICED_BT_UNKNOWN_ADDR : If Unknown remote BD address
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If command queued to send down

◆ wiced_ble_padv_transfer_set_info()

wiced_bt_dev_status_t wiced_ble_padv_transfer_set_info ( wiced_bt_device_address_t  peer_bda,
uint16_t  service_data,
wiced_ble_ext_adv_handle_t  adv_handle 
)

Sends the HCI command to send synchronization information about the periodic advertising in an advertising set to the connected device.

Parameters
[in]peer_bda- Peer Bluetooth Address
[in]service_data- Service Data value
[in]adv_handle- handle of the advertising set
Returns
wiced_bt_dev_status_t WICED_BT_UNKNOWN_ADDR : If Unknown remote BD address
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If command queued to send down

◆ wiced_ble_padv_set_sync_transfer_params()

wiced_bt_dev_status_t wiced_ble_padv_set_sync_transfer_params ( wiced_bt_device_address_t  peer_bda,
wiced_ble_padv_sync_transfer_param_t p_st 
)

Sends the HCI command to set synchronize periodic transfer parameter.

Parameters
[in]peer_bda- Peer Bluetooth Address
[in]p_st- sync transfer params
Returns
wiced_bt_dev_status_t WICED_BT_UNKNOWN_ADDR : If Unknown remote BD address
WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If successful

◆ wiced_ble_padv_set_default_sync_transfer_params()

wiced_bt_dev_status_t wiced_ble_padv_set_default_sync_transfer_params ( wiced_ble_padv_sync_transfer_param_t p_st)

Sends the HCI command to set Default synchronize periodic transfer parameter.

Parameters
[in]p_st- sync transfer params
Returns
wiced_bt_dev_status_t WICED_BT_NO_RESOURCES : If no memory to issue the command
WICED_BT_SUCCESS : If successful

◆ wiced_ble_padv_set_subevent_data()

wiced_bt_dev_status_t wiced_ble_padv_set_subevent_data ( wiced_ble_ext_adv_handle_t  adv_handle,
uint8_t  num_subevents,
wiced_ble_padv_subevent_data_t p_se_data,
uint16_t  max_response_len 
)

Function wiced_ble_padv_set_subevent_data.

             This API is used by the Host to set the data for one or more subevents of PAwR in reply to an
             HCI_LE_Periodic_Advertising_Subevent_Data_Request event. The data for a subevent shall be transmitted only once.
Parameters
[in]adv_handleHandle of the Advertising Set
[in]num_subeventsNumber of subevent data in the command
[in]p_se_dataPointer to the subevent data
[in]max_response_lenmax expected response length in # WICED_BT_BLE_PAWR_RSP_REPORT_EVENT
Note
:
Returns
wiced_result_t WICED_BT_SUCCESS contents of features are valid WICED_BT_ERROR otherwise.

◆ wiced_ble_padv_set_subevent_rsp_data()

wiced_bt_dev_status_t wiced_ble_padv_set_subevent_rsp_data ( uint16_t  sync_handle,
wiced_ble_padv_subevent_rsp_data_t p_rsp_data 
)

Function wiced_ble_padv_set_subevent_rsp_data.

             This API is used by the Host to set the data for a response slot in a specific subevent of the PAwR
             identified by the \p sync_handle. The data for a response slot shall be transmitted only once.
Parameters
[in]sync_handleHandle of the synchronized advertising train
[out]p_rsp_dataPointer to p_rsp_data
Returns
wiced_result_t WICED_BT_SUCCESS contents of features are valid WICED_BT_ERROR otherwise.

◆ wiced_ble_padv_set_sync_subevent()

wiced_bt_dev_status_t wiced_ble_padv_set_sync_subevent ( uint16_t  sync_handle,
uint16_t  properties,
uint8_t  num_subevents,
uint8_t *  p_subevents 
)

Function wiced_ble_padv_set_sync_subevent.

             This API is called to instruct the Controller to synchronize with a subset of the subevents
             within a PAwR train identified by the \p sync_handle, listen for packets sent by the peer device
             and pass any received data up to the Host
Parameters
[in]sync_handleHandle of the synchronized periodic ADV train
[in]propertiesProperties of the synchronized periodic ADV train
[in]num_subeventsNumber of subevents
[in]p_subeventsPointer to an array of subevents
Returns
wiced_result_t WICED_BT_SUCCESS contents of features are valid WICED_BT_ERROR otherwise.