Fast Pair Advertising Manager

The Fast Pair Advertising Manager is a helper module for the Google Fast Pair Service (GFPS) that provides management of the Fast Pair advertising set. The module implements a trigger-based system for controlling Fast Pair advertising state that allows client modules to request advertising with their preferred configuration. It also defines the use case layer that provides an implementation of specific advertising requirements for supported use cases.

Overview 

The Fast Pair Advertising Manager module provides the following key features:

Trigger-based advertising control - Allows multiple components to request the start of advertising using registered triggers.
Trigger-based advertising configuration - Provides flexible configuration of the advertising parameters, such as pairing mode and RPA rotation behavior based on trigger requirements.
Payload synchronization - Ensures advertising payload updates are synchronized with RPA rotations.
Extension compatibility - Is compatible with the Fast Pair extensions that are supported by the Google Fast Pair Service (GFPS) module (for example, the Find Hub Network extension).
Use case support - Provides tailored behavior for specific Fast Pair device types (for example, locator tags).

Note

The module is designed to work in a cooperative thread context.

Configuration 

To enable the Fast Pair Advertising Manager, use the CONFIG_BT_FAST_PAIR_ADV_MANAGER Kconfig option. As this is a helper module, the Kconfig option is only configurable if the CONFIG_BT_FAST_PAIR Kconfig option is enabled (see the Google Fast Pair Service (GFPS) documentation for more details).

With the CONFIG_BT_FAST_PAIR_ADV_MANAGER Kconfig option enabled, you can use the following Kconfig options with this module:

BT_FAST_PAIR_ADV_MANAGER_USE_CASE - This Kconfig option allows to select the Fast Pair use case (device type) and to enable additional advertising behaviors that are specific to your use case.
- CONFIG_BT_FAST_PAIR_ADV_MANAGER_USE_CASE_UNSPECIFIED - The option provides a neutral configuration without behaviors specific to any use case. By default, the CONFIG_BT_FAST_PAIR_ADV_MANAGER_USE_CASE_UNSPECIFIED option is selected.
- CONFIG_BT_FAST_PAIR_ADV_MANAGER_USE_CASE_LOCATOR_TAG - The option provides a tailored configuration for Fast Pair locator tags that use the FHN extension. It depends on the CONFIG_BT_FAST_PAIR_FHN Kconfig option.
  - CONFIG_BT_FAST_PAIR_ADV_MANAGER_USE_CASE_LOCATOR_TAG_CLOCK_SYNC_TRIGGER - The option enables the clock synchronization trigger for locator tag devices. The option is enabled by default.

Dependencies 

The CONFIG_BT_FAST_PAIR_ADV_MANAGER Kconfig option depends on the following Bluetooth LE features:

CONFIG_BT_PERIPHERAL - Peripheral role support
CONFIG_BT_EXT_ADV - Extended advertising support
CONFIG_BT_PRIVACY - Bluetooth privacy support
CONFIG_BT_RPA_TIMEOUT_DYNAMIC - Support for dynamic configuration of the RPA timeout with the bt_le_set_rpa_timeout() function
CONFIG_BT_SMP - Security Manager Protocol support
CONFIG_BT_ADV_PROV - Advertising data provider support
CONFIG_BT_ADV_PROV_FAST_PAIR - Fast Pair advertising data provider support

Implementation details 

This module uses Zephyr Bluetooth subsystem APIs to manage the Fast Pair advertising set and the connections that are derived from it.

Module lifecycle 

The module follows a specific lifecycle:

Initialization - The module is initialized during system startup by the SYS_INIT macro.
Configuration - The majority of the configuration (such as information callbacks or Bluetooth identity) is performed before enabling the module.
Enabling - The module is enabled with the bt_fast_pair_adv_manager_enable() function, which requires that the Fast Pair subsystem is ready (bt_fast_pair_enable()).
Operation - Triggers can request advertising activation or deactivation.
Disabling - The module is disabled with the bt_fast_pair_adv_manager_disable() function before the Fast Pair subsystem is disabled.

Advertising triggers 

The module uses a trigger-based system where different components can request advertising activation.

All advertising triggers are registered in the module section with the BT_FAST_PAIR_ADV_MANAGER_TRIGGER_REGISTER macro that uses the STRUCT_SECTION_ITERABLE macro to place the bt_fast_pair_adv_manager_trigger descriptor in the module section. See the Iterable Sections section for more details. The number of registered triggers is limited to 32.

