Bluetooth: Advertising library

The advertising library handles the Bluetooth LE advertising of your application. It supports a variety of common advertising scenarios. For non-connectable advertising, the library serves as a reference together with the Advertising and Scan Response Data Encoder API.

Overview

The library covers the most common advertising behaviors and can be adjusted by enabling or disabling specific advertising modes.

The library event handler allows for the extension of advertising functionalities, such as adding indicators for active advertising modes.

Advertising modes

The library supports the following connectable advertising modes:

• Directed High Duty - After disconnecting, the application immediately attempts to reconnect to the most recently connected peer. This advertising mode is useful for staying connected to one peer and seamlessly recovering from accidental disconnects. This mode is only allowed for limited duration since it has a high chance of blocking other wireless traffic. Directed High Duty will only work if extended advertising is disabled.

• Directed - Direct advertising to the last connected peer. This mode has a lower duty cycle compared to Directed High Duty.

• Fast - Rapidly advertise to surrounding devices.

• Slow - Advertise to surrounding devices with a longer advertising interval than in Fast advertising mode. This advertising mode conserves power and generates less traffic for other wireless devices that might be present. Finding a device and connecting to it might take more time in Slow advertising mode.

• Idle (Advertising off) - The application stops advertising.

The advertising modes are enabled by using Kconfig options. See the Configuration section below.

When advertising, the library transitions through the enabled advertising modes until a connection is made or advertising times out. The flow of advertising is: Direct High Duty -> Direct -> Fast -> Slow -> Idle.

If you start advertising in Direct mode, the library first attempts Direct advertising. If no information about a previous connection is available or the previous peer is not available, the library starts Fast advertising. If no peer connects before the Fast advertising times out, the application moves on to Slow advertising with a longer advertising interval. If no peer connects before the configured timeout, advertising stops.

Disabled advertising modes are skipped (Directed High Duty is always skipped if extended advertising is enabled).

You can configure the timeout thresholds and advertising intervals for Direct, Fast, and Slow advertising. Direct High Duty is a one-shot burst and its timeout threshold and advertising interval cannot be configured.

Allow list

Allow list advertising affects the filtering parameters for Fast and Slow advertising modes. The allow list stores information about all devices that have been connected before. If you enable the use of the allow list, the application specifically advertises to the devices that are on the allow list.

You can enable or disable allow list advertising by using Kconfig options. After initialization, you can temporarily disable allow list advertising for one connection using the ble_adv_restart_without_allow_list() function. After the device disconnects, the allow list will take effect again.

To permanently disable allow list advertising, you must disable it in Kconfig.

Configuration

The library is enabled and configured using the Kconfig system:

• General settings:

  • CONFIG_BLE_ADV - Enables the advertising library.

  • CONFIG_BLE_ADV_DATA - Enables the advertising and scan response data encoder. You can enable this without CONFIG_BLE_ADV if the full library is not required.

  • CONFIG_BLE_ADV_RESTART_ON_DISCONNECT- Starts advertising upon disconnect.

• Directed advertising settings:

  • CONFIG_BLE_ADV_DIRECTED_ADVERTISING - Enables Directed advertising.

  • CONFIG_BLE_ADV_DIRECTED_ADVERTISING_HIGH_DUTY - Enables Directed High Duty advertising.

  • CONFIG_BLE_ADV_DIRECTED_ADVERTISING_TIMEOUT - Sets the Directed advertising timeout in units of 10 ms.

  • CONFIG_BLE_ADV_DIRECTED_ADVERTISING_INTERVAL - Sets the Directed advertising interval in units of 0.625 ms.

• Fast advertising settings:

  • CONFIG_BLE_ADV_FAST_ADVERTISING - Enables Fast advertising.

  • CONFIG_BLE_ADV_FAST_ADVERTISING_TIMEOUT - Sets the Fast advertising timeout in units of 10 ms.

  • CONFIG_BLE_ADV_FAST_ADVERTISING_INTERVAL - Sets the Fast advertising interval in units of 0.625 ms.

