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:

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

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