Synchronization#

Synchronization.

Provides the base functionality of periodic advertising synchronization. Use bluetooth_feature_sync_scanner and/or bluetooth_feature_past_receiver components to include the synchronization mechanisms that the application requires. Use bluetooth_feature_periodic_sync to include support for trains that do not have subevents or response slots, and/or bluetooth_feature_pawr_sync to include support for Periodic Advertising with Responses (PAwR) trains.

Some functionality in this class is considered deprecated and has been superseded by new classes. When one or more of bluetooth_feature_sync_scanner, bluetooth_feature_periodic_sync, or bluetooth_feature_pawr_sync components is included by the application, commands that have been superseded by the new classes are no longer available for use in the Synchronization class. Calling them will receive SL_STATUS_NOT_SUPPORTED error code. These commands are as follows:

See the command descriptions for the replacements.

Events that are deprecated and superseded by the new classes are no longer triggered by the Synchronization class if any of the new classes are included in the application. See event descriptions for the replacements.

Modules#

sl_bt_evt_sync_opened

sl_bt_evt_sync_transfer_received

sl_bt_evt_sync_data

sl_bt_evt_sync_closed

Enumerations#

enum
sl_bt_sync_reporting_mode_t {
sl_bt_sync_report_none = 0x0
sl_bt_sync_report_all = 0x1
}

Specifies the mode for periodic advertising reports.

enum
sl_bt_sync_advertiser_clock_accuracy_t {
sl_bt_sync_clock_accuracy_500 = 0x1f4
sl_bt_sync_clock_accuracy_250 = 0xfa
sl_bt_sync_clock_accuracy_150 = 0x96
sl_bt_sync_clock_accuracy_100 = 0x64
sl_bt_sync_clock_accuracy_75 = 0x4b
sl_bt_sync_clock_accuracy_50 = 0x32
sl_bt_sync_clock_accuracy_30 = 0x1e
sl_bt_sync_clock_accuracy_20 = 0x14
}

These values indicate the advertiser clock accuracy in a periodic advertising synchronization.

Functions#

SL_BGAPI_DEPRECATED sl_status_t
sl_bt_sync_set_parameters(uint16_t skip, uint16_t timeout, uint32_t flags)
SL_BGAPI_DEPRECATED sl_status_t
sl_bt_sync_open(bd_addr address, uint8_t address_type, uint8_t adv_sid, uint16_t *sync)
sl_status_t
sl_bt_sync_set_reporting_mode(uint16_t sync, uint8_t reporting_mode)
sl_status_t
sl_bt_sync_update_sync_parameters(uint16_t sync, uint16_t skip, uint16_t timeout)
sl_status_t
sl_bt_sync_close(uint16_t sync)

Macros#

#define
sl_bt_cmd_sync_open_id 0x00420020
#define
sl_bt_cmd_sync_close_id 0x01420020
#define
sl_bt_rsp_sync_open_id 0x00420020
#define
sl_bt_rsp_sync_close_id 0x01420020

Enumeration Documentation#

sl_bt_sync_reporting_mode_t#

sl_bt_sync_reporting_mode_t

Specifies the mode for periodic advertising reports.

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


Definition at line 4624 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_sync_advertiser_clock_accuracy_t#

sl_bt_sync_advertiser_clock_accuracy_t

These values indicate the advertiser clock accuracy in a periodic advertising synchronization.

Enumerator
sl_bt_sync_clock_accuracy_500

(0x1f4) Clock accuracy 500 ppm

sl_bt_sync_clock_accuracy_250

(0xfa) Clock accuracy 250 ppm

sl_bt_sync_clock_accuracy_150

(0x96) Clock accuracy 150 ppm

sl_bt_sync_clock_accuracy_100

(0x64) Clock accuracy 100 ppm

sl_bt_sync_clock_accuracy_75

(0x4b) Clock accuracy 75 ppm

sl_bt_sync_clock_accuracy_50

(0x32) Clock accuracy 50 ppm

sl_bt_sync_clock_accuracy_30

(0x1e) Clock accuracy 30 ppm

sl_bt_sync_clock_accuracy_20

(0x14) Clock accuracy 20 ppm


Definition at line 4636 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

Function Documentation#

sl_bt_sync_set_parameters#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_sync_set_parameters (uint16_t skip, uint16_t timeout, uint32_t flags)
Parameters
[in]skip

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

  • Range: 0x0000 to 0x01F3

  • Default value: 0

