Advertiser#

Advertiser.


Modules
sl_bt_evt_advertiser_timeout
Indicates the advertising of an advertising set has stopped, because the advertiser has completed the configured number of advertising events or the advertising has reached the configured duration.
sl_bt_evt_advertiser_scan_request
Reports any scan request received in advertising mode if the scan request notification is enabled.


Enumerations
enum	sl_bt_advertiser_connectable_mode_t { sl_bt_advertiser_non_connectable = 0x0, sl_bt_advertiser_directed_connectable = 0x1, sl_bt_advertiser_connectable_scannable = 0x2, sl_bt_advertiser_scannable_non_connectable = 0x3, sl_bt_advertiser_connectable_non_scannable = 0x4 }
	Advertiser Connectable Mode.
enum	sl_bt_advertiser_discoverable_mode_t { sl_bt_advertiser_non_discoverable = 0x0, sl_bt_advertiser_limited_discoverable = 0x1, sl_bt_advertiser_general_discoverable = 0x2, sl_bt_advertiser_broadcast = 0x3, sl_bt_advertiser_user_data = 0x4 }
	Advertiser Discoverable Mode.
enum	sl_bt_advertiser_adv_address_type_t { sl_bt_advertiser_identity_address = 0x0, sl_bt_advertiser_non_resolvable = 0x1}
	Advertising Address Type.


Functions
sl_status_t	sl_bt_advertiser_create_set (uint8_t *handle)
sl_status_t	sl_bt_advertiser_set_timing (uint8_t handle, uint32_t interval_min, uint32_t interval_max, uint16_t duration, uint8_t maxevents)
sl_status_t	sl_bt_advertiser_set_phy (uint8_t handle, uint8_t primary_phy, uint8_t secondary_phy)
sl_status_t	sl_bt_advertiser_set_channel_map (uint8_t handle, uint8_t channel_map)
sl_status_t	sl_bt_advertiser_set_tx_power (uint8_t handle, int16_t power, int16_t *set_power)
sl_status_t	sl_bt_advertiser_set_report_scan_request (uint8_t handle, uint8_t report_scan_req)
sl_status_t	sl_bt_advertiser_set_random_address (uint8_t handle, uint8_t addr_type, bd_addr address, bd_addr *address_out)
sl_status_t	sl_bt_advertiser_clear_random_address (uint8_t handle)
sl_status_t	sl_bt_advertiser_set_configuration (uint8_t handle, uint32_t configurations)
sl_status_t	sl_bt_advertiser_clear_configuration (uint8_t handle, uint32_t configurations)
sl_status_t	sl_bt_advertiser_set_data (uint8_t handle, uint8_t packet_type, size_t adv_data_len, const uint8_t *adv_data)
sl_status_t	sl_bt_advertiser_set_long_data (uint8_t handle, uint8_t packet_type)
sl_status_t	sl_bt_advertiser_start (uint8_t handle, uint8_t discover, uint8_t connect)
sl_status_t	sl_bt_advertiser_stop (uint8_t handle)
sl_status_t	sl_bt_advertiser_start_periodic_advertising (uint8_t handle, uint16_t interval_min, uint16_t interval_max, uint32_t flags)
sl_status_t	sl_bt_advertiser_stop_periodic_advertising (uint8_t handle)
sl_status_t	sl_bt_advertiser_delete_set (uint8_t handle)

Detailed Description#

Advertiser.

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

Enumeration Type Documentation#

sl_bt_advertiser_connectable_mode_t#

enum sl_bt_advertiser_connectable_mode_t

Advertiser Connectable Mode.


Enumerator
sl_bt_advertiser_non_connectable	(0x0) Non-connectable non-scannable.
sl_bt_advertiser_directed_connectable	(0x1) Directed connectable (RESERVED, DO NOT USE)
sl_bt_advertiser_connectable_scannable	(0x2) Undirected connectable scannable. This mode can only be used in legacy advertising PDUs.
sl_bt_advertiser_scannable_non_connectable	(0x3) Undirected scannable (Non-connectable but responds to scan requests)
sl_bt_advertiser_connectable_non_scannable	(0x4) Undirected connectable non-scannable. This mode can only be used in extended advertising PDUs.

sl_bt_advertiser_discoverable_mode_t#

enum sl_bt_advertiser_discoverable_mode_t

