Bluetooth LE advertising providers
The Bluetooth LE advertising providers subsystem manages advertising data and scan response data. The subsystem does not control Bluetooth LE advertising by itself.
Overview
The Bluetooth LE advertising providers subsystem acts as a middleware between data providers and a module that controls Bluetooth advertising. The module that controls the Bluetooth advertising can use the subsystem’s API to get advertising data and scan response data. On the API call, the Bluetooth LE advertising providers subsystem gets data from providers and passes the data to the module that controls Bluetooth advertising.
Providers
The subsystem gets both advertising data and scan response data from providers. A provider manages a single element that is part of either advertising data or scan response data.
The nRF Connect SDK provides a set of predefined data providers. An application can also define application-specific data providers.
Application-specific providers
An application-specific provider must implement bt_le_adv_prov_data_get()
callback and register it using one of the following macros:
BT_LE_ADV_PROV_AD_PROVIDER_REGISTER
- The macro registers provider that appends data to advertising packets.BT_LE_ADV_PROV_SD_PROVIDER_REGISTER
- The macro registers provider that appends data to scan response packets.
When the callback is called, the provider must fill in the Bluetooth data structure passed as a callback argument. Apart from filling the Bluetooth data structure, the provider can also perform any of the following actions:
Fill out the feedback structure (
bt_le_adv_prov_feedback
) to provide additional information to the module that controls Bluetooth LE advertising.Return an error code. The error value of
-ENOENT
is used to inform that provider desists from providing data. In that case, the provider does not fill in the Bluetooth data structure. This error code is not forwarded to the module that controls Bluetooth LE advertising. Other negative values denote provider-specific errors, which are forwarded directly to the module that controls Bluetooth LE advertising.
The provided Bluetooth data can depend on any of the following options:
Bluetooth advertising state passed as function argument (
bt_le_adv_prov_adv_state
).Calls of the provider’s dedicated API, if the provider exposes such an API.
For example, a provider may fill in the Bluetooth data only if the used Bluetooth local identity has no bond.
The provider returns -ENOENT
to desist from providing data if bonded.
Examples of provider implementations can be found in the subsys/bluetooth/adv_prov/providers/
folder.
Advertising control
The Bluetooth LE advertising providers subsystem does not control Bluetooth LE advertising by itself. A separate module that controls Bluetooth advertising is mandatory. For example, CAF: Bluetooth LE advertising module, that is available in the nRF Connect SDK. An application can use this CAF module or implement an application-specific module that controls Bluetooth advertising. The application then uses the Bluetooth LE advertising providers subsystem to manage advertising data and scan response data.
Custom module
An application-specific module can use the following functions to get providers’ advertising data:
bt_le_adv_prov_get_ad_prov_cnt()
to get number of advertising data providers.bt_le_adv_prov_get_ad()
to fill the advertising packet with providers’ data.
Similar functions are defined for scan response data (bt_le_adv_prov_get_sd_prov_cnt()
and bt_le_adv_prov_get_sd()
).
The module must provide bt_le_adv_prov_adv_state
to inform providers about Bluetooth advertising state.
The module must also take into account providers’ feedback received in bt_le_adv_prov_feedback
.
See mentioned structures’ documentation for detailed description of individual members.
Configuration
Set CONFIG_BT_ADV_PROV
to enable the Bluetooth LE advertising providers subsystem.
Predefined providers
The nRF Connect SDK provides a set of predefined providers.
Each provider is enabled using a dedicated Kconfig option.
These options share a common Kconfig option prefix of CONFIG_BT_ADV_PROV_
.
Among others, the following providers are available:
Advertising Flags (
CONFIG_BT_ADV_PROV_FLAGS
),GAP Appearance (
CONFIG_BT_ADV_PROV_GAP_APPEARANCE
),Microsoft Swift Pair (
CONFIG_BT_ADV_PROV_SWIFT_PAIR
),TX Power (
CONFIG_BT_ADV_PROV_TX_POWER
).Bluetooth device name (
CONFIG_BT_ADV_PROV_DEVICE_NAME
).
For details about each advertising provider, see the Kconfig option description.
API documentation
include/bluetooth/adv_prov.h
subsys/bluetooth/adv_prov/
- group bt_le_adv_prov
The subsystem manages advertising packets and scan response packets.
Defines
-
BT_LE_ADV_PROV_AD_PROVIDER_REGISTER(pname, get_data_fn)
Register advertising data provider.
The macro statically registers an advertising data provider. The provider appends data to advertising packet managed by the Bluetooth LE advertising providers subsystem.
- Parameters
pname – Provider name.
get_data_fn – Function used to get provider’s advertising data.
-
BT_LE_ADV_PROV_SD_PROVIDER_REGISTER(pname, get_data_fn)
Register scan response data provider.
The macro statically registers a scan response data provider. The provider appends data to scan response packet managed by the Bluetooth LE advertising providers subsystem.
- Parameters
pname – Provider name.
get_data_fn – Function used to get provider’s scan response data.
Typedefs
-
typedef int (*bt_le_adv_prov_data_get)(struct bt_data *d, const struct bt_le_adv_prov_adv_state *state, struct bt_le_adv_prov_feedback *fb)
Callback used to get provider’s data.
- Param d
[out] Pointer to structure to be filled with data.
- Param state
[in] Pointer to structure describing Bluetooth advertising state.
- Param fb
[out] Pointer to structure describing provider’s feedback.
- Retval 0
If the operation was successful.
- Retval (-ENOENT)
If provider does not provide data.
- Return
Other negative value denotes error specific to provider.
Functions
-
size_t bt_le_adv_prov_get_ad_prov_cnt(void)
Get number of advertising data packet providers.
The number of advertising data packet providers defines maximum number of elements in advertising packet that can be provided by providers. An advertising data provider may not provide data.
- Returns
Number of advertising data packet providers.
-
size_t bt_le_adv_prov_get_sd_prov_cnt(void)
Get number of scan response data packet providers.
The number of scan response data packet providers defines maximum number of elements in scan response packet that can be provided by providers. A scan response data provider may not provide data.
- Returns
Number of scan response data packet providers.
-
int bt_le_adv_prov_get_ad(struct bt_data *ad, size_t *ad_len, const struct bt_le_adv_prov_adv_state *state, struct bt_le_adv_prov_feedback *fb)
Fill advertising data.
Number of elements in array pointed by ad must be at least equal to bt_le_adv_prov_get_ad_prov_cnt.
- Parameters
ad – [out] Pointer to array to be filled with advertising data.
ad_len – [inout] Value describing number of elements in the array pointed by ad. The value is then set by the function to number of filled elements.
state – [in] Structure describing advertising state.
fb – [out] Structure filled with feedback from advertising data providers.
- Returns
0 if the operation was successful. Otherwise, a (negative) error code is returned.
-
int bt_le_adv_prov_get_sd(struct bt_data *sd, size_t *sd_len, const struct bt_le_adv_prov_adv_state *state, struct bt_le_adv_prov_feedback *fb)
Fill scan response data.
Number of elements in array pointed by sd must be at least equal to bt_le_adv_prov_get_sd_prov_cnt.
- Parameters
sd – [out] Pointer to array to be filled with scan response data.
sd_len – [inout] Value describing number of elements in the array pointed by sd. The value is then set by the function to number of filled elements.
state – [in] Structure describing advertising state.
fb – [out] Structure filled with feedback from scan response data providers.
- Returns
0 if the operation was successful. Otherwise, a (negative) error code is returned.
-
struct bt_le_adv_prov_adv_state
- #include <adv_prov.h>
Structure describing Bluetooth advertising state.
Public Members
-
bool pairing_mode
Information if the advertising device is looking for a new peer.
-
bool in_grace_period
Instead of instantly stopping Bluetooth advertising, the advertising may enter grace period (if requested by at least one of the providers). During the grace period advertising is continued for the requested time, but the advertising data is modified. The boolean informs about advertising in grace period.
-
bool pairing_mode
-
struct bt_le_adv_prov_feedback
- #include <adv_prov.h>
Structure describing feedback reported by advertising providers.
Public Members
-
size_t grace_period_s
Instead of instantly stopping Bluetooth advertising, the advertising may enter grace period (if requested by at least one of the providers). During the grace period advertising is continued for the requested time, but the advertising data is modified. The value is used by providers to inform about required minimal time of grace period. The time of grace period advertising is equal to maximum time requested by providers.
-
size_t grace_period_s
-
struct bt_le_adv_prov_provider
- #include <adv_prov.h>
Structure describing advertising data provider.
Public Members
-
bt_le_adv_prov_data_get get_data
Function used to get provider’s data.
-
bt_le_adv_prov_data_get get_data
-
BT_LE_ADV_PROV_AD_PROVIDER_REGISTER(pname, get_data_fn)