Advertiser#

Advertiser.

This is the base class of legacy, extended, and periodic advertisings for common functionalities including advertising set management, TX power setting, advertising address, and so on.

On an advertising set, either the legacy or extended advertising can be enabled at a time but they cannot be enabled simultaneously on the same advertising set. For example, the following sequence shows how to start the legacy advertising on an advertising set. Starting the extended advertising is similar. The only difference is to use the extended_advertiser API class.

  1. Create an advertise set with the sl_bt_advertiser_create_set command.

  2. Configure and set advertising parameters for the advertising set as needed.

  3. Set the advertising data with the sl_bt_legacy_advertiser_set_data or sl_bt_legacy_advertiser_generate_data command.

  4. Start the legacy advertising with the sl_bt_legacy_advertiser_start command.

Periodic advertising can be enabled independently on the advertising set regardless of the state of the legacy or extended advertising. However, to ensure that scanners can find the periodic advertising information and establish a synchronization, the extended advertising must be enabled simultaneously with the periodic advertising.

When the bluetooth_feature_legacy_advertiser, bluetooth_feature_extended_advertiser or bluetooth_feature_periodic_advertiser component is included by the application, commands that have been superseded by the new classes are no longer available for use in the advertiser class. Calling them will receive SL_STATUS_NOT_SUPPORTED error code. These commands are as follows: sl_bt_advertiser_set_phy, sl_bt_advertiser_set_configuration, sl_bt_advertiser_clear_configuration, sl_bt_advertiser_set_data, sl_bt_advertiser_set_long_data, sl_bt_advertiser_start, sl_bt_advertiser_start_periodic_advertising, and sl_bt_advertiser_stop_periodic_advertising. See the command descriptions for the replacements.

Modules#

Generic Advertising Configuration Flags

sl_bt_evt_advertiser_timeout

sl_bt_evt_advertiser_scan_request

Enumerations#

enum
sl_bt_advertiser_connection_mode_t {
sl_bt_advertiser_non_connectable = 0x0
sl_bt_advertiser_connectable_scannable = 0x2
sl_bt_advertiser_scannable_non_connectable = 0x3
sl_bt_advertiser_connectable_non_scannable = 0x4
}

These values define the available connection modes, which indicate whether the device accepts connection requests or scan requests.

enum
sl_bt_advertiser_discovery_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
}

These values define the available discovery modes, which dictate how the device is visible to other devices in the legacy and extended advertising.

enum
sl_bt_advertiser_adv_address_type_t {
sl_bt_advertiser_identity_address = 0x0
sl_bt_advertiser_non_resolvable = 0x1
}

Address type to use for the legacy and extended advertising.

enum
sl_bt_advertiser_packet_type_t {
sl_bt_advertiser_advertising_data_packet = 0x0
sl_bt_advertiser_scan_response_packet = 0x1
}

These values define the packet types in legacy and extended advertising.

Functions#

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

Macros#

Enumeration Documentation#

sl_bt_advertiser_connection_mode_t#

sl_bt_advertiser_connection_mode_t

These values define the available connection modes, which indicate whether the device accepts connection requests or scan requests.

Enumerator
sl_bt_advertiser_non_connectable

(0x0) Non-connectable non-scannable

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.


Definition at line 1955 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_discovery_mode_t#

sl_bt_advertiser_discovery_mode_t

These values define the available discovery modes, which dictate how the device is visible to other devices in the legacy and extended advertising.

Enumerator
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

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 discovery mode is defined by the user.


Definition at line 1982 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_adv_address_type_t#

sl_bt_advertiser_adv_address_type_t

Address type to use for the legacy and extended advertising.

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; the advertising must be non-connectable.


Definition at line 2006 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_packet_type_t#

sl_bt_advertiser_packet_type_t

These values define the packet types in legacy and extended advertising.

Enumerator
sl_bt_advertiser_advertising_data_packet

(0x0) Advertising data packet

sl_bt_advertiser_scan_response_packet

(0x1) Scan response packet


Definition at line 2021 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

Function Documentation#

sl_bt_advertiser_create_set#

sl_status_t sl_bt_advertiser_create_set (uint8_t * handle)
Parameters
[out]handle

Advertising set handle

Create an advertising set that can be used for legacy, extended, or periodic advertising. The handle of the created advertising set is returned in response if the operation succeeds.

The maximum number of advertising sets for user advertisers is limited by the SL_BT_CONFIG_USER_ADVERTISERS configuration.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2186 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_configure#

sl_status_t sl_bt_advertiser_configure (uint8_t advertising_set, uint32_t flags)
Parameters
[in]advertising_set

Advertising set handle

[in]flags

Configuration flags. Value: 0 or bitmask of Generic Advertising Configuration Flags