Advertiser Discoverable Mode.


Enumerator
sl_bt_advertiser_non_discoverable	(0x0) Not discoverable
sl_bt_advertiser_limited_discoverable	(0x1) Discoverable using both limited and general discovery procedures
sl_bt_advertiser_general_discoverable	(0x2) Discoverable using general discovery procedure
sl_bt_advertiser_broadcast	(0x3) Device is not discoverable in either limited or generic discovery procedure but may be discovered using the Observation procedure.
sl_bt_advertiser_user_data	(0x4) Send advertising and/or scan response data defined by the user. The limited/general discoverable flags are defined by the user.

sl_bt_advertiser_adv_address_type_t#

enum sl_bt_advertiser_adv_address_type_t

Advertising Address Type.


Enumerator
sl_bt_advertiser_identity_address	(0x0) Use public or static device address, or an identity address if privacy mode is enabled.
sl_bt_advertiser_non_resolvable	(0x1) Use non resolvable address type; advertising mode must also be non-connectable.

Function Documentation#

sl_bt_advertiser_create_set()#

sl_status_t sl_bt_advertiser_create_set ( uint8_t * handle )

Create an advertising set. The handle of the created advertising set is returned in response.

Parameters



[out]	`handle`	Advertising set handle

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_set_timing()#



sl_status_t sl_bt_advertiser_set_timing	(	uint8_t	`handle,`
		uint32_t	`interval_min,`
		uint32_t	`interval_max,`
		uint16_t	`duration,`
		uint8_t	`maxevents`
	)

Set the advertising timing parameters of the given advertising set. This setting will take effect next time that advertising is enabled.

Parameters



[in]	`handle`	Advertising set handle
[in]	`interval_min`	Minimum advertising interval. Value in units of 0.625 ms Range: 0x20 to 0xFFFF Time range: 20 ms to 40.96 s Default value: 100 ms
[in]	`interval_max`	Maximum advertising interval. Value in units of 0.625 ms Range: 0x20 to 0xFFFF Time range: 20 ms to 40.96 s Note: interval_max should be bigger than interval_min Default value: 200 ms
[in]	`duration`	Advertising duration for this advertising set. Value 0 indicates no advertising duration limit and advertising continues until it is disabled. A non-zero value sets the duration in units of 10 ms. The duration begins at the start of the first advertising event of this advertising set. Range: 0x0001 to 0xFFFF Time range: 10 ms to 655.35 s Default value: 0
[in]	`maxevents`	If non-zero, indicates the maximum number of advertising events to send before the advertiser is stopped. Value 0 indicates no maximum number limit. Default value: 0

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_set_phy()#



sl_status_t sl_bt_advertiser_set_phy	(	uint8_t	`handle,`
		uint8_t	`primary_phy,`
		uint8_t	`secondary_phy`
	)

Set advertising PHYs of the given advertising set. This setting will take effect next time that advertising is enabled. The invalid parameter error is returned if a PHY value is invalid or the device does not support a given PHY.

Parameters



[in]	`handle`	Advertising set handle
[in]	`primary_phy`	Enum sl_bt_gap_phy_type_t. The PHY on which the advertising packets are transmitted on the primary advertising channel. If legacy advertising PDUs are used, 1M PHY must be used. Values: sl_bt_gap_1m_phy (0x1): 1M PHY sl_bt_gap_coded_phy (0x4): Coded PHY, 125k (S=8) or 500k (S=2) Default value: sl_bt_gap_1m_phy
[in]	`secondary_phy`	Enum sl_bt_gap_phy_type_t. The PHY on which the advertising packets are transmitted on the secondary advertising channel. Values: sl_bt_gap_1m_phy (0x1): 1M PHY sl_bt_gap_2m_phy (0x2): 2M PHY sl_bt_gap_coded_phy (0x4): Coded PHY, 125k (S=8) or 500k (S=2) Default value: sl_bt_gap_1m_phy

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_set_channel_map()#



sl_status_t sl_bt_advertiser_set_channel_map	(	uint8_t	`handle,`
		uint8_t	`channel_map`
	)

Set the primary advertising channel map of the given advertising set. This setting will take effect next time that advertising is enabled.

Parameters



