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.

Modules#

Generic Advertising Configuration Flags

sl_bt_evt_advertiser_timeout

sl_bt_evt_advertiser_scan_request

Enumerations#

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
}

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)

Macros#

Enumeration Documentation#

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


Definition at line 1910 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1923 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1938 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 2101 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 : 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 2119 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 : 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 : 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 : 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.

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 2163 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 : 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 2195 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 2221 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 : 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 2244 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 2290 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 2311 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 2327 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 2339 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1884 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1885 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1886 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1887 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1888 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1889 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1890 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1891 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1892 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1893 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1894 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1895 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1896 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1897 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1898 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1899 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1900 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1901 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1902 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/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 1903 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h