Extended Advertiser

Extended Advertiser.

Modules

Extended Advertising Configuration Flags
 

Enumerations

enum  sl_bt_extended_advertiser_connection_mode_t { sl_bt_extended_advertiser_non_connectable = 0x0, sl_bt_extended_advertiser_scannable = 0x3, sl_bt_extended_advertiser_connectable = 0x4 }
 These values define the available connection modes in extended advertising.
 

Functions

sl_status_t sl_bt_extended_advertiser_set_phy (uint8_t advertising_set, uint8_t primary_phy, uint8_t secondary_phy)
 
sl_status_t sl_bt_extended_advertiser_set_data (uint8_t advertising_set, size_t data_len, const uint8_t *data)
 
sl_status_t sl_bt_extended_advertiser_set_long_data (uint8_t advertising_set)
 
sl_status_t sl_bt_extended_advertiser_generate_data (uint8_t advertising_set, uint8_t discover)
 
sl_status_t sl_bt_extended_advertiser_start (uint8_t advertising_set, uint8_t connect, uint32_t flags)
 
sl_status_t sl_bt_extended_advertiser_start_directed (uint8_t advertising_set, uint8_t connect, uint32_t flags, bd_addr peer_addr, uint8_t peer_addr_type)
 

Detailed Description

Extended Advertiser.

The commands and events in this class are related to extended advertising functionalities in GAP peripheral and broadcaster roles.

Enumeration Type Documentation

◆ sl_bt_extended_advertiser_connection_mode_t

enum sl_bt_extended_advertiser_connection_mode_t

These values define the available connection modes in extended advertising.

Enumerator
sl_bt_extended_advertiser_non_connectable 

(0x0) Non-connectable and non-scannable extended advertising

sl_bt_extended_advertiser_scannable 

(0x3) Scannable extended advertising

sl_bt_extended_advertiser_connectable 

(0x4) Connectable extended advertising

Function Documentation

◆ sl_bt_extended_advertiser_set_phy()

sl_status_t sl_bt_extended_advertiser_set_phy ( uint8_t  advertising_set,
uint8_t  primary_phy,
uint8_t  secondary_phy 
)

Set advertising PHYs of the extended advertising on an advertising set. This setting will take effect next time the advertising is enabled. When advertising on the LE Coded PHY, coding scheme S=8 is used. The invalid parameter error is returned if a PHY value is invalid or the device does not support a given PHY.

Parameters
[in]advertising_setAdvertising set handle
[in]primary_phy

Enum sl_bt_gap_phy_t. The PHY on which the advertising packets are transmitted on the primary advertising channel. Values:

  • sl_bt_gap_phy_1m (0x1): 1M PHY
  • sl_bt_gap_phy_coded (0x4): Coded PHY, 125k (S=8)

Default value: sl_bt_gap_phy_1m

[in]secondary_phy

Enum sl_bt_gap_phy_t. The PHY on which the advertising packets are transmitted on the secondary advertising channel. Values:

  • sl_bt_gap_phy_1m (0x1): 1M PHY
  • sl_bt_gap_phy_2m (0x2): 2M PHY
  • sl_bt_gap_phy_coded (0x4): Coded PHY, 125k (S=8)

Default value: sl_bt_gap_phy_1m

Returns
SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_extended_advertiser_set_data()

sl_status_t sl_bt_extended_advertiser_set_data ( uint8_t  advertising_set,
size_t  data_len,
const uint8_t *  data 
)

Set user-defined data for extended advertising. This overwrites the existing advertising data packet and scan response packet on this advertising set regardless of whether the data was set for the legacy or extended advertising. Maximum 191 bytes of data can be set for connectable extended advertising. Maximum 253 bytes of data can be set for non-connectable extended advertising. For setting longer advertising data, use command sl_bt_extended_advertiser_set_long_data.

If advertising mode is currently enabled, the new advertising data will be used immediately. Advertising mode can be enabled using command sl_bt_extended_advertiser_start.

The invalid parameter error is returned if the data is too long to fit into a single advertisement.

Parameters
[in]advertising_setAdvertising set handle
[in]data_lenLength of data in data
[in]dataData to be set
Returns
SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_extended_advertiser_set_long_data()

sl_status_t sl_bt_extended_advertiser_set_long_data ( uint8_t  advertising_set)

Set long user-defined data for extended advertising. This overwrites the existing advertising data packet and scan response packet on this advertising set regardless of whether the data was set for the legacy or extended advertising.

Prior to calling this command, add data to the buffer with one or multiple calls to sl_bt_system_data_buffer_write. When this command is called, the data in the system data buffer is extracted as the advertising data. The buffer will be emptied after this command regardless of the completion status.

