CAF: Bluetooth LE advertising module

When enabled for an application, the Bluetooth® LE advertising module is responsible for controlling the Bluetooth LE advertising for Bluetooth LE Peripheral device.

This module can only work together with the CAF Bluetooth LE state module. The Bluetooth LE state module is a core Bluetooth module in the Common Application Framework (CAF).

Configuration

The following Kconfig options are available for this module:

• CONFIG_CAF_BLE_ADV

• CONFIG_CAF_BLE_ADV_PM_EVENTS

• CONFIG_CAF_BLE_ADV_POWER_DOWN_ON_DISCONNECTION_REASON_0X15

• CONFIG_CAF_BLE_ADV_DIRECT_ADV

• CONFIG_CAF_BLE_ADV_FAST_ADV

• CONFIG_CAF_BLE_ADV_FAST_ADV_TIMEOUT

• CONFIG_CAF_BLE_ADV_FILTER_ACCEPT_LIST

• CONFIG_CAF_BLE_ADV_GRACE_PERIOD

• CONFIG_CAF_BLE_ADV_ROTATE_RPA

Read about some of these options in the following sections.

Enabling the module

To enable the Bluetooth LE advertising module, complete the following steps:

1. Enable and configure the CAF Bluetooth LE state module.

2. Set the CONFIG_CAF_BLE_ADV Kconfig option.

3. Configure the advertising data and scan response data for undirected advertising. Both advertising data and scan response data are managed by Bluetooth LE advertising providers. See Bluetooth LE advertising providers for details. Also see Bluetooth LE advertising module for an example of the Bluetooth LE advertising providers configuration defined by an application.

Using directed advertising

By default, the module uses indirect advertising. Set the CONFIG_CAF_BLE_ADV_DIRECT_ADV option to use directed advertising. The directed advertising can be used to call the selected peer device to connect as quickly as possible.

Note

The module will not advertise directly towards a Central that uses Resolvable Private Address (RPA). The Bluetooth LE Peripheral does not read the Central Address Resolution GATT characteristic of the Bluetooth LE Central, so the Peripheral does not know if the remote device supports the address resolution of directed advertisements.

Changing advertising interval

Set the CONFIG_CAF_BLE_ADV_FAST_ADV Kconfig option to make the Peripheral initially advertise with a shorter interval. This lets you speed up finding the Peripheral by Bluetooth Centrals.

• If the device uses indirect advertising, it will switch to slower advertising after the period of time defined in CONFIG_CAF_BLE_ADV_FAST_ADV_TIMEOUT (in seconds).

• If the device uses directed advertising, the Bluetooth LE advertising module will receive ble_peer_event with ble_peer_event.state set to PEER_STATE_CONN_FAILED if the Central does not connect during the predefined period of fast directed advertising. The ble_peer_event is submitted by CAF: Bluetooth LE state module. After the event is received, the device will switch to the low duty cycle directed advertising.

Switching to slower advertising is done to reduce the energy consumption.

Synchronizing RPA and advertising data updates

With the CONFIG_BT_PRIVACY Kconfig option enabled, set the CONFIG_CAF_BLE_ADV_ROTATE_RPA option to synchronize Resolvable Private Address (RPA) rotation with the undirected advertising data update. You can control the rotation period with the CONFIG_CAF_BLE_ADV_ROTATE_RPA_TIMEOUT option and change the randomization factor of the rotation period with the CONFIG_CAF_BLE_ADV_ROTATE_RPA_TIMEOUT_RAND option.

Power-down

When the system goes to the power-down state, the advertising either instantly stops or enters the grace period state.

Grace period

The grace period is an advertising state, during which the advertising is still active, but the advertising data and scan response data can be modified to inform that system is about to go to the power-down state.

If any advertising data provider requests non-zero grace period time, the stopping of advertising on power-down is delayed by the requested time. Instead of instantly stopping, the advertising enters the grace period. After the grace period ends, the advertising stops.

