Periodic Advertising Sync Scanner#

Periodic Advertising Sync Scanner.

Synchronize to periodic advertising trains by scanning for extended advertisements that provide the synchronization information.

Functions#

sl_status_t
sl_bt_sync_scanner_set_sync_parameters(uint16_t skip, uint16_t timeout, uint8_t reporting_mode)
sl_status_t
sl_bt_sync_scanner_open(bd_addr address, uint8_t address_type, uint8_t adv_sid, uint16_t *sync)

Macros#

Function Documentation#

sl_bt_sync_scanner_set_sync_parameters#

sl_status_t sl_bt_sync_scanner_set_sync_parameters (uint16_t skip, uint16_t timeout, uint8_t reporting_mode)
Parameters
[in]skip

The maximum number of periodic advertising packets that can be skipped after a successful receive.

  • Range: 0x0000 to 0x01F3

  • Default : 0

[in]timeout

The maximum permitted time between successful receives. If this time is exceeded, synchronization is lost. Unit: 10 ms.

  • Range: 0x000A to 0x4000

  • Unit: 10 ms

  • Time range: 100 ms to 163.84 s

  • Default : 1000 ms

[in]reporting_mode

Enum sl_bt_sync_reporting_mode_t. Specifies the initial mode for reporting data received in the periodic advertising train after it has achieved synchronization. Values:

  • sl_bt_sync_report_none (0x0): Data received in periodic advertising trains is not reported to the application.

  • sl_bt_sync_report_all (0x1): Data received in periodic advertising trains is reported to the application.

Default: sl_bt_sync_report_all (Data received in periodic advertising trains is reported to the application)

Configure synchronization parameters for synchronizing to periodic advertising trains. The specified parameters take effect immediately for all periodic advertising trains that have not already established synchronization.

The application should determine skip and timeout values based on the periodic advertising interval provided by the advertiser. Use a long enough timeout to allow multiple receives. If skip and timeout are used, select appropriate values so that they allow a few receiving attempts. Irrespective of the value of the skip parameter, the Controller stops skipping packets if the skipping would cause a timeout. Periodic advertising intervals are reported in sl_bt_evt_scanner_extended_advertisement_report event.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4391 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/ble_host/ble_bgapi/inc/sl_bt_api.h

sl_bt_sync_scanner_open#

sl_status_t sl_bt_sync_scanner_open (bd_addr address, uint8_t address_type, uint8_t adv_sid, uint16_t * sync)
Parameters
[in]address

Address of the advertiser

[in]address_type

Enum sl_bt_gap_address_type_t.

Advertiser address type.

If the application does not include the bluetooth_feature_use_accurate_api_address_types component, address_type uses the following values:

  • 0: Public address

  • 1: Random address

If the application includes the bluetooth_feature_use_accurate_api_address_types component, address_type uses enum sl_bt_gap_address_type_t values:

  • sl_bt_gap_public_address (0x0): Public device address

  • sl_bt_gap_static_address (0x1): Static device address

  • sl_bt_gap_random_resolvable_address (0x2): Resolvable private random address

  • sl_bt_gap_random_nonresolvable_address (0x3): Non-resolvable private random address

  • sl_bt_gap_public_address_resolved_from_rpa (0x4): Public identity address resolved from a resolvable private address (RPA)

  • sl_bt_gap_static_address_resolved_from_rpa (0x5): Static identity address resolved from a resolvable private address (RPA)

[in]adv_sid

The identifier of the advertising set to synchronize to

[out]sync

A handle that will be assigned to the periodic advertising synchronization after the synchronization is established. This handle is valid only if the result code of this response is SL_STATUS_OK.

Start establishing synchronization with the specified periodic advertiser in parallel with other advertisers given in previous invocations of this command.

Periodic advertisers are typically discovered by scanning for extended advertisements and observing the received sl_bt_evt_scanner_extended_advertisement_report events. See the bluetooth_feature_extended_scanner component and the sl_bt_scanner_start command. When an advertiser has periodic advertising, the periodic_interval field of sl_bt_evt_scanner_extended_advertisement_report event will be non-zero. To synchronize to that periodic advertising train, use the address, address_type, and adv_sid fields from the sl_bt_evt_scanner_extended_advertisement_report when issuing this command.

If the application has not already started scanning with the sl_bt_scanner_start command, the stack will internally enable scanning so that synchronizations can occur. The internal scanning uses the PHY that was most recently used with sl_bt_scanner_start and the parameters that have been configured with sl_bt_scanner_set_parameters. The internal scanning is automatically stopped when all requested synchronizations have occurred.

The scanning responses from the internal scanning are not passed to the application unless the application starts scanning with the sl_bt_scanner_start command. If the application starts scanning while synchronizations are being established, the scanning PHY and settings set by the application take effect immediately and scanning for synchronizations continues with the new settings. When the application has started scanning with the sl_bt_scanner_start command, scanning continues until the application stops scanning with the sl_bt_scanner_stop command.

Advertisers that have not already synced before the invocation of this command will be synced using the skip and timeout values configured in the most recent invocation of command sl_bt_evt_scanner_extended_advertisement_report.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events

  • sl_bt_evt_periodic_sync_opened - Triggered after synchronization is established to a periodic advertising train that does not have subevents or response slots.

  • sl_bt_evt_pawr_sync_opened - Triggered after synchronization is established to a Periodic Advertising with Responses (PAwR) train.

  • sl_bt_evt_periodic_sync_report - Triggered when data for periodic advertising train that does not have subevents or response slots is received and accepted by the reporting mode currently set to the train.

  • sl_bt_evt_pawr_sync_subevent_report - Triggered when subevent data for Periodic Advertising with Responses (PAwR) train is received and accepted by the reporting mode currently set to the train.

  • sl_bt_evt_sync_closed - Triggered after periodic advertising synchronization was lost or explicitly closed, or a synchronization establishment procedure was canceled.


Definition at line 4483 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/ble_host/ble_bgapi/inc/sl_bt_api.h

Macro Definition Documentation#

sl_bt_cmd_sync_scanner_set_sync_parameters_id#

#define sl_bt_cmd_sync_scanner_set_sync_parameters_id
Value:
0x00500020

Definition at line 4337 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/ble_host/ble_bgapi/inc/sl_bt_api.h

sl_bt_cmd_sync_scanner_open_id#

#define sl_bt_cmd_sync_scanner_open_id
Value:
0x01500020

Definition at line 4338 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/ble_host/ble_bgapi/inc/sl_bt_api.h

sl_bt_rsp_sync_scanner_set_sync_parameters_id#

#define sl_bt_rsp_sync_scanner_set_sync_parameters_id
Value:
0x00500020

Definition at line 4339 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/ble_host/ble_bgapi/inc/sl_bt_api.h

sl_bt_rsp_sync_scanner_open_id#

#define sl_bt_rsp_sync_scanner_open_id
Value:
0x01500020

Definition at line 4340 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/ble_host/ble_bgapi/inc/sl_bt_api.h