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 |