Maximum 191 bytes of data can be set for connectable extended advertising. Maximum 1650 bytes of data can be set for non-connectable extended advertising. Advertising parameters may limit the amount of data that can be sent in a single advertisement. See sl_bt_extended_advertiser_set_data for more details.

Parameters
[in]advertising_setAdvertising set handle
Returns
SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_extended_advertiser_generate_data()

sl_status_t sl_bt_extended_advertiser_generate_data ( uint8_t  advertising_set,
uint8_t  discover 
)

Ask the stack to generate the extended advertising data on an advertising set. Alternatively, user-defined advertising data can be set using the sl_bt_extended_advertiser_set_data command.

This overwrites the existing advertising data packet and scan response packet on this advertising set regardless of whether the data was set for the legacy or extended advertising.

If advertising mode is currently enabled, the new advertising data will be used immediately. To enable advertising mode, use command sl_bt_extended_advertiser_start.

See sl_bt_legacy_advertiser_generate_data for the advertising data generation logic.

Parameters
[in]advertising_setAdvertising set handle
[in]discoverEnum sl_bt_advertiser_discovery_mode_t. The discovery mode for the Flags data field in the packet. Values:
  • sl_bt_advertiser_non_discoverable (0x0): Not discoverable
  • sl_bt_advertiser_limited_discoverable (0x1): Discoverable by both limited and general discovery procedures
  • sl_bt_advertiser_general_discoverable (0x2): Discoverable by the general discovery procedure
Returns
SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_extended_advertiser_start()

sl_status_t sl_bt_extended_advertiser_start ( uint8_t  advertising_set,
uint8_t  connect,
uint32_t  flags 
)

Start undirected extended advertising on an advertising set with the specified connection mode. Use sl_bt_advertiser_stop to stop the advertising.

Use the sl_bt_extended_advertiser_set_data or sl_bt_extended_advertiser_generate_data command to set the advertising data before calling this command. Advertising data is added into the scan response packet if the connection mode is scannable. Otherwise, data is in the advertising data packet.

The number of concurrent connectable advertisings is limited by the connection number configuration. See sl_bt_legacy_advertiser_start for more details.

This command fails with the invalid parameter error if the advertising uses a non-resolvable random address but the connection mode is sl_bt_extended_advertiser_connectable.

Event sl_bt_evt_connection_opened will be received when a remote device opens a connection to the advertiser on this advertising set. As a result, the advertising stops.

Event sl_bt_evt_advertiser_timeout will be received when the number of advertising events set by sl_bt_advertiser_set_timing command is done and the advertising has stopped.

Parameters
[in]advertising_setAdvertising set handle
[in]connectEnum sl_bt_extended_advertiser_connection_mode_t. Connection mode. Values:
  • sl_bt_extended_advertiser_non_connectable (0x0): Non-connectable and non-scannable extended advertising
  • sl_bt_extended_advertiser_scannable (0x3): Scannable extended advertising
  • sl_bt_extended_advertiser_connectable (0x4): Connectable extended advertising
[in]flagsAdditional extended advertising options. Value: 0 or bitmask of Extended Advertising Configuration Flags
Returns
SL_STATUS_OK if successful. Error code otherwise.

Events

◆ sl_bt_extended_advertiser_start_directed()

sl_status_t sl_bt_extended_advertiser_start_directed ( uint8_t  advertising_set,
uint8_t  connect,
uint32_t  flags,
bd_addr  peer_addr,
uint8_t  peer_addr_type 
)

Start directed extended advertising on an advertising set with the specified peer target device and connection mode. Use sl_bt_advertiser_stop to stop the advertising.

The number of concurrent connectable advertisings is limited by the connection number configuration. See sl_bt_legacy_advertiser_start for more details.

This command fails with the invalid parameter error if the advertising uses a non-resolvable random address but the connection mode is sl_bt_extended_advertiser_connectable.

Event sl_bt_evt_connection_opened will be received when the target device opens a connection to the advertiser on this advertising set. As a result, the advertising stops.

Event sl_bt_evt_advertiser_timeout will be received when the advertising stops and no Bluetooth connection is opened to it.

Parameters
[in]advertising_setAdvertising set handle
[in]connectEnum sl_bt_extended_advertiser_connection_mode_t. Connection mode. Values:
  • sl_bt_extended_advertiser_non_connectable (0x0): Non-connectable and non-scannable extended advertising
  • sl_bt_extended_advertiser_scannable (0x3): Scannable extended advertising
  • sl_bt_extended_advertiser_connectable (0x4): Connectable extended advertising
[in]flagsAdditional extended advertising options. Value: 0 or bitmask of Extended Advertising Configuration Flags
[in]peer_addrAddress of the peer target device the advertising is directed to
[in]peer_addr_typePeer target device address type. Values:
  • 0: Public address
  • 1: Random address
Returns
SL_STATUS_OK if successful. Error code otherwise.

Events