Periodic Advertising Synchronization (sync)#

Provides periodic advertising synchronization feature.

When this feature is used, enable event le_gap_extended_scan_response which contains useful information for establishing a synchronization.

sync commands#

sync_close#

Closes a periodic advertising synchronization or cancels an ongoing attempt of establishing a synchronization.

C API#

/* Function */
struct gecko_msg_sync_close_rsp_t *gecko_cmd_sync_close(uint8 sync);

/* Response id */
gecko_rsp_sync_close_id

/* Response structure */
struct gecko_msg_sync_close_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)#


Type	Name	Description
uint8	sync	Periodic advertising synchronization handle

Response Parameters (for BGAPI headers refer to link)#


Type	Name	Description
uint16	result	Result code 0: success Non-zero: an error occurred For other values refer to the Error codes

Events generated#


Event	Description
sync_closed	Triggered after a periodic advertising synchronization has been closed or canceled.

sync_open#

Establish a synchronization with a periodic advertising from the specified advertiser and begin receiving periodic advertising packets. Note that synchronization establishment can only occur when scanning is enabled. While scanning is disabled, no attempt to synchronize will occur.

The application should determine skip and timeout values based on the periodic advertising interval provided by the advertiser. If skip and timeout are used, select appropriate values so that they allow a few receiving attempts. Periodic advertising intervals are reported in event le_gap_extended_scan_response.

C API#

/* Function */
struct gecko_msg_sync_open_rsp_t *gecko_cmd_sync_open(uint8 adv_sid, uint16 skip, uint16 timeout, bd_addr address, uint8 address_type);

/* Response id */
gecko_rsp_sync_open_id

/* Response structure */
struct gecko_msg_sync_open_rsp_t
{
  uint16 result;
  uint8 sync;
}

Command Parameters (for BGAPI headers refer to link)#


Type	Name	Description
uint8	adv_sid	Advertising set identifier
uint16	skip	The maximum number of periodic advertising packets that can be skipped after a successful receive. Range: 0x0000 to 0x01F3
uint16	timeout	The maximum permitted time between successful receives. If this time is exceeded, synchronization is lost. Unit: 10 ms. Range: 0x06 to 0xFFFF Unit: 10 ms Time range: 100 ms ms to 163.84 s
bd_addr	address	Address of the advertiser
uint8	address_type	Advertiser address type. Values: 0: Public address 1: Random address

Response Parameters (for BGAPI headers refer to link)#


Type	Name	Description
uint16	result	Result code 0: success Non-zero: an error occurred For other values refer to the Error codes
uint8	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 0 (zero).

Events generated#


Event	Description
sync_opened	Triggered after the synchronization is established.
sync_data	Indicates that a periodic advertisement packet is received.

sync events#

sync_opened#

Indicates that a periodic advertising synchronization has been opened.

C API#

/* event id*/
gecko_evt_sync_opened_id

/* event structure*/
struct gecko_msg_sync_opened_evt_t
{
  uint8 sync;
  uint8 adv_sid;
  bd_addr address;
  uint8 address_type;
  uint8 adv_phy;
  uint16 adv_interval;
  uint16 clock_accuracy;
}

Event Parameters (for BGAPI headers refer to link)#


Type	Name	Description
uint8	sync	Periodic advertising synchronization handle
uint8	adv_sid	Advertising set identifier
bd_addr	address	Address of the advertiser
uint8	address_type	Advertiser address type. Values: 0: Public address 1: Random address
uint8	adv_phy	The advertiser PHY. Value: 1: 1M PHY 2: 2M PHY 4: Coded PHY
uint16	adv_interval	The periodic advertising interval. Value in units of 1.25 ms Range: 0x06 to 0xFFFF Time range: 7.5 ms to 81.92 s
uint16	clock_accuracy	The advertiser clock accuracy.

sync_closed#

Indicates that a periodic advertising synchronization lost or a synchronization establishment procedure was canceled.

C API#

/* event id*/
gecko_evt_sync_closed_id

/* event structure*/
struct gecko_msg_sync_closed_evt_t
{
  uint16 reason;
  uint8 sync;
}

Event Parameters (for BGAPI headers refer to link)#


Type	Name	Description
uint16	reason	Result code 0: success Non-zero: an error occurred For other values refer to the Error codes
uint8	sync	Periodic advertising synchronization handle

sync_data#

Reports a received periodic advertisement packet.

C API#

/* event id*/
gecko_evt_sync_data_id

/* event structure*/
struct gecko_msg_sync_data_evt_t
{
  uint8 sync;
  int8 tx_power;
  int8 rssi;
  uint8 data_status;
  uint8array data;
}

Event Parameters (for BGAPI headers refer to link)#


Type	Name	Description
uint8	sync	Periodic advertising synchronization handle
int8	tx_power	TX power value in the received packet header. Units: dBm Valid value range: -127 to 126 Value 127: information unavailable
int8	rssi	Signal strength indicator (RSSI) in the latest received packet. Units: dBm Range: -127 to +20
uint8	data_status	Data completeness: 0: Complete 1: Incomplete, more data to come in new events 2: Incomplete, data truncated, no more to come
uint8array	data	Periodic advertising data

sync enumerations#

sync_advertiser_clock_accuracy#

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

Enumerations#


Value	Name	Description
500	sync_clock_accuracy_500	Clock accuracy 500 ppm
250	sync_clock_accuracy_250	Clock accuracy 250 ppm
150	sync_clock_accuracy_150	Clock accuracy 150 ppm
100	sync_clock_accuracy_100	Clock accuracy 100 ppm
75	sync_clock_accuracy_75	Clock accuracy 75 ppm
50	sync_clock_accuracy_50	Clock accuracy 50 ppm
30	sync_clock_accuracy_30	Clock accuracy 30 ppm
20	sync_clock_accuracy_20	Clock accuracy 20 ppm