• Slow advertising settings:

  • CONFIG_BLE_ADV_SLOW_ADVERTISING - Enables Slow advertising.

  • CONFIG_BLE_ADV_SLOW_ADVERTISING_TIMEOUT - Sets the Slow advertising timeout in units of 10 ms.

  • CONFIG_BLE_ADV_SLOW_ADVERTISING_INTERVAL - Sets the Slow advertising interval in units of 0.625 ms.

• Allow list and extended advertising:

  • CONFIG_BLE_ADV_USE_ALLOW_LIST - Enables the use of allow list.

  • CONFIG_BLE_ADV_EXTENDED_ADVERTISING - Enables extended advertising.

• PHY-related settings:

  • CONFIG_BLE_ADV_PRIMARY_PHY_AUTO - Sets the primary PHY to auto.

  • CONFIG_BLE_ADV_PRIMARY_PHY_1MBPS - Sets the primary PHY to 1 Mbit/s.

  • CONFIG_BLE_ADV_PRIMARY_PHY_2MBPS - Sets the primary PHY to 2 Mbit/s.

  • CONFIG_BLE_ADV_PRIMARY_PHY_CODED - Sets the primary PHY to coded PHY.

  • CONFIG_BLE_ADV_SECONDARY_PHY_AUTO - Sets the secondary PHY to auto.

  • CONFIG_BLE_ADV_SECONDARY_PHY_1MBPS - Sets the secondary PHY to 1 Mbit/s.

  • CONFIG_BLE_ADV_SECONDARY_PHY_2MBPS - Sets the secondary PHY to 2 Mbit/s.

  • CONFIG_BLE_ADV_SECONDARY_PHY_CODED - Sets the secondary PHY to coded PHY.

Initialization

The library is initialized by calling the ble_adv_init() function. See the ble_adv_config struct for configuration details.

Usage

Before compiling your application, enable the intended advertising modes through the Kconfig system.

Make sure to provide an event handler that is called when advertising transitions to a new mode. You can then use this event handler to add functionality, for example to indicate mode transitions to the user by flashing an LED when advertising starts, or to power down the application when no peer is found.

If enabled, the event handler must handle requests to update the allow list (BLE_ADV_EVT_ALLOW_LIST_REQUEST) and peer address (BLE_ADV_EVT_PEER_ADDR_REQUEST). If the peer address request event is ignored, the Directed advertising mode cannot be used. Likewise, if the allow list request event is ignored, the Fast and Slow advertising modes will not use the allow list.

When replying to the BLE_ADV_EVT_ALLOW_LIST_REQUEST event, the application must provide the allow list in the following way:

• If the application uses Bluetooth: Peer Manager: Retrieve the allow list by calling the pm_allow_list_get() function. Make sure that the pm_allow_list_set() function was previously called. Then, call the ble_adv_allow_list_reply() function with the output of the pm_allow_list_get() function.

• If the application does not use Bluetooth: Peer Manager: call the sd_ble_gap_whitelist_set() function. Then, call the ble_adv_allow_list_reply() function. After initialization, call the ble_adv_start() function to start advertising in the intended mode.

The application must reply to the BLE_ADV_EVT_PEER_ADDR_REQUEST event by calling the ble_adv_peer_addr_reply() function.

Note

When setting connection-specific configurations using the sd_ble_cfg_set() function, you must create a tag for each configuration. This tag must be provided when calling the sd_ble_gap_adv_start() function and the sd_ble_gap_connect() function.

Dependencies

This library has the following Bare Metal dependencies:

• SoftDevice (peripheral role) - CONFIG_SOFTDEVICE_PERIPHERAL

• SoftDevice handler (Bluetooth LE) - CONFIG_NRF_SDH_BLE

• Bluetooth LE Advertising data (selected automatically) - CONFIG_BLE_ADV_DATA

API documentation

Header file: include/bm/bluetooth/ble_adv.h

Source files: lib/bluetooth/ble_adv/

Bluetooth LE Advertising library API reference

Header file: include/bm/bluetooth/ble_adv_data.h

Source files: lib/bluetooth/ble_adv/

Advertising and Scan Response Data Encoder API reference