Each trigger can have a dedicated configuration that is described by the bt_fast_pair_adv_manager_trigger_config structure. The trigger configuration is a constant field of the bt_fast_pair_adv_manager_trigger structure and cannot be changed at runtime.

Advertising process 

The module uses the Bluetooth Extended Advertising API (include/zephyr/bluetooth/bluetooth.h) to manage the Fast Pair advertising set.

Note

Even though the Bluetooth Extended Advertising API is used to manage the Fast Pair advertising set, the module still broadcasts advertising frames in the legacy format over-the-air.

Advertising set initialization

The Fast Pair advertising set is allocated with the bt_le_ext_adv_create() function in the bt_fast_pair_adv_manager_enable() context. During the advertising set creation, the module registers the following callbacks:

bt_le_ext_adv_cb.connected - The callback is used to track the connection state.
bt_le_ext_adv_cb.rpa_expired - The callback is used to manage the RPA rotations.

Additionally, during the advertising set creation, the advertising parameters are set as follows:

Advertising interval 100 ms

Note

Currently, the advertising interval is fixed and cannot be changed with a Kconfig option or API functions.
Bluetooth identity according to the module configuration (bt_fast_pair_adv_manager_id_set()).

Since this module is typically responsible for setting the RPA timeout that affects all advertising sets, it triggers the initial RPA rotation with the bt_le_oob_get_local() function to configure the timeout according to the Fast Pair advertising requirements. This operation takes place right after the advertising set creation and before the advertising process is started.

The module starts advertising in the bt_fast_pair_adv_manager_enable() context if the appropriate conditions are met.

RPA rotations

The module is typically responsible for setting the RPA timeout. The module sets the RPA timeout with the bt_le_set_rpa_timeout() function in the context of the bt_le_ext_adv_cb.rpa_expired callback that is registered during the advertising set creation.

Note

If the FHN extension is used, the FHN advertising configures the RPA timeout in the FHN provisioned state. This module is tightly integrated with the FHN extension and respects this requirement.

The timeout value is recalculated for every RPA rotation and randomized to increase privacy. The typical timeout ranges between 11 and 15 minutes. The sys_csrand_get() function from the Random Number Generation subsystem is used to generate random value for the timeout.

The RPA rotation is suspended if any active advertising trigger has the bt_fast_pair_adv_manager_trigger_config.suspend_rpa flag set to true. This is achieved by returning false from the bt_le_ext_adv_cb.rpa_expired callback.

Advertising payload

The module uses the Bluetooth LE advertising providers library (CONFIG_BT_ADV_PROV) to construct the advertising payload.

During the payload update procedure, the module populates the bt_le_adv_prov_adv_state structure to indicate the current advertising state. Information about the pairing mode, RPA rotation, and other parameters is passed to the Bluetooth LE advertising providers library with the help of this structure and the API functions that are mentioned in subsequent sentences. Then, it calls the bt_le_adv_prov_get_ad() function to encode the advertising payload in the array of bt_data elements. The array size is properly allocated with the bt_le_adv_prov_get_ad_prov_cnt() function before the encode operation. Similarly, the bt_le_adv_prov_get_sd() function is used to encode the scanning data. As the final step, the collected payload is set in the Fast Pair advertising set with the bt_le_ext_adv_set_data() function.

The advertising payload is updated in the following cases:

Advertising process is started.
The bt_fast_pair_adv_manager_payload_refresh() function is called and the advertising is ongoing.
The bt_le_ext_adv_cb.rpa_expired callback is triggered due to the RPA rotation and the advertising is ongoing.
The pairing mode state of the module changes as a result of the bt_fast_pair_adv_manager_request() function call and the advertising is ongoing.

Advertising conditions

The advertising is started with the bt_le_ext_adv_start() function and the process is maintained if the following conditions are met:

The module is enabled (bt_fast_pair_adv_manager_enable()).
At least one advertising trigger gets activated with the bt_fast_pair_adv_manager_request() function.
The module does not maintain any connection.

Note

The module currently supports only one connection at a time. A connection stops the Fast Pair advertising even if the advertising triggers are active. The advertising is restarted when the connection is terminated.

Otherwise, the advertising is inactive.

The module tracks the advertising activity and can report each change with the bt_fast_pair_adv_manager_info_cb.adv_state_changed callback to the application.