The grace period is requested for example by the Swift Pair advertising data provider (CONFIG_BT_ADV_PROV_SWIFT_PAIR). During the grace period, Swift Pair data is removed from the advertising packet and the device enters Swift Pair’s cool-down phase. This is done to ensure that the user does not try to connect to the device that is no longer available.

Note

Make sure that CONFIG_CAF_BLE_ADV_GRACE_PERIOD Kconfig option is enabled if both following conditions are met:

• Any of the providers requests the grace period.

• CONFIG_CAF_BLE_ADV_PM_EVENTS is enabled.

The CONFIG_CAF_BLE_ADV_GRACE_PERIOD is enabled by default if the Swift Pair advertising data provider is enabled in the configuration.

Force power down on bonded peer power off

You can use the CONFIG_CAF_BLE_ADV_POWER_DOWN_ON_DISCONNECTION_REASON_0X15 Kconfig option to force power down when a bonded peer disconnects with reason 0x15 (Remote Device Terminated due to Power Off). On a Bluetooth LE peer event (ble_peer_event) reporting PEER_STATE_DISCONNECTED (ble_peer_event.state) with reason 0x15 (ble_peer_event.reason), the module performs the following:

• Instantly stops Bluetooth LE advertising (the module enters power down state).

• Submits a force power down event (force_power_down_event).

You can use this feature to prevent a bonded peer from waking up until activity on the peripheral is detected.

Implementation details

The Bluetooth LE advertising module is used only by Bluetooth Peripheral devices.

The Bluetooth LE advertising module uses Zephyr’s Settings to store the information if the peer for the given local identity uses the Resolvable Private Address (RPA).

Undirected advertising data update

The module does not instantly update advertising and scan response payloads when either advertising data or scan response data (provided by Bluetooth LE advertising providers) is modified. The module automatically gets new advertising data and scan response data from Bluetooth LE’s advertising data provider subsystem only in the following cases:

• Bluetooth LE undirected advertising is started or restarted.

• Undirected advertising enters the Grace period.

• RPA is rotated with the CONFIG_CAF_BLE_ADV_ROTATE_RPA option enabled.

The payload update can be triggered by the application using ble_adv_data_update_event. Make sure to submit the event after changing the Bluetooth data provided by a provider.

Reaction on Bluetooth peer operation

If the application supports Bluetooth LE bond management (CONFIG_CAF_BLE_BOND_SUPPORTED), the Bluetooth LE bond module defined for the application is used to control the Bluetooth bonds. The Bluetooth LE bond module broadcasts information related to bond control using ble_peer_operation_event.

The Bluetooth LE advertising module reacts on ble_peer_operation_event related to the Bluetooth peer change or erase advertising. The module performs one of the following operations:

• If there is a peer connected over Bluetooth, the Bluetooth LE advertising module triggers disconnection and submits a ble_peer_event with ble_peer_event.state set to PEER_STATE_DISCONNECTING to let other application modules prepare for the planned disconnection.

• Otherwise, the Bluetooth advertising with the newly selected Bluetooth local identity is started.

Avoiding connection requests from unbonded centrals when bonded

If CONFIG_CAF_BLE_ADV_FILTER_ACCEPT_LIST is enabled and the Bluetooth local identity currently in use already has a bond, the device will filter incoming scan response data requests and connection requests. In that case, only the bonded peer can connect or request scan response data. This is done to prevent Bluetooth Centrals other than the bonded one from connecting with the device.

Grace period with synchronized updates of RPA and advertising data

With both the CONFIG_CAF_BLE_ADV_GRACE_PERIOD and the CONFIG_CAF_BLE_ADV_ROTATE_RPA options enabled, if the RPA rotation occurs in the grace period, it terminates the grace period prematurely. This limitation is caused by the Bluetooth API, which doesn’t allow to delay the RPA rotation.