PAwR Advertiser#

PAwR Advertiser.

Provides support for advertising with Periodic Advertising with Responses (PAwR) trains.

Modules#

sl_bt_evt_pawr_advertiser_subevent_data_request

sl_bt_evt_pawr_advertiser_subevent_tx_failed

sl_bt_evt_pawr_advertiser_response_report

Functions#

sl_status_t
sl_bt_pawr_advertiser_start(uint8_t advertising_set, uint16_t interval_min, uint16_t interval_max, uint32_t flags, uint8_t num_subevents, uint8_t subevent_interval, uint8_t response_slot_delay, uint8_t response_slot_spacing, uint8_t response_slots)
sl_status_t
sl_bt_pawr_advertiser_set_subevent_data(uint8_t advertising_set, uint8_t subevent, uint8_t response_slot_start, uint8_t response_slot_count, size_t adv_data_len, const uint8_t *adv_data)
sl_status_t
sl_bt_pawr_advertiser_create_connection(uint8_t advertising_set, uint8_t subevent, bd_addr address, uint8_t address_type, uint8_t *connection)
sl_status_t
sl_bt_pawr_advertiser_stop(uint8_t advertising_set)

Function Documentation#

sl_bt_pawr_advertiser_start#

sl_status_t sl_bt_pawr_advertiser_start (uint8_t advertising_set, uint16_t interval_min, uint16_t interval_max, uint32_t flags, uint8_t num_subevents, uint8_t subevent_interval, uint8_t response_slot_delay, uint8_t response_slot_spacing, uint8_t response_slots)
Parameters
[in]advertising_set

The PAwR advertising set handle

[in]interval_min

Minimum periodic advertising interval. Value in units of 1.25 ms.

  • Range: 0x06 to 0xFFFF

  • Time range: 7.5 ms to 81.92 s

Default value: 100 ms

[in]interval_max

Maximum periodic advertising interval. Value in units of 1.25 ms.

  • Range: 0x06 to 0xFFFF

  • Time range: 7.5 ms to 81.92 s

  • Note: interval_max should be bigger than interval_min

Default value: 200 ms

[in]flags

Additional periodic advertising options. Value: 0 or bitmask of Periodic Advertising Configuration Flags

[in]num_subevents

The number of subevents.

  • Range: 0x01 to 0x80

[in]subevent_interval

Subevent interval. Value in units of 1.25 ms.

  • Range: 0x06 to 0xFF

  • Time range: 7.5 ms to 318.75 ms

[in]response_slot_delay

Time between the advertising packet in a subevent and the first response slot. Value in units of 1.25 ms.

  • Range: 0x01 to 0xFE

  • Time range: 1.25 ms to 317.5 ms

[in]response_slot_spacing

Time between response slots. Value in units of 0.125 ms.

  • Range: 0x02 to 0xFF

  • Time range: 0.25 ms to 31.875 ms

[in]response_slots

Number of subevent response slots.

  • Range: 0x01 to 0xFF

Start PAwR advertising on the specified advertising set.

According to the Bluetooth Core specification, PAwR advertising PDUs cannot be transmitted until at least one extended advertising event has been completed. If the application needs exact control over the extended advertising data and parameters, use the Advertiser class to configure the parameters of the advertising set and the Extended Advertiser class to set or generate the desired extended advertising data payload. If the application does not configure the parameters or set the data, the default parameters and empty advertising data are used for the extended advertising.

If the application has not already started extended advertising and the flag SL_BT_PERIODIC_ADVERTISER_AUTO_START_EXTENDED_ADVERTISING is set in flags, the stack will automatically start extended advertising with the parameters and extended advertising data currently configured to the advertising set. The application may stop the automatically started extended advertising using the sl_bt_advertiser_stop command.

If the application has not already started extended advertising and the flag SL_BT_PERIODIC_ADVERTISER_AUTO_START_EXTENDED_ADVERTISING is not set in flags, the stack will momentarily start extended advertising with the parameters and extended advertising data currently configured to the advertising set. Unless the application starts extended advertising before the first extended advertising event has completed, the stack will automatically stop the momentary extended advertising after the first extended advertising event.

PAwR advertising PDUs are transmitted on the secondary PHY configured for the advertising set with the sl_bt_extended_advertiser_set_phy command.

To stop PAwR advertising, use sl_bt_pawr_advertiser_stop command.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 6238 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_pawr_advertiser_set_subevent_data#

sl_status_t sl_bt_pawr_advertiser_set_subevent_data (uint8_t advertising_set, uint8_t subevent, uint8_t response_slot_start, uint8_t response_slot_count, size_t adv_data_len, const uint8_t * adv_data)
Parameters
[in]advertising_set