[in]	`handle`	Advertising set handle
[in]	`channel_map`	Advertising channel map which determines which of the three channels will be used for advertising. This value is given as a bitmask. Values: 1: Advertise on CH37 2: Advertise on CH38 3: Advertise on CH37 and CH38 4: Advertise on CH39 5: Advertise on CH37 and CH39 6: Advertise on CH38 and CH39 7: Advertise on all channels Recommended value: 7 Default value: 7

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_set_tx_power()#



sl_status_t sl_bt_advertiser_set_tx_power	(	uint8_t	`handle,`
		int16_t	`power,`
		int16_t *	`set_power`
	)

Limit the maximum advertising TX power on the given advertising set. If the value goes over the global value that was set using sl_bt_system_set_max_tx_power command, the global value will be the maximum limit. The maximum TX power of legacy advertising is further constrained to be less than +10 dBm. Extended advertising TX power can be +10 dBm and over if Adaptive Frequency Hopping is enabled.

This setting will take effect next time advertising is enabled.

By default, maximum advertising TX power is limited by the global value.

Parameters



[in]	`handle`	Advertising set handle
[in]	`power`	TX power in 0.1 dBm steps. For example, the value of 10 is 1 dBm and 55 is 5.5 dBm.
[out]	`set_power`	The selected maximum advertising TX power

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_set_report_scan_request()#



sl_status_t sl_bt_advertiser_set_report_scan_request	(	uint8_t	`handle,`
		uint8_t	`report_scan_req`
	)

Enable or disable the scan request notification of a given advertising set. This setting will take effect next time that advertising is enabled.

Parameters



[in]	`handle`	Advertising set handle
[in]	`report_scan_req`	If non-zero, enables scan request notification and scan requests will be reported as events.
Default value: 0

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

sl_bt_evt_advertiser_scan_request - Triggered when a scan request is received during advertising if the scan request notification is enabled by this command.

sl_bt_advertiser_set_random_address()#



sl_status_t sl_bt_advertiser_set_random_address	(	uint8_t	`handle,`
		uint8_t	`addr_type,`
		bd_addr	`address,`
		bd_addr *	`address_out`
	)

Set the advertiser on an advertising set to use a random address. This overrides the default advertiser address which is either the public device address programmed at production or the address written into persistent storage using sl_bt_system_set_identity_address command. This setting is stored in RAM only and does not change the identity address in persistent storage.

When setting a resolvable random address, the address parameter is ignored. The stack generates a private resolvable random address and set it as the advertiser address. The generated address is returned in the response.

To use the default advertiser address, remove this setting using sl_bt_advertiser_clear_random_address command.

Wrong state error is returned if advertising has been enabled on the advertising set. Invalid parameter error is returned if the advertising set handle is invalid or the address does not conforms to the Bluetooth specification.

Parameters



[in]	`handle`	Advertising set handle
[in]	`addr_type`	Address type: 1: Static device address 2: Private resolvable random address 3: Private non-resolvable random address. This type can only be used for non-connectable advertising.
[in]	`address`	The random address to set. Ignore this field when setting a resolvable random address.
[out]	`address_out`	The resolvable random address set for the advetiser. Ignore this field when setting other types of random address.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_clear_random_address()#

sl_status_t sl_bt_advertiser_clear_random_address ( uint8_t handle )

Clear the random address previously set for the advertiser address on an advertising set. A random address can be set using sl_bt_advertiser_set_random_address command. The default advertiser address will be used after this operation.

The error SL_STATUS_INVALID_STATE is returned if advertising has been enabled on the advertising set. An invalid parameter error is returned if the advertising set handle is invalid.

Parameters



[in]	`handle`	Advertising set handle

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_set_configuration()#



sl_status_t sl_bt_advertiser_set_configuration	(	uint8_t	`handle,`
		uint32_t	`configurations`
	)

Enable advertising configuration flags on the given advertising set. The configuration change will take effect next time that advertising is enabled.

These configuration flags can be disabled using sl_bt_advertiser_clear_configuration.

Parameters



[in]	`handle`	Advertising set handle
[in]	`configurations`	Advertising configuration flags to enable. This value can be a bitmask of multiple flags. Flags: 1 (Bit 0): Use legacy advertising PDUs. 2 (Bit 1): Omit advertiser's address from all PDUs (anonymous advertising). This flag is effective only in extended advertising. 4 (Bit 2): Use gap_non_resolvable address type. Advertising must be in non-connectable mode if this configuration is enabled. 8 (Bit 3): Include TX power in advertising packets. This flag is effective only in extended advertising. Default value: 1

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_clear_configuration()#



