Legacy Advertiser#

Legacy Advertiser.




Enumerations
enum	sl_bt_legacy_advertiser_connection_mode_t { sl_bt_legacy_advertiser_non_connectable = 0x0,
sl_bt_legacy_advertiser_connectable = 0x2,
sl_bt_legacy_advertiser_scannable = 0x3
}
	These values define the available connection modes of undirected legacy advertising.

enum	sl_bt_legacy_advertiser_directed_connection_mode_t { sl_bt_legacy_advertiser_high_duty_directed_connectable = 0x1,
sl_bt_legacy_advertiser_low_duty_directed_connectable = 0x5
}
	These values define the available connection modes of directed legacy advertising.




Functions
sl_status_t	sl_bt_legacy_advertiser_set_data (uint8_t advertising_set, uint8_t type, size_t data_len, const uint8_t *data)

sl_status_t	sl_bt_legacy_advertiser_generate_data (uint8_t advertising_set, uint8_t discover)

sl_status_t	sl_bt_legacy_advertiser_start (uint8_t advertising_set, uint8_t connect)

sl_status_t	sl_bt_legacy_advertiser_start_directed (uint8_t advertising_set, uint8_t connect, bd_addr peer_addr, uint8_t peer_addr_type)

Detailed Description#

Legacy Advertiser.

The commands and events in this class are related to legacy advertising functionalities.

Enumeration Type Documentation#

◆sl_bt_legacy_advertiser_connection_mode_t#



enum sl_bt_legacy_advertiser_connection_mode_t

These values define the available connection modes of undirected legacy advertising.


Enumerator
sl_bt_legacy_advertiser_non_connectable	(0x0) Undirected non-connectable and non-scannable legacy advertising
sl_bt_legacy_advertiser_connectable	(0x2) Undirected connectable and scannable legacy advertising
sl_bt_legacy_advertiser_scannable	(0x3) Undirected scannable and non-connectable legacy advertising

◆sl_bt_legacy_advertiser_directed_connection_mode_t#



enum sl_bt_legacy_advertiser_directed_connection_mode_t

These values define the available connection modes of directed legacy advertising.


Enumerator
sl_bt_legacy_advertiser_high_duty_directed_connectable	(0x1) High duty cycle directed connectable legacy advertising
sl_bt_legacy_advertiser_low_duty_directed_connectable	(0x5) Low duty cycle directed connectable legacy advertising

Function Documentation#

◆sl_bt_legacy_advertiser_set_data()#



sl_status_t sl_bt_legacy_advertiser_set_data	(	uint8_t	`advertising_set,`
		uint8_t	`type,`
		size_t	`data_len,`
		const uint8_t *	`data`
	)

Set user-defined advertising data packet or scan response packet on an advertising set. 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 31 bytes of data can be set with this command.

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

Parameters



[in]	`advertising_set`	Advertising set handle
[in]	`type`	Enum sl_bt_advertiser_packet_type_t. The advertising packet type
[in]	`data_len`	Length of data in `data`
[in]	`data`	Data to set

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_legacy_advertiser_generate_data()#



sl_status_t sl_bt_legacy_advertiser_generate_data	(	uint8_t	`advertising_set,`
		uint8_t	`discover`
	)

Ask the stack to generate the advertising data packet and scan response packet on an advertising set. Alternatively, the user-defined advertising data can be set using the sl_bt_legacy_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_legacy_advertiser_start.

The stack generates the advertising data and scan response packet using the following logic.

Add a flags field to advertising data.
Add a TX power level field to advertising data if the TX power service exists in the local GATT database.
Add a peripheral connection interval range field to advertising data if the GAP peripheral preferred connection parameters characteristic exists in the local GATT database.
Add a list of 16-bit service UUIDs to advertising data if there are one or more 16-bit service UUIDs to advertise. The list is complete if all advertised 16-bit UUIDs are in advertising data. Otherwise, the list is incomplete.
Add a list of 128-bit service UUIDs to advertising data if there are one or more 128-bit service UUIDs to advertise and there is still free space for this field. The list is complete if all advertised 128-bit UUIDs are in advertising data. Otherwise, the list is incomplete. Note that an advertising data packet can contain at most one 128-bit service UUID.
Try to add the full local name to advertising data if the device is not in privacy mode. If the full local name does not fit into the remaining free space, the advertised name is a shortened version by cutting off the end if the free space has at least 6 bytes. Otherwise, the local name is added to scan response data.