Trigger state changes

The trigger configuration (bt_fast_pair_adv_manager_trigger_config) may update the module’s advertising state once the given trigger is activated with the bt_fast_pair_adv_manager_request() function. The advertising state is also updated when the previously activated trigger gets deactivated as its configuration is no longer applied.

Advertising set deinitialization

During the disable operation, in the bt_fast_pair_adv_manager_disable() function context, the module stops the ongoing Bluetooth activities:

Advertising process with the bt_le_ext_adv_stop() function.
Active connections with the bt_conn_disconnect() function. This disconnect operation is only limited to the connections that are derived from the Fast Pair advertising set.

The advertising set is also deleted with the bt_le_ext_adv_delete() function.

Coexistence with other advertising sets 

The Fast Pair advertising set, that is managed by this module, can operate in parallel with other advertising sets without interfering with them.

The module only manages the advertising process for the Fast Pair advertising set and the connections that are derived from it. It uses one connection slot from the connection pool of the Bluetooth stack (CONFIG_BT_MAX_CONN).

Other advertising sets that also use RPA as its MAC address are affected by the RPA timeout setting of the Fast Pair advertising set. The RPA timeout is set globally with the bt_le_set_rpa_timeout() function in the Bluetooth stack and affects all advertising sets.

FHN integration 

The module is compatible with the Find Hub Network (FHN) extension and handles the complex advertising state transitions automatically. The advertising policy of the Fast Pair advertising set respects the requirements of the FHN advertising set. The module rotates the RPA and the payload of the Fast Pair advertising set synchronously with the FHN advertising set.

The module yields control over the RPA timeout configuration to the FHN advertising set once the FHN provisioning is completed. Conversely, right after the unprovisioning, the module takes back control over the RPA timeout configuration. To achieve this, the module uses the bt_le_oob_get_local() function to trigger the premature RPA rotation and set the RPA according to the Fast Pair advertising requirements.

Use case extensions 

The module supports use case layer that provides an implementation of specific advertising requirements for supported use cases. Currently, the use case extension is only available for the locator tags.

By default, the CONFIG_BT_FAST_PAIR_ADV_MANAGER_USE_CASE_UNSPECIFIED Kconfig option is enabled, which means that this layer is disabled.

If you change this default configuration and select a specific use case, the core library uses the enable callback to activate the use case extension in the bt_fast_pair_adv_manager_enable() function.

Similarly, the disable callback is used in the context of the bt_fast_pair_adv_manager_disable() function to deactivate the use case extension.

For this process to work, the use case layer must register the mandatory callback structure with the enable and disable callbacks.

Locator tag

The locator tag extension registers the bt_fast_pair_info_cb and the bt_fast_pair_fhn_info_cb callback structures to manage the advertising triggers that are specific to the locator tag use case.

This extension defines the FHN provisioning trigger that is used to maintain the Fast Pair advertising between the Owner Account Key write (bt_fast_pair_info_cb.account_key_written) and the successful FHN provisioning (bt_fast_pair_fhn_info_cb.provisioning_state_changed). This advertising trigger is also configured to suspend the RPA rotation during the FHN provisioning. If the FHN provisioning is not completed within the allowed time, the extension deactivates the FHN provisioning with the bt_fast_pair_adv_manager_request() function. The trigger behavior is aligned with the requirements of the Fast Pair Locator Tag Specific Guidelines section of the FHN Accessory specification.

Note

If the FHN provisioning trigger is deactivated prematurely with the bt_fast_pair_adv_manager_disable() function, it will not be restored during the bt_fast_pair_adv_manager_enable() function call. The device should typically advertise continuously for the predefined period until it is factory reset or successfully provisioned.

The extension also defines the FHN clock synchronization trigger that is used to maintain the Fast Pair advertising after a power loss until the clock synchronization (bt_fast_pair_fhn_info_cb.clock_synced) is completed. This trigger is enabled by default and can be controlled with the CONFIG_BT_FAST_PAIR_ADV_MANAGER_USE_CASE_LOCATOR_TAG_CLOCK_SYNC_TRIGGER Kconfig option. This advertising trigger does not use a dedicated configuration structure and passes NULL as the configuration pointer.

API documentation 

Header file: include/bluetooth/fast_pair/adv_manager.h

Source files: subsys/bluetooth/fast_pair/adv_manager

Fast Pair Advertising Manager API