sl_status_t sl_bt_advertiser_clear_configuration	(	uint8_t	`handle,`
		uint32_t	`configurations`
	)

Disable advertising configuration flags on the given advertising set. The configuration change will take effect next time that advertising is enabled.

These configuration flags can be enabled using sl_bt_advertiser_set_configuration.

Parameters



[in]	`handle`	Advertising set handle
[in]	`configurations`	Advertising configuration flags to disable. This value can be a bitmask of multiple flags. See sl_bt_advertiser_set_configuration for possible flags.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_set_data()#



sl_status_t sl_bt_advertiser_set_data	(	uint8_t	`handle,`
		uint8_t	`packet_type,`
		size_t	`adv_data_len,`
		const uint8_t *	`adv_data`
	)

Set user-defined data in advertising packets, scan response packets, or periodic advertising packets. Maximum 31 bytes of data can be set for legacy advertising. Maximum 191 bytes of data can be set for connectable extended advertising. Maximum 253 bytes of data can be set for periodic and non-connectable extended advertising. For setting longer advertising data, use command sl_bt_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_advertiser_start. Periodic advertising mode can be enabled using command sl_bt_advertiser_start_periodic_advertising.

The invalid parameter error will be returned in the following situations:

Data length is more than 31 bytes but the advertiser can only advertise using legacy advertising PDUs.
Data is too long to fit into a single advertisement.
Set data of the advertising data packet when the advertiser is advertising in scannable mode using extended advertising PDUs.
Set data of the scan response data packet when the advertiser is advertising in connectable mode using extended advertising PDUs.

Note that the user-defined data may be overwritten by the system when the advertising is later enabled in a discoverable mode other than user_data.

Parameters



[in]	`handle`	Advertising set handle
[in]	`packet_type`	This value selects whether data is intended for advertising packets, scan response packets, or periodic advertising packets. 0: Advertising packets 1: Scan response packets 8: Periodic advertising packets
[in]	`adv_data_len`	Array length
[in]	`adv_data`	Data to be set

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_set_long_data()#



sl_status_t sl_bt_advertiser_set_long_data	(	uint8_t	`handle,`
		uint8_t	`packet_type`
	)

Set advertising data for a specified packet type and advertising set. Data currently in the system data buffer will be extracted as the advertising data. The buffer will be emptied after this command regardless of the completion status.

Prior to calling this command, add data to the buffer with one or multiple calls to sl_bt_system_data_buffer_write.

Maximum 31 bytes of data can be set for legacy advertising. Maximum 191 bytes of data can be set for connectable extended advertising. Maximum 1650 bytes of data can be set for periodic and non-connectable extended advertising, but advertising parameters may limit the amount of data that can be sent in a single advertisement.

See sl_bt_advertiser_set_data for more details on advertising data.

Parameters



[in]	`handle`	Advertising set handle
[in]	`packet_type`	This value selects whether data is intended for advertising packets, scan response packets, or periodic advertising packets. Values: 0: Advertising packets 1: Scan response packets 8: Periodic advertising packets

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_start()#



sl_status_t sl_bt_advertiser_start	(	uint8_t	`handle,`
		uint8_t	`discover,`
		uint8_t	`connect`
	)

Start advertising of a given advertising set with specified discoverable and connectable modes.

The number of concurrent advertising is limited by MAX_ADVERTISERS configuration.

The number of concurrent connectable advertising is also limited by MAX_CONNECTIONS configuration. For example, only one connectable advertising can be enabled if the device has (MAX_CONNECTIONS - 1) connections when this command is called. The limitation does not apply to non-connectable advertising.

The default advertising configuration in the stack is set to using legacy advertising PDUs on 1M PHY. The stack will automatically select extended advertising PDUs if either of the following has occurred with the default configuration:

The connectable mode is set to advertiser_connectable_non_scannable.
The primary advertising PHY is set to Coded PHY by sl_bt_advertiser_set_phy.
The user advertising data length is more than 31 bytes.
Periodic advertising is enabled.

If the currently set parameters can't be used, an error is returned. Specifically, this command fails with the connection limit exceeded error if it causes the number of connections exceeding the configured MAX_CONNECTIONS value. It fails with the invalid parameter error if one of the following use cases occurs:

