Bluetooth LE advertising providers

The Bluetooth LE advertising providers library manages advertising data and scan response data. It does not control Bluetooth LE advertising by itself.

Overview

The Bluetooth LE advertising providers library acts as a middleware between data providers and a module that controls Bluetooth advertising. The module that controls the Bluetooth advertising can use the library’s API to get advertising data and scan response data. On the API call, the Bluetooth LE advertising providers library gets data from providers and passes the data to the module that controls Bluetooth advertising.

Providers

The library 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:

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 that 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 library 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 library to manage advertising data and scan response data.

Custom module

An application-specific module can use the following functions to get providers’ advertising 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 the CONFIG_BT_ADV_PROV Kconfig option to enable the Bluetooth LE advertising providers library.

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:

For details about each advertising provider, see the Kconfig option description.

API documentation

Header file: include/bluetooth/adv_prov.h
Source files: 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 rpa_rotated

Information if RPA (Resolvable Private Address) was rotated since the last advertising data update. Advertising data that contain random values should be re-generated together with RPA rotation to prevent compromising privacy.

bool new_adv_session

Information if new advertising session is about to start. If set to false, the previously started advertising session is continued.

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.

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.

Fast Pair provider API

Header file: include/bluetooth/adv_prov/fast_pair.h
Source files: subsys/bluetooth/adv_prov/providers/fast_pair.c
group bt_le_adv_prov_fast_pair

Fast Pair advertising data provider API.

Functions

void bt_le_adv_prov_fast_pair_enable(bool enable)

Enable/disable Fast Pair advertising provider.

User shall make sure that this function is not called while Fast Pair advertising data provider is providing advertising data.

Parameters:

  • enable – [in] Enable/disable Fast Pair provider.

void bt_le_adv_prov_fast_pair_show_ui_pairing(bool enable)

Show/hide UI indication in Fast Pair not discoverable advertising.

This configuration does not affect Fast Pair discoverable advertising.

User shall make sure that this function is not called while Fast Pair advertising data provider is providing advertising data.

Parameters:

  • enable – [in] Show/hide the UI indication.

int bt_le_adv_prov_fast_pair_set_battery_mode(enum bt_fast_pair_adv_battery_mode mode)

Set advertising battery mode in Fast Pair not dicoverable advertising.

To prevent tracking, the Fast Pair Provider should not include battery data in the advertising packet all the time.

User shall make sure that this function is not called while Fast Pair advertising data provider is providing advertising data.

Parameters:

  • mode – [in] Advertising battery mode.

Returns:

0 if the operation was successful. Otherwise, a (negative) error code is returned.

Swift Pair provider API

Header file: include/bluetooth/adv_prov/swift_pair.h
Source files: subsys/bluetooth/adv_prov/providers/swift_pair.c
group bt_le_adv_prov_swift_pair

Swift Pair advertising data provider API.

Functions

void bt_le_adv_prov_swift_pair_enable(bool enable)

Enable/disable Swift Pair advertising provider.

User shall make sure that this function is not called while Swift Pair advertising data provider is providing advertising data.

Parameters:

  • enable – [in] Enable/disable Swift Pair provider.