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.
Create an advertise set with the sl_bt_advertiser_create_set command.
Configure and set advertising parameters for the advertising set as needed.
Set the advertising data with the sl_bt_legacy_advertiser_set_data or sl_bt_legacy_advertiser_generate_data command.
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_scan_request
Enumerations#
These values define the available discovery modes, which dictate how the device is visible to other devices in the legacy and extended advertising.
Address type to use for the legacy and extended advertising.
These values define the packet types in legacy and extended advertising.
Functions#
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 |
1910
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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. |
1923
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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 |
1938
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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)
[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.
2101
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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)
[in] | advertising_set | Advertising set handle |
[in] | flags | Configuration flags. Value: 0 or bitmask of Generic Advertising Configuration Flags
|
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.
2119
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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)
[in] | advertising_set | Advertising set handle |
[in] | interval_min | Minimum advertising interval. Value in units of 0.625 ms
|
[in] | interval_max | Maximum advertising interval. Value in units of 0.625 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.
|
[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.
2163
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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)
[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:
Recommended 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.
2195
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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)
[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.
2221
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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)
[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.
|
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
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.
2244
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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)
[in] | advertising_set | Advertising set handle |
[in] | addr_type | Enum sl_bt_gap_address_type_t. Address type. Values:
|
[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.
2290
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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)
[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.
2311
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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)
[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.
2327
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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)
[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.
2339
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x01040020
1884
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x12040020
1885
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x03040020
1886
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x04040020
1887
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x0b040020
1888
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x05040020
1889
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x10040020
1890
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x11040020
1891
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x0a040020
1892
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x02040020
1893
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x01040020
1894
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x12040020
1895
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x03040020
1896
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x04040020
1897
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x0b040020
1898
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x05040020
1899
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x10040020
1900
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x11040020
1901
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x0a040020
1902
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/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_idValue:
0x02040020
1903
of file /mnt/raid/workspaces/ws.iS2YF8Lrv/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h