Default value: 0

Configure the legacy and extended advertising on an advertising set. The configuration will take effect next time the legacy or extended advertising is enabled.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2204 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_set_timing#

sl_status_t sl_bt_advertiser_set_timing (uint8_t advertising_set, uint32_t interval_min, uint32_t interval_max, uint16_t duration, uint8_t maxevents)
Parameters
[in]advertising_set

Advertising set handle

[in]interval_min

Minimum advertising interval. Value in units of 0.625 ms

  • Range: 0x20 to 0xFFFFFF

  • Time range: 20 ms to 10485.759375 s

Default value: 100 ms

[in]interval_max

Maximum advertising interval. Value in units of 0.625 ms

  • Range: 0x20 to 0xFFFFFF

  • Time range: 20 ms to 10485.759375 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

Set the timing parameters for legacy or extended advertising on an advertising set. This setting will take effect next time the legacy or extended advertising is enabled.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2249 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_set_channel_map#

sl_status_t sl_bt_advertiser_set_channel_map (uint8_t advertising_set, uint8_t channel_map)
Parameters
[in]advertising_set

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

Set the primary advertising channel map on an advertising set. This setting will take effect next time when the legacy or extended advertising is enabled.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2281 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_set_tx_power#

sl_status_t sl_bt_advertiser_set_tx_power (uint8_t advertising_set, int16_t power, int16_t * set_power)
Parameters
[in]advertising_set

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

Limit the maximum advertising TX power on an advertising set. If the value goes over the global value that was set using the sl_bt_system_set_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 has no effect on periodic advertising.

This setting will take effect next time the legacy or extended advertising is enabled.

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

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2307 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_set_report_scan_request#

sl_status_t sl_bt_advertiser_set_report_scan_request (uint8_t advertising_set, uint8_t report_scan_req)
Parameters
[in]advertising_set

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

Enable or disable the scan request notification on an advertising set. This setting will take effect next time the legacy or extended advertising is enabled.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 2333 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_set_random_address#

sl_status_t sl_bt_advertiser_set_random_address (uint8_t advertising_set, uint8_t addr_type, bd_addr address, bd_addr * address_out)
Parameters
[in]advertising_set

Advertising set handle

[in]addr_type

Enum sl_bt_gap_address_type_t. Address type. Values:

  • 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. 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 advertiser. Ignore this field when setting other types of random addresses.

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. In privacy mode, the stack does not change an advertiser address set by this command. To ensure that the stack can manage the address update periodically in privacy mode, the address setting should be removed with the sl_bt_advertiser_clear_random_address command.

When setting a resolvable random address, the address parameter is ignored. The stack generates one and set it as the advertiser address. The generated address is returned in the response. To enhance the privacy, the application should schedule periodic address updates by calling this command periodically. Use different schedules for different advertising sets.

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 conform to the Bluetooth specification.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2379 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_clear_random_address#

sl_status_t sl_bt_advertiser_clear_random_address (uint8_t advertising_set)
Parameters
[in]advertising_set

Advertising set handle

Clear the random address previously set for the advertiser address on an advertising set. To set a random address, use 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.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2400 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_stop#

sl_status_t sl_bt_advertiser_stop (uint8_t advertising_set)
Parameters
[in]advertising_set

Advertising set handle

Stop the legacy or extended advertising on an advertising set. Counterpart with sl_bt_legacy_advertiser_start or sl_bt_extended_advertiser_start.

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

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2416 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_delete_set#

sl_status_t sl_bt_advertiser_delete_set (uint8_t advertising_set)
Parameters
[in]advertising_set

Advertising set handle

Delete an advertising set. Any enabled legacy, extended, or periodic advertising is stopped before the deletion.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2428 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_set_phy#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_advertiser_set_phy (uint8_t advertising_set, uint8_t primary_phy, uint8_t secondary_phy)
Parameters
[in]advertising_set

Advertising 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. If legacy advertising PDUs are used, 1M PHY must be used. 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

Deprecated and replaced by sl_bt_extended_advertiser_set_phy.

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

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2464 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_set_configuration#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_advertiser_set_configuration (uint8_t advertising_set, uint32_t configurations)
Parameters
[in]advertising_set

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 a non-resolvable private address. When this configuration is enabled, the advertising must use non-connectable mode. The stack generates a non-resolvable private address for the advertising set and the stack will update the address periodically when the privacy mode is enabled. This configuration is ignored if the advertiser address has been set with the sl_bt_advertiser_set_random_address command.

  • 8 (Bit 3): Include TX power in advertising packets. This flag is effective only in extended advertising.

  • 16 (Bit 4): Use the device identity address when the privacy mode is enabled in the stack. This configuration is ignored if the configuration of using non-resolvable private address is enabled or the advertising address has been set with the sl_bt_advertiser_set_random_address command.