[in]timeout

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

  • Range: 0x0A to 0x4000

  • Unit: 10 ms

  • Time range: 100 ms to 163.84 s

  • Default value: 1000 ms

[in]flags

No flags defined currently

Deprecated and replaced by sl_bt_sync_scanner_set_sync_parameters.

Configure periodic advertiser synchronization parameters. The specified parameters take effect immediately for all advertisers that have not already established synchronization.

The application should determine skip and timeout values based on the periodic advertising interval provided by the advertiser. Ensure that you 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. Periodic advertising intervals are reported in event sl_bt_evt_scanner_scan_report.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4904 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_sync_open#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_sync_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

Advertising set identifier

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

Deprecated and replaced by sl_bt_sync_scanner_open.

Start establishing synchronization with the specified periodic advertiser in parallel with other advertisers given in previous invocations of this command. The stack will internally enable scanning when needed so that synchronizations can occur. The scanning responses from the internal scanning are not passed to the application unless the application has also enabled scanning.

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

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events

  • sl_bt_evt_sync_opened - Triggered after the synchronization is established.

  • sl_bt_evt_sync_data - Indicates that a periodic advertisement packet is received.

  • 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 4966 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_sync_set_reporting_mode#

sl_status_t sl_bt_sync_set_reporting_mode (uint16_t sync, uint8_t reporting_mode)
Parameters
[in]sync

Periodic advertising synchronization handle

[in]reporting_mode

Enum sl_bt_sync_reporting_mode_t. Specifies the mode for reporting data received in the periodic advertising train. 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.

Set data reporting mode of the periodic advertising synchronization.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4987 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_sync_update_sync_parameters#

sl_status_t sl_bt_sync_update_sync_parameters (uint16_t sync, uint16_t skip, uint16_t timeout)
Parameters
[in]sync

Periodic advertising synchronization handle

[in]skip

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

  • Range: 0x0000 to 0x01F3

  • Default value: 0

[in]timeout

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

  • Range: 0x0A to 0x4000

  • Unit: 10 ms

  • Time range: 100 ms to 163.84 s

  • Default value: 1000 ms

Update synchronization parameters for a periodic sync that was already established.

When a sync is established by scanning (see Periodic Advertising Sync Scanner) or by receiving Periodic Advertising Synchronization Transfer (see PAST Receiver), the sync gets the skip and timeout parameters that were configured in the corresponding class. The application can use this command sl_bt_sync_update_sync_parameters to update the values of a sync that has been established. The application can for example update the values to better match the actual interval of the periodic advertising train, or to increase the skip value to minimize wakeups when power saving is prioritized over receiving every periodic advertisement.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 5020 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_sync_close#

sl_status_t sl_bt_sync_close (uint16_t sync)
Parameters
[in]sync

Periodic advertising synchronization handle

Close a periodic advertising synchronization or cancel an ongoing attempt of establishing a synchronization.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events

  • sl_bt_evt_sync_closed - Triggered after a periodic advertising synchronization has been closed or canceled.


Definition at line 5038 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

Macro Definition Documentation#

sl_bt_cmd_sync_set_parameters_id#

#define sl_bt_cmd_sync_set_parameters_id
Value:
0x02420020

Definition at line 4610 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_sync_open_id#

#define sl_bt_cmd_sync_open_id
Value:
0x00420020

Definition at line 4611 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_sync_set_reporting_mode_id#

#define sl_bt_cmd_sync_set_reporting_mode_id
Value:
0x03420020

Definition at line 4612 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_sync_update_sync_parameters_id#

#define sl_bt_cmd_sync_update_sync_parameters_id
Value:
0x04420020

Definition at line 4613 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_sync_close_id#

#define sl_bt_cmd_sync_close_id
Value:
0x01420020

Definition at line 4614 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_sync_set_parameters_id#

#define sl_bt_rsp_sync_set_parameters_id
Value:
0x02420020

Definition at line 4615 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_sync_open_id#

#define sl_bt_rsp_sync_open_id
Value:
0x00420020

Definition at line 4616 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_sync_set_reporting_mode_id#

#define sl_bt_rsp_sync_set_reporting_mode_id
Value:
0x03420020

Definition at line 4617 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_sync_update_sync_parameters_id#

#define sl_bt_rsp_sync_update_sync_parameters_id
Value:
0x04420020

Definition at line 4618 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_sync_close_id#

#define sl_bt_rsp_sync_close_id
Value:
0x01420020

Definition at line 4619 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h