Parameters



[in]	`advertising_set`	Advertising set handle
[in]	`discover`	Enum 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 |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_legacy_advertiser_start()#



sl_status_t sl_bt_legacy_advertiser_start	(	uint8_t	`advertising_set,`
		uint8_t	`connect`
	)

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

Use the sl_bt_legacy_advertiser_set_data or sl_bt_legacy_advertiser_generate_data command to set the advertising data before calling this command. The advertising data is added into the advertising data packet and scan response packet if the connection mode is connectable and/or scannable. The data is only added into the advertising data packet when the connection mode is non-connectable and non-scannable.

The number of concurrent connectable advertisings is limited by the number of connections reserved by the user application (the SL_BT_CONFIG_MAX_CONNECTIONS configuration) and the number reserved by other software components (the SL_BT_COMPONENT_CONNECTIONS configuration). This command fails with the connection limit exceeded error if it may cause the number of connections exceeding the configured value in future. For example, only one connectable advertising can be enabled if the device has (SL_BT_CONFIG_MAX_CONNECTIONS + SL_BT_COMPONENT_CONNECTIONS - 1) connections. This limitation does not apply to non-connectable advertising.

This command fails with the invalid parameter error if non-resolvable random address is used but the connection mode is sl_bt_legacy_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_set`	Advertising set handle
[in]	`connect`	Enum sl_bt_legacy_advertiser_connection_mode_t. Connection mode. Values:* sl_bt_legacy_advertiser_non_connectable (0x0): Undirected non-connectable and non-scannable legacy advertising

sl_bt_legacy_advertiser_connectable (0x2): Undirected connectable and scannable legacy advertising
sl_bt_legacy_advertiser_scannable (0x3): Undirected scannable and non-connectable legacy advertising |

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

sl_bt_evt_advertiser_timeout - Triggered when the number of advertising events set by sl_bt_advertiser_set_timing command is done and the advertising has stopped.
sl_bt_evt_connection_opened - Triggered when a remote device opens a connection to the advertiser and the advertising has stopped.

◆sl_bt_legacy_advertiser_start_directed()#



sl_status_t sl_bt_legacy_advertiser_start_directed	(	uint8_t	`advertising_set,`
		uint8_t	`connect,`
		bd_addr	`peer_addr,`
		uint8_t	`peer_addr_type`
	)

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

Directed legacy advertising does not allow any advertising data. When the connection mode is sl_bt_legacy_advertiser_high_duty_directed_connectable, the stack defaults the advertising duration to 0.64 s if the application has not set the parameter. The duration is reduced to 1.28 s if the application has set a larger duration value.

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 non-resolvable random address is set as the advertising address.

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_set`	Advertising set handle
[in]	`connect`	Enum sl_bt_legacy_advertiser_directed_connection_mode_t. Connection mode. Values:* sl_bt_legacy_advertiser_high_duty_directed_connectable (0x1): High duty cycle directed connectable legacy advertising

sl_bt_legacy_advertiser_low_duty_directed_connectable (0x5): Low duty cycle directed connectable legacy advertising | | [in] | peer_addr | Address of the peer target device the advertising is directed to | | [in] | peer_addr_type | Peer target device address type. Values:* 0: Public address
1: Random address |

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

sl_bt_evt_advertiser_timeout - Triggered when the number of advertising events set by sl_bt_advertiser_set_timing command is done and the advertising has stopped.
sl_bt_evt_connection_opened - Triggered when a remote device opens a connection to the advertiser and the advertising has stopped.