Default value: 1

Deprecated and replaced by sl_bt_advertiser_configure command.

Enable advertising configuration flags on an advertising set. The configuration change will take effect next time the legacy or extended advertising is enabled.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2504 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_clear_configuration#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_advertiser_clear_configuration (uint8_t advertising_set, uint32_t configurations)
Parameters
[in]advertising_set

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.

Deprecated and replaced by sl_bt_advertiser_configure command.

Disable advertising configuration flags on an advertising set. The configuration change will take effect next time the legacy or extended advertising is enabled.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2523 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_set_data#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_advertiser_set_data (uint8_t advertising_set, uint8_t packet_type, size_t adv_data_len, const uint8_t * adv_data)
Parameters
[in]advertising_set

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

Length of data in adv_data

[in]adv_data

Data to be set

Deprecated and replaced by sl_bt_legacy_advertiser_set_data for legacy advertising PDUs, sl_bt_extended_advertiser_set_data for extended advertising PDUs, and sl_bt_periodic_advertiser_set_data for periodic advertising PDUs.

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 scannable advertising is enabled using extended advertising PDUs.

  • Set data of the scan response data packet when the connectable advertising is enabled using extended advertising PDUs.

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

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2570 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_set_long_data#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_advertiser_set_long_data (uint8_t advertising_set, uint8_t packet_type)
Parameters
[in]advertising_set

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

Deprecated and replaced by sl_bt_extended_advertiser_set_long_data for extended advertising PDUs and sl_bt_periodic_advertiser_set_long_data for periodic advertising PDUs.

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.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2608 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_start#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_advertiser_start (uint8_t advertising_set, uint8_t discover, uint8_t connect)
Parameters
[in]advertising_set

Advertising set handle

[in]discover

Enum sl_bt_advertiser_discovery_mode_t. Discovery mode. 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

  • 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 discovery mode is defined by the user.

[in]connect

Enum sl_bt_advertiser_connection_mode_t. Connection mode. Values:

  • sl_bt_advertiser_non_connectable (0x0): Non-connectable non-scannable

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

Deprecated and replaced by sl_bt_legacy_advertiser_start and sl_bt_extended_advertiser_start commands.

Start the legacy or extended advertising on an advertising set with specified discovery and connection modes.

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.

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:

  1. The connection mode is set to sl_bt_advertiser_connectable_non_scannable.

  2. The primary advertising PHY is set to Coded PHY by sl_bt_extended_advertiser_set_phy.

  3. The user advertising data length is more than 31 bytes.

  4. Periodic advertising is enabled.

This command fails with the invalid parameter error if one of the following cases occurs:

  1. Non-resolvable random address is used but the connection mode is advertiser_connectable_scannable or advertiser_connectable_non_scannable.

  2. advertiser_connectable_non_scannable is the connection mode but using legacy advertising PDUs has been explicitly enabled with command sl_bt_advertiser_set_configuration.

  3. Coded PHY is the primary advertising PHY but using legacy advertising PDUs has been explicitly enabled with command sl_bt_advertiser_set_configuration.

  4. advertiser_connectable_scannable is the connection 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:

  1. Add a flags field to advertising data.

  2. Add a TX power level field to advertising data if the TX power service exists in the local GATT database.

  3. Add a peripheral connection interval range field to advertising data if the GAP peripheral preferred connection parameters characteristic exists in the local GATT database.

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

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

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

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 2726 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_start_periodic_advertising#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_advertiser_start_periodic_advertising (uint8_t advertising_set, uint16_t interval_min, uint16_t interval_max, uint32_t flags)
Parameters
[in]advertising_set

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

Deprecated and replaced by sl_bt_periodic_advertiser_start command.

Start periodic advertising on an 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.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2771 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_advertiser_stop_periodic_advertising#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_advertiser_stop_periodic_advertising (uint8_t advertising_set)
Parameters
[in]advertising_set

Advertising set handle

Deprecated and replaced by sl_bt_periodic_advertiser_stop command.

Stop periodic advertising on an 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.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 2792 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

Macro Definition Documentation#

sl_bt_cmd_advertiser_create_set_id#

#define sl_bt_cmd_advertiser_create_set_id
Value:
0x01040020

Definition at line 1914 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_configure_id#

#define sl_bt_cmd_advertiser_configure_id
Value:
0x12040020

Definition at line 1915 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_set_timing_id#

#define sl_bt_cmd_advertiser_set_timing_id
Value:
0x03040020

Definition at line 1916 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_set_channel_map_id#

#define sl_bt_cmd_advertiser_set_channel_map_id
Value:
0x04040020

