You are viewing documentation for version: 2.13 This version works with Simplicity Studio 4 only | **For the latest and prior versions see Version History
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 has occurred
For other values see 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 has occurred
For other values see 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 has occurred
For other values see 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
|
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 |