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: LE 1M PHY

  • 2: LE 2M PHY

  • 4: LE 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: Data complete

  • 2: Data incomplete, data truncated, no more to come

8

uint8array

data

Periodic ddvertising 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