Definition at line 1917 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_set_tx_power_id#

#define sl_bt_cmd_advertiser_set_tx_power_id
Value:
0x0b040020

Definition at line 1918 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_set_report_scan_request_id#

#define sl_bt_cmd_advertiser_set_report_scan_request_id
Value:
0x05040020

Definition at line 1919 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_set_random_address_id#

#define sl_bt_cmd_advertiser_set_random_address_id
Value:
0x10040020

Definition at line 1920 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_clear_random_address_id#

#define sl_bt_cmd_advertiser_clear_random_address_id
Value:
0x11040020

Definition at line 1921 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_stop_id#

#define sl_bt_cmd_advertiser_stop_id
Value:
0x0a040020

Definition at line 1922 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_delete_set_id#

#define sl_bt_cmd_advertiser_delete_set_id
Value:
0x02040020

Definition at line 1923 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_set_phy_id#

#define sl_bt_cmd_advertiser_set_phy_id
Value:
0x06040020

Definition at line 1924 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_set_configuration_id#

#define sl_bt_cmd_advertiser_set_configuration_id
Value:
0x07040020

Definition at line 1925 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_clear_configuration_id#

#define sl_bt_cmd_advertiser_clear_configuration_id
Value:
0x08040020

Definition at line 1926 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_set_data_id#

#define sl_bt_cmd_advertiser_set_data_id
Value:
0x0f040020

Definition at line 1927 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_set_long_data_id#

#define sl_bt_cmd_advertiser_set_long_data_id
Value:
0x0e040020

Definition at line 1928 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_start_id#

#define sl_bt_cmd_advertiser_start_id
Value:
0x09040020

Definition at line 1929 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_start_periodic_advertising_id#

#define sl_bt_cmd_advertiser_start_periodic_advertising_id
Value:
0x0c040020

Definition at line 1930 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_advertiser_stop_periodic_advertising_id#

#define sl_bt_cmd_advertiser_stop_periodic_advertising_id
Value:
0x0d040020

Definition at line 1931 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_create_set_id#

#define sl_bt_rsp_advertiser_create_set_id
Value:
0x01040020

Definition at line 1932 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_configure_id#

#define sl_bt_rsp_advertiser_configure_id
Value:
0x12040020

Definition at line 1933 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_set_timing_id#

#define sl_bt_rsp_advertiser_set_timing_id
Value:
0x03040020

Definition at line 1934 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_set_channel_map_id#

#define sl_bt_rsp_advertiser_set_channel_map_id
Value:
0x04040020

Definition at line 1935 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_set_tx_power_id#

#define sl_bt_rsp_advertiser_set_tx_power_id
Value:
0x0b040020

Definition at line 1936 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_set_report_scan_request_id#

#define sl_bt_rsp_advertiser_set_report_scan_request_id
Value:
0x05040020

Definition at line 1937 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_set_random_address_id#

#define sl_bt_rsp_advertiser_set_random_address_id
Value:
0x10040020

Definition at line 1938 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_clear_random_address_id#

#define sl_bt_rsp_advertiser_clear_random_address_id
Value:
0x11040020

Definition at line 1939 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_stop_id#

#define sl_bt_rsp_advertiser_stop_id
Value:
0x0a040020

Definition at line 1940 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_delete_set_id#

#define sl_bt_rsp_advertiser_delete_set_id
Value:
0x02040020

Definition at line 1941 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_set_phy_id#

#define sl_bt_rsp_advertiser_set_phy_id
Value:
0x06040020

Definition at line 1942 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_set_configuration_id#

#define sl_bt_rsp_advertiser_set_configuration_id
Value:
0x07040020

Definition at line 1943 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_clear_configuration_id#

#define sl_bt_rsp_advertiser_clear_configuration_id
Value:
0x08040020

Definition at line 1944 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_set_data_id#

#define sl_bt_rsp_advertiser_set_data_id
Value:
0x0f040020

Definition at line 1945 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_set_long_data_id#

#define sl_bt_rsp_advertiser_set_long_data_id
Value:
0x0e040020

Definition at line 1946 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_start_id#

#define sl_bt_rsp_advertiser_start_id
Value:
0x09040020

Definition at line 1947 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_start_periodic_advertising_id#

#define sl_bt_rsp_advertiser_start_periodic_advertising_id
Value:
0x0c040020

Definition at line 1948 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_advertiser_stop_periodic_advertising_id#

#define sl_bt_rsp_advertiser_stop_periodic_advertising_id
Value:
0x0d040020

Definition at line 1949 of file /mnt/raid/workspaces/ws.0zwF9W456/overlay/gsdk/protocol/bluetooth/build_debug/bt_api/sw/bgapi/inc/sl_bt_api.h