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:

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:

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:

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.

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.