Periodic Advertising Synchronization (sync)

This class provides periodic advertising synchronization feature.

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

sync commands

sync_close

This command can be used to close a synchronization with periodic advertising or cancel an ongoing synchronization establishment procedure.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x42 class Message class:Periodic Advertising Synchronization
3 0x01 method Message ID
4 uint8 sync Periodic advertising synchronization handle

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x42 class Message class:Periodic Advertising Synchronization
3 0x01 method Message ID
4-5 uint16 result Result code
  • 0: success
  • Non-zero: an error occurred
For other values refer to the Error codes

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
}

Events generated

Event Description
sync_closed This event is triggered after the synchronization has been closed.

sync_open

This command can be used to 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 take place.

The application should decide skip and timeout values based on the periodic advertising interval provided by the advertiser. It is recommended to set skip and timeout at the values that allow a few receiving attempts. Periodic advertising intervals are reported in event le_gap_extended_scan_response.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x0c lolen Minimum payload length
2 0x42 class Message class:Periodic Advertising Synchronization
3 0x00 method Message ID
4 uint8 adv_sid Advertising set identifier
5-6 uint16 skip The maximum number of periodic advertising packets that can be skipped after a successful receive. Range: 0x0000 to 0x01F3
7-8 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
9-14 bd_addr address Address of the advertiser
15 uint8 address_type Advertiser address type. Values:
  • 0: Public address
  • 1: Random address

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x03 lolen Minimum payload length
2 0x42 class Message class:Periodic Advertising Synchronization
3 0x00 method Message ID
4-5 uint16 result Result code
  • 0: success
  • Non-zero: an error occurred
For other values refer to the Error codes
6 uint8 sync Handle that will be assigned to the periodic advertising synchronization once the synchronization will be established. This handle is valid only if the result code of this response is 0 (zero).

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
}

Events generated

Event Description
sync_opened This event is triggered after the synchronization has been established.
sync_data This event indicates a periodic advertising packet has been received.

sync events

sync_opened

This event indicates a synchronization has been opened.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x0e lolen Minimum payload length
2 0x42 class Message class:Periodic Advertising Synchronization
3 0x00 method Message ID
4 uint8 sync Periodic advertising synchronization handle
5 uint8 adv_sid Advertising set identifier
6-11 bd_addr address Address of the advertiser
12 uint8 address_type Advertiser address type. Values:
  • 0: Public address
  • 1: Random address
13 uint8 adv_phy The advertiser PHY. Value:
  • 1: 1M PHY
  • 2: 2M PHY
  • 4: Coded PHY
14-15 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
16-17 uint16 clock_accuracy The advertiser clock accuracy.

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
}

sync_closed

This event indicates sync lost or a sync establishment procedure was cancelled.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x03 lolen Minimum payload length
2 0x42 class Message class:Periodic Advertising Synchronization
3 0x01 method Message ID
4-5 uint16 reason Result code
  • 0: success
  • Non-zero: an error occurred
For other values refer to the Error codes
6 uint8 sync Periodic advertising synchronization handle

API

/* event id*/
gecko_evt_sync_closed_id

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

sync_data

This event reports a received periodic advertising packet.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x05 lolen Minimum payload length
2 0x42 class Message class:Periodic Advertising Synchronization
3 0x02 method Message ID
4 uint8 sync Periodic advertising synchronization handle
5 int8 tx_power TX power value in the received packet header. Units: dBm
  • Valid value range: -127 to 126
  • Value 127: information unavailable
6 int8 rssi Signal strength indicator (RSSI) in the latest received packet. Units: dBm
  • Range: -127 to +20
7 uint8 data_status Data completeness:
  • 0: Complete
  • 1: Incomplete, more data to come in new events
  • 2: Incomplete, data truncated, no more to come
8 uint8array data Periodic advertising data

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
}

sync enumerations

sync_advertiser_clock_accuracy

These values indicate what is 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