The PAwR advertising set handle

[in]subevent

The subevent in which the data is to be sent

[in]response_slot_start

The first response slot to be used in this subevent

[in]response_slot_count

The number of response slots to be used

[in]adv_data_len

Length of data in adv_data

[in]adv_data

Data to be sent in the specified subevent

Set data to be sent in the specified subevent of an active PAwR train. Data is transmitted only once and is discarded after it has been transmitted.

Data given to this command is passed to the Bluetooth controller, which will queue data and transmit it at the correct time. The application may always opportunistically try to queue more data with this command, but the controller may reject data and return an error if the queuing capacity is exceeded. In this case, the Bluetooth stack will trigger the sl_bt_evt_pawr_advertiser_subevent_data_request event later when the controller is ready to accept more data.

To ensure effective use of the available memory, applications are encouraged to observe the sl_bt_evt_pawr_advertiser_subevent_data_request events and set data for the subevents that are being requested and for which the application has data to send. Applications should also note that PAwR is an unreliable transport and cannot guarantee delivery. If reliability is required, the application must implement an acknowledgment mechanism using response slots of the PAwR train and set subevent data again for a re-transmission if it was not successfully delivered.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 6290 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_pawr_advertiser_create_connection#

sl_status_t sl_bt_pawr_advertiser_create_connection (uint8_t advertising_set, uint8_t subevent, bd_addr address, uint8_t address_type, uint8_t * connection)
Parameters
[in]advertising_set

The PAwR advertising set handle

[in]subevent

The subevent in which the connection request is to be sent

[in]address

Address of the device to connect to

[in]address_type

Enum sl_bt_gap_address_type_t. Address type of the device to connect to. Values:

  • sl_bt_gap_public_address (0x0): Public device address

  • sl_bt_gap_static_address (0x1): Static device address

  • sl_bt_gap_random_resolvable_address (0x2): Resolvable private random address

  • sl_bt_gap_random_nonresolvable_address (0x3): Non-resolvable private random address

  • sl_bt_gap_public_address_resolved_from_rpa (0x4): Public identity address resolved from a resolvable private address (RPA)

  • sl_bt_gap_static_address_resolved_from_rpa (0x5): Static identity address resolved from a resolvable private address (RPA)

[out]connection

Handle that will be assigned to the connection after the connection is established. This handle is valid only if the result code of this command is SL_STATUS_OK.

Initiate a connection request to a device that is synchronized to the specified active PAwR train. The connection is established on the secondary PHY configured for the advertising set with the sl_bt_extended_advertiser_set_phy command. The connection uses the parameters configured with command sl_bt_connection_set_default_parameters.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 6337 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_pawr_advertiser_stop#

sl_status_t sl_bt_pawr_advertiser_stop (uint8_t advertising_set)
Parameters
[in]advertising_set

The PAwR advertising set handle

Stop PAwR advertising on an advertising set. Counterpart to sl_bt_pawr_advertiser_start.

This command does not affect the enable state of the advertising set, i.e., legacy or extended advertising is not stopped.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 6356 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

Macro Definition Documentation#

sl_bt_cmd_pawr_advertiser_start_id#

#define sl_bt_cmd_pawr_advertiser_start_id
Value:
0x00550020

Definition at line 6026 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_pawr_advertiser_set_subevent_data_id#

#define sl_bt_cmd_pawr_advertiser_set_subevent_data_id
Value:
0x01550020

Definition at line 6027 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_pawr_advertiser_create_connection_id#

#define sl_bt_cmd_pawr_advertiser_create_connection_id
Value:
0x02550020

Definition at line 6028 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_pawr_advertiser_stop_id#

#define sl_bt_cmd_pawr_advertiser_stop_id
Value:
0x03550020

Definition at line 6029 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_pawr_advertiser_start_id#

#define sl_bt_rsp_pawr_advertiser_start_id
Value:
0x00550020

Definition at line 6030 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_pawr_advertiser_set_subevent_data_id#

#define sl_bt_rsp_pawr_advertiser_set_subevent_data_id
Value:
0x01550020

Definition at line 6031 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_pawr_advertiser_create_connection_id#

#define sl_bt_rsp_pawr_advertiser_create_connection_id
Value:
0x02550020

Definition at line 6032 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_pawr_advertiser_stop_id#

#define sl_bt_rsp_pawr_advertiser_stop_id
Value:
0x03550020

Definition at line 6033 of file /mnt/raid/workspaces/ws.XK183xwsq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h