Non-resolvable random address is used but the connectable mode is advertiser_connectable_scannable or advertiser_connectable_non_scannable.
advertiser_connectable_non_scannable is the connectable mode but using legacy advertising PDUs has been explicitly enabled with command sl_bt_advertiser_set_configuration.
Coded PHY is the primary advertising PHY but using legacy advertising PDUs has been explicitly enabled with command sl_bt_advertiser_set_configuration.
advertiser_connectable_scannable is the connectable mode but using extended advertising PDUs has been explicitly enabled or the primary advertising PHY is set to Coded PHY.

If advertising is enabled in user_data mode, use sl_bt_advertiser_set_data to set advertising and scan response data before issuing this command. When advertising is enabled in modes other than user_data, advertising and scan response data is generated by the stack using the following procedure:

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 slave 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.

Event sl_bt_evt_connection_opened will be received when a remote device opens a connection to the advertiser on this advertising set and also advertising on the given set 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 advertising with the current set has stopped.

Parameters



[in]	`handle`	Advertising set handle
[in]	`discover`	Enum sl_bt_advertiser_discoverable_mode_t. Discoverable mode. Values: sl_bt_advertiser_non_discoverable (0x0): Not discoverable sl_bt_advertiser_limited_discoverable (0x1): Discoverable using both limited and general discovery procedures sl_bt_advertiser_general_discoverable (0x2): Discoverable using general discovery procedure sl_bt_advertiser_broadcast (0x3): Device is not discoverable in either limited or generic discovery procedure but may be discovered using the Observation procedure. sl_bt_advertiser_user_data (0x4): Send advertising and/or scan response data defined by the user. The limited/general discoverable flags are defined by the user.
[in]	`connect`	Enum sl_bt_advertiser_connectable_mode_t. Connectable mode. Values sl_bt_advertiser_non_connectable (0x0): Non-connectable non-scannable. sl_bt_advertiser_directed_connectable (0x1): Directed connectable (RESERVED, DO NOT USE) sl_bt_advertiser_connectable_scannable (0x2): Undirected connectable scannable. This mode can only be used in legacy advertising PDUs. sl_bt_advertiser_scannable_non_connectable (0x3): Undirected scannable (Non-connectable but responds to scan requests) sl_bt_advertiser_connectable_non_scannable (0x4): Undirected connectable non-scannable. This mode can only be used in extended advertising PDUs.

Returns

SL_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 advertising has stopped on the given advertising set.
sl_bt_evt_connection_opened - Triggered when a remote device opens a connection to the advertiser on the specified advertising set and also advertising with the current set stops.

sl_bt_advertiser_stop()#

sl_status_t sl_bt_advertiser_stop ( uint8_t handle )

Stop the advertising of the given advertising set. Counterpart with sl_bt_advertiser_start.

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

Parameters



[in]	`handle`	Advertising set handle

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_start_periodic_advertising()#



sl_status_t sl_bt_advertiser_start_periodic_advertising	(	uint8_t	`handle,`
		uint16_t	`interval_min,`
		uint16_t	`interval_max,`
		uint32_t	`flags`
	)

Start periodic advertising on the given advertising set. The stack enables the advertising set automatically if the set was not enabled and the set can advertise using extended advertising PDUs beside the syncInfo, which is needed for the periodic advertising.

The invalid parameter error is returned if the application has configured legacy advertising PDUs or anonymous advertising, or the advertising set is enabled using legacy advertising PDUs.

To stop periodic advertising, use sl_bt_advertiser_stop_periodic_advertising command with the handle received in response from this command.

Parameters



[in]	`handle`	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`	Periodic advertising configurations. Bitmask of the following: Bit 0: Include TX power in advertising PDU

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_stop_periodic_advertising()#

sl_status_t sl_bt_advertiser_stop_periodic_advertising ( uint8_t handle )

Stop the periodic advertising on the given advertising set. Counterpart with sl_bt_advertiser_start_periodic_advertising.

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

Parameters



[in]	`handle`	Advertising set handle

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_advertiser_delete_set()#

sl_status_t sl_bt_advertiser_delete_set ( uint8_t handle )

Delete an advertising set.

Parameters



[in]	`handle`	Advertising set handle

Returns

SL_STATUS_OK if successful. Error code otherwise.