Integration overview

The nRF Connect SDK integrates the Fast Pair Provider role, facilitating communication between the Fast Pair Seeker (typically a smartphone) and the Provider (your device).

Integration prerequisites

Before you start the nRF Connect SDK integration with Fast Pair, make sure that the following prerequisites are fulfilled:

  • Install the nRF Connect SDK.

  • Set up a supported Development Kit (DK). See Application development for more information on setting up the DK you are using.

  • Install the requirements mentioned in the Fast Pair provision script. The script is automatically invoked by the build system during application build to generate Fast Pair provisioning data hex file.

  • During the early stages of development, you can use the debug Model ID and Anti-Spoofing Public/Private Key pair obtained by Nordic Semiconductor for local tests. Later on, you need to register your own Fast Pair Provider device with Google. The Registering Fast Pair Provider section in this document explains how to register the device and obtain the Model ID and Anti-Spoofing Public/Private Key pair.

Solution architecture

The integration involves following the instructions outlined in the Integration steps section. The SDK supports extensions such as Battery Notification and Personalized Name, which can be included based on the specific use case requirements.

Google Fast Pair extensions

The Fast Pair standard implementation in the nRF Connect SDK supports the following extensions:

  • Battery Notification extension

  • Personalized Name extension

  • Find Hub Network (FHN) extension

Each supported extension is described in the following sections.

Tip

Extension-specific instructions are located under the extension section in each integration step of this guide. You can safely skip sections for extensions that you do not want to support in your application.

Battery Notification extension

The extension provides a mechanism to broadcast battery level information that is encoded in the Fast Pair not discoverable advertising payload. You can set up the battery information for up to three different components (required for the earbuds use case: left bud, right bud and case).

For more details on this extension, see the Fast Pair Battery Notification extension documentation.

Personalized Name extension

The extension allows the user to attach a personalized name to their Fast Pair accessories.

For more details on this extension, see the Fast Pair Personalized Name extension documentation.

FHN extension

The FHN extension leverages the Find Hub Network, which is a crowdsourced network consisting of millions of Android devices that use Bluetooth® LE to detect missing devices and report their approximate locations back to their owners. The entire process is end-to-end encrypted and anonymous, so no one else (including Google) can view device’s location or information. The Find Hub Network also includes features protecting the user against unwanted tracking.

Note

The Find Hub Network (FHN) extension was previously known as the Find My Device Network (FMDN) extension. You might still encounter occasional use of the old extension name in the Google documentation and resources.

You can add your accessory to the Find Hub Network through provisioning that happens during the Bluetooth LE connection. Once provisioned, the accessory starts to advertise FHN frames that contain its unique identifier. This advertising payload is used by nearby Android devices to report the accessory location to its owner. The accessory location is an approximation of the reporting device’s location, meaning it is not precise. The FHN frames are independently broadcasted alongside the standard application payload. You can remove your accessory from the Find Hub Network in a symmetrical operation, called unprovisioning. Once unprovisioned, the accessory stops advertising FHN frames.

The support for the FHN extension is available on Android platforms.

Google Play Services and Android system level support are responsible for the provisioning of the FHN extension. They also perform background tasks, such as periodic clock synchronization of the provisioned devices.

Find Hub app is an end-user application for managing the tracking accessories. It allows you to:

  • Locate your accessories using the map view.

  • Play sound on the nearby tagged item to make it easier to find.

  • Check the battery level of your accessory.

  • Remove (unprovision) your item.

For more details on this extension, see the Fast Pair Find Hub Network extension documentation. This documentation also contains the FHN Accessory specification, which is frequently used as a reference in the FHN sections of this guide.

Detecting Unwanted Location Trackers

The FHN Accessory specification integrates the Detecting Unwanted Location Trackers (DULT) specification, which is a joint standardization effort from Apple, Google and other companies to prevent unwanted tracking. Relevant FHN sections of this guide describe the DULT integration with the FHN extension. For more details on the DULT integration guidelines, see the Fast Pair Unwanted Tracking Prevention Guidelines documentation.

Precision Finding

The Precision Finding (PF) feature extends the FHN extension with ranging capabilities that enable the Seeker to perform a precise distance measurement with the Provider device. It uses ranging technologies such as Bluetooth LE Channel Sounding (CS) to provide accurate proximity information, improving the user experience when locating a missing device. The feature supports the following ranging technologies:

  • Ultra Wideband (UWB)

  • Bluetooth Low Energy Channel Sounding

  • Wi-Fi® Neighbor Awareness Networking (NAN) Round-Trip Time (RTT)

  • Bluetooth Low Energy Received Signal Strength Indicator

For more details on this feature, see the Fast Pair FHN Precision Finding documentation that is part of the FHN Accessory specification.

Note

The Precision Finding feature is marked as experimental.

As of the beginning of the second quarter of 2026, Precision Finding support using Bluetooth Low Energy Channel Sounding as the ranging technology is not publicly available on Android platforms. However, you can experiment with this configuration on Android test devices that provide hardware and software support for Bluetooth Low Energy Channel Sounding (for example, Google Pixel 10), provided that the following requirements are met:

  • The target Android device must run Android QPR3 Beta 2 (January 2026) or a later release.

  • Google Play Services must not be enrolled in its independent beta program.

  • The primary email account on the Android test device must be registered on Google’s allowlist for this feature. To add a test email address to the allowlist, contact the Google team to request approval.

The Precision Finding feature is optional. For more details on the Precision Finding integration, see the Precision Finding and Using the Precision Finding callbacks sections.

Integration steps

The Fast Pair standard integration in the nRF Connect SDK consists of the following steps:

  1. Provisioning the device

  2. Performing prerequisite operations

  3. Setting up Bluetooth LE advertising

  4. Interacting with GATT service

  5. Managing factory resets

  6. Tailoring protocol for specific use case

These steps are described in the following sections.

The Fast Pair standard implementation in the nRF Connect SDK integrates Fast Pair Provider, one of the available Fast Pair roles. For an integration example, see the Bluetooth Fast Pair: Input device sample.

Provisioning the device

A device model must be registered with Google to work as a Fast Pair Provider. The data is used for procedures defined by the Fast Pair standard.

Registering Fast Pair Provider

See the official Fast Pair Model Registration documentation for information on how to register the device and obtain the Model ID and Anti-Spoofing Public/Private Key pair. Alternatively, you can use the debug Model ID and Anti-Spoofing Public/Private Key pair obtained by Nordic Semiconductor for the development purposes. See the following samples and applications for details about the debug Fast Pair Providers registered by Nordic:

Device type

When registering the device in the Google Nearby Devices console, go to the Fast Pair protocol configuration panel, and in the Device Type list select an option that matches your application’s use case. The chosen device type also determines the optional feature set that you can support in your use case. You declare support for each feature by selecting the true option.

Note

Ensure you make an informed decision when selecting the device type, as it has a significant impact on the Fast Pair Seeker behavior in relation to your Provider’s device.

The Fast Pair standard implementation in the nRF Connect SDK actively supports the following device types and use cases:

Firmware update intent

Intents are an established mechanism for app-to-app communication on the Android platform. In this particular case, the firmware update intent is used by Fast Pair to notify the companion app about the need to update the Provider’s firmware. A companion app is an Android application that is typically developed for a device model. It often unlocks additional interactions with a device, which are not supported at the Android system level. Companion apps are typically used to configure device parameters or update their firmware. For further details on the Android intent feature for firmware updates, see the Fast Pair firmware update intent section in the Fast Pair specification.

To configure your device model in the Google Nearby Devices console for support of the firmware update intent feature, complete the following steps:

  1. Select the appropriate option in the Firmware Type list. The default Unspecified selection disables the intent feature for firmware updates.

  2. Enter the firmware version string in the Firmware Version field.

  3. Enter the companion app package name in the Companion App Package Name field.

See Firmware update intent to learn how to prepare your Provider firmware to support the firmware update intent feature.

FHN extension

To support the FHN extension, set the Find My Device feature to true for the device that you want to register in the Google Nearby Devices console.

For an example that uses the Find My Device feature, see the Bluetooth Fast Pair: Locator tag sample.

Note

To test the FHN extension with the debug (uncertified) device models, you must set up your Android test device. Make sure your phone uses the primary email account that is registered on Google’s email allow list for the FHN feature. To register your development email account, complete Google’s device proposal form. You can find the link to the device proposal form in the Fast Pair Find Hub Network extension specification.

Provisioning registration data onto device

The Fast Pair standard requires provisioning the device with Model ID and Anti-Spoofing Private Key obtained during device model registration. In the nRF Connect SDK, the provisioning data is generated as a hexadecimal file using the Fast Pair provision script.

When building Fast Pair in the nRF Connect SDK, you can configure the build system to automatically handle the Fast Pair provisioning process during the build. If this feature is enabled, the build system calls the Fast Pair provision script. It then includes the resulting hexadecimal file in the final firmware that you can flash onto the device.

For further details on how to configure the automatic Fast Pair provisioning in your project configuration, see the following subsections.

Partition definition

The Fast Pair provisioning data is stored on the dedicated Fast Pair partition. To properly define this partition, you must rely on the partitioning tool that is supported by your target device. The specific description for each partitioning tool is provided in the following subsections.

Devicetree (DTS)

The recommended approach for defining the Fast Pair partition is to declare the bt_fast_pair_partition partition manually in the devicetree overlay file. See the board overlay examples in the Bluetooth Fast Pair: Input device and Bluetooth Fast Pair: Locator tag samples.

Note

The Fast Pair partition can be provisioned by the build system only if it is defined in the DTS configuration of the main (default) application image.

Partition Manager (PM) (deprecated)

Note

The Partition Manager script is a component in the nRF Connect SDK and is responsible for handling the memory partitioning at build time.

This functionality is in the process of being deprecated and replaced by Zephyr’s default devicetree-based memory partitioning. It is recommended that all new designs using Nordic devices, excluding the nRF91 Series devices, are built with DTS instead of Partition Manager. Partition Manager will be removed from the nRF Connect SDK by the end of 2026 from the main branch.

For more information on how to configure partitions using DTS and how to migrate your existing configuration to DTS, see the Release notes page.

The only exception from these migration guidelines in the context of the Fast Pair sample support is the nRF53 Series DFU configuration with MCUboot in the overwrite mode (for example, the nrf5340dk/nrf5340/cpuapp board target in the Bluetooth Fast Pair: Locator tag sample). This particular configuration is not yet deprecated, as the DTS alternative is not yet available.

For devices that support Partition Manager, the system also automatically creates the bt_fast_pair partition. The partition is defined in the subsys/partition_manager/pm.yml.bt_fast_pair file.

Note

The dynamic generation of the bt_fast_pair partition definition is only supported if you enable the CONFIG_BT_FAST_PAIR Kconfig option in your application image.

Alternatively, you can define the Fast Pair partition manually in the application’s static Partition Manager configuration file. See the nRF53 board examples in the samples/bluetooth/fast_pair/locator_tag/configuration/ directory, which is a part of the Bluetooth Fast Pair: Locator tag sample. For more information about defining Partition Manager partitions, see the Configuration section of the Partition Manager page.

Note

The Fast Pair partition can be provisioned by the build system only if it is defined in the main (default) application domain. For example, defining partition in the CPUNET domain for nRF53 targets is not supported.

Sysbuild Kconfig configuration and provisioning data generation

To generate a hexadecimal file with the Fast Pair provisioning data during the build, you must use the default nRF Connect SDK build system configuration with sysbuild and set the following sysbuild Kconfig options:

See Sysbuild (System build) for detailed information on how to configure the sysbuild Kconfig options.

Note

The Anti-Spoofing Private Key is confidential and must be handled securely. It is recommended to store this key securely outside the code repository and either pass it to the project as an additional build parameter (with the -DSB_CONFIG_BT_FAST_PAIR_ANTI_SPOOFING_PRIVATE_KEY parameter) or use a separate setup to provision devices.

If the provisioning data generation is triggered successfully, the SB_CONFIG_BT_FAST_PAIR_PROV_DATA Kconfig option is set in the project sysbuild configuration.

The build system automatically places the Fast Pair provisioning data onto the partition defined by the supported partitioning tool (DTS or the deprecated Partition Manager).

The provisioning hex file is automatically merged with the final hexadecimal output from the build command (merged.hex) and is uploaded on your target device with the west flash command.

See the following sections for information on how to add the Google Fast Pair subsystem to your project.

Performing prerequisite operations

To start integrating the Google Fast Pair subsystem in your project, complete the following prerequisite steps:

The subsequent subsections describe required steps for enabling Fast Pair extensions supported in the nRF Connect SDK.

Enabling Fast Pair in Kconfig

To support Google Fast Pair in your project, you must enable the CONFIG_BT_FAST_PAIR Kconfig option at the main application image level.

Note

The Fast Pair Kconfig configuration at the sysbuild level is only used to generate the Fast Pair provisioning data hex file during the build. See the Provisioning registration data onto device section for more details regarding sysbuild configuration for Fast Pair.

Enabling Fast Pair with API

An application can communicate with the Fast Pair subsystem using API calls and registered callbacks. The Fast Pair subsystem uses the registered callbacks to inform the application about the Fast Pair related events.

The application must register the callbacks before it enables the Fast Pair subsystem and starts to operate as the Fast Pair Provider and advertise Bluetooth LE packets. To identify the callback registration functions in the Fast Pair API, look for the _register suffix. Set your application-specific callback functions in the callback structure that is the input parameter for the ..._register API function. The callback structure must persist in the application memory (static declaration), as during the registration, the Fast Pair module stores only the memory pointer to it.

The standard Fast Pair API (without extensions) currently supports the bt_fast_pair_info_cb_register() function (optional) for registering application callbacks.

The standard Fast Pair (without extensions) does not require registration of any callback type, meaning all callbacks are optional.

After the callback registration, the Fast Pair subsystem must be enabled with the bt_fast_pair_enable() function. Before performing the bt_fast_pair_enable() operation, you must enable Bluetooth with the bt_enable() function and load Zephyr’s Settings with the settings_load() function. The Fast Pair subsystem readiness can be checked with the bt_fast_pair_is_ready() function. The Fast Pair subsystem can be disabled with the bt_fast_pair_disable() function. In the Fast Pair subsystem disabled state, most of the Fast Pair APIs are not available.

Apart from the callback registration and enabling the Fast Pair subsystem, no additional operations are needed to integrate the standard Fast Pair implementation.

Personalized Name extension

To support the Personalized Name extension, enable the CONFIG_BT_FAST_PAIR_PN Kconfig option in your project.

FHN extension

To support the FHN extension, enable the CONFIG_BT_FAST_PAIR_FHN Kconfig option in your project.

Managing the activation state

The FHN extension is enabled together with the general Fast Pair module once the bt_fast_pair_enable() function executes successfully. The Provider can respond to the extension-specific requests coming from the Seeker over the Bluetooth GATT layer only in the enabled state. Depending on its state, the extension starts other activities, such as:

  • Beacon clock service that is used to measure time in seconds.

  • FHN advertising with periodical updates to the FHN payload (the FHN advertising is in use only if provisioned).

The FHN extension is disabled together with the general Fast Pair module once the bt_fast_pair_disable() function executes successfully. During the disable operation, the Provider terminates all extension-related activities that are mentioned in the enable operation description. Additionally, it drops all FHN connections that were established using the FHN advertising payload.

Note

A failure in the enable or disable operation can have certain side effects related to the module state. An error during the bt_fast_pair_enable() or the bt_fast_pair_disable() function call results in the unready state of the extension. In that case, you should retry the operation or reboot the system, as certain module operations may be active.

To check the FHN extension readiness, use the bt_fast_pair_is_ready() function of the general Fast Pair module. The extension is marked as ready when it is in the enabled state and unready when it is in the disabled state. The unready state is also reported by the bt_fast_pair_is_ready() function if the bt_fast_pair_enable() or bt_fast_pair_disable() operations fail.

You can use the following API functions only in the unready state of the FHN extension:

Beacon clock service

Once you have successfully activated the Fast Pair module using the bt_fast_pair_enable() function, the FHN extension starts the beacon clock service. The beacon clock service runs in the background and uses the system workqueue to periodically store the clock information in the non-volatile memory (NVM). To adjust the clock store interval, use the CONFIG_BT_FAST_PAIR_FHN_CLOCK_NVM_UPDATE_TIME Kconfig option. The service is used to measure time in seconds as a sum of two components: the system uptime (see k_uptime_get()) and beacon clock value as read from the non-volatile memory during the system boot.

Once the Provider is provisioned, it is important to keep the beacon clock synchronized with its counterpart value on the Seeker side. The clock drift is the difference between the beacon clock value as measured by the Seeker and the Provider. The beacon clock is used to calculate the Ephemeral Identifier (EID), which is a part of the FHN advertising payload. Seekers identify and track the provisioned Provider by analyzing the broadcasted EIDs in the advertising frames. Performing frequent system reboots or staying in the turned off state (for example, System OFF) may cause the clock drift to accumulate overtime. If the clock drift is too high, the Provider EID encoded in the FHN advertising payload becomes unidentifiable to Seeker devices.

When you disable the FHN extension using the bt_fast_pair_disable() function, the beacon clock service also gets terminated. As a result, the clock information is no longer updated in the non-volatile memory.

Caution

It is not recommended to persist in the disabled state for too long with the provisioned Provider, as your device may accumulate a significant clock drift on a power loss or reboot event.

DULT integration

The FHN extension uses the Detecting Unwanted Location Trackers (DULT) module to satisfy the requirements from the DULT specification. This guide describes the steps necessary to integrate the FHN extension with the DULT module. For more details on the DULT integration, see the Detecting Unwanted Location Trackers (DULT) integration documentation.

The DULT support for the FHN extension is controlled by the CONFIG_BT_FAST_PAIR_FHN_DULT Kconfig option. This option is enabled by default. The DULT support is required for small and not easily discoverable accessories, and is recommended for large accessories.

The FHN extension registers itself as a DULT user during the bt_fast_pair_enable() function call and unregisters itself during bt_fast_pair_disable() function call. If you have multiple DULT users in your application, you must ensure that there is only one DULT user registered at a time.

The FHN extension passes accessory information parameters to the DULT module during the registration process. These parameters are used for the FHN extension in the DULT module and are configured by the following Kconfig options:

For more details on how to set these Kconfig options, refer to the Fast Pair Unwanted Tracking Prevention Guidelines documentation.

Subsequent sections for the FHN extension describe further steps for integrating the DULT module once the DULT user is registered and the DULT module is successfully enabled during the bt_fast_pair_enable() function call.

Precision Finding

To support the optional Precision Finding feature, enable the CONFIG_BT_FAST_PAIR_FHN_PF Kconfig option in your project.

You must register the ranging management callbacks using the bt_fast_pair_fhn_pf_ranging_mgmt_cb_register() function before enabling the Fast Pair module with the bt_fast_pair_enable() function. Otherwise, the enable operation fails.

All callbacks in the bt_fast_pair_fhn_pf_ranging_mgmt_cb structure, except for the bt_fast_pair_fhn_pf_ranging_mgmt_cb.comm_channel_terminated callback, are mandatory to register.

See the Using the Precision Finding callbacks section for details on how to handle the ranging management workflow. For an integration example that uses Bluetooth Low Energy Channel Sounding as the ranging technology, see the Bluetooth Fast Pair: Locator tag sample.

Setting up Bluetooth LE advertising

The Fast Pair Provider must include Fast Pair service advertising data in the advertising payload. The Fast Pair Seeker must also know the Provider’s transmit power to determine proximity.

Note

The Fast Pair Advertising Manager helper module can be used to simplify the Fast Pair advertising management that is described in this integration step. This module is also compatible with the requirements of the FHN extension and its FHN advertising set that are also covered by this integration step. See Google Fast Pair Advertising Manager integration for more details on how to integrate it in your application.

Advertising data and parameters

The Fast Pair service implementation provides API to generate the advertising data for both discoverable and not discoverable advertising:

bt_fast_pair_adv_data_size(), bt_fast_pair_adv_data_fill()

These functions are used to check the buffer size required for the advertising data and fill the buffer with data. Managing memory used for the advertising packets is a responsibility of the application. Make sure that these functions are called by the application from the cooperative context to ensure that not discoverable advertising data generation is not preempted by an Account Key write operation from a connected Fast Pair Seeker. Account Keys are used to generate not discoverable advertising data.

bt_fast_pair_set_pairing_mode()

This function is used to set the pairing mode before the advertising is started.

Note

When the CONFIG_BT_FAST_PAIR_SUBSEQUENT_PAIRING Kconfig option is disabled, you cannot use the Fast Pair not discoverable advertising with UI indications (BT_FAST_PAIR_NOT_DISC_ADV_TYPE_SHOW_UI_IND). This type of advertising is required for triggering the subsequent pairing. For more details, see the Subsequent pairing section.

Since you control the advertising, make sure to use advertising parameters consistent with the specification. The Bluetooth privacy is selected by the Fast Pair service, but you must make sure that the following requirements are met:

  • The Resolvable Private Address (RPA) rotation is synchronized with the advertising payload update during the not discoverable advertising.

  • The Resolvable Private Address (RPA) address is not rotated during discoverable advertising session.

See the official Fast Pair Advertising documentation for detailed information about the requirements related to discoverable and not discoverable advertising.

Fast Pair advertising data provider

The Fast Pair advertising data provider (CONFIG_BT_ADV_PROV_FAST_PAIR) can be used to manage the Fast Pair advertising data. See Bluetooth Fast Pair: Input device for an example of using the provider in a sample. See subsys/bluetooth/adv_prov/providers/fast_pair.c for provider implementation.

Advertising TX power

The Fast Pair Seeker must know the TX power of the Provider to determine proximity. The TX power can be provided in one of the following ways:

  • Defined during model registration

  • Included in the advertising payload

See the Fast Pair TX power documentation for more information.

Advertising data provider

If your application uses Bluetooth LE advertising providers, you can use the TX power advertising data provider (CONFIG_BT_ADV_PROV_TX_POWER) to read the advertising TX power from Bluetooth controller and add it to the generated advertising data. The CONFIG_BT_ADV_PROV_TX_POWER_CORRECTION_VAL option can be used to define a TX power correction value that is added to the TX power readout included in the advertising data. The option can be used to take into account hardware configuration, for example, used antenna and device casing. See Bluetooth Fast Pair: Input device sample for an example of how to use the TX power advertising provider.

Multiprotocol Service Layer front-end module (MPSL FEM)

If your application uses MPSL Front-end module feature, you can use a front-end module power model. The power model allows you to control the TX power more accurately and compensate, for example, for external conditions. See the TX power split using models section of the Front-end module feature documentation for more details. See the MPSL FEM power model section in API documentation for API documentation.

Battery Notification extension

You can include special battery data in a not discoverable advertising packet using the Fast Pair Battery Notification extension. To use this extension, ensure the following:

  1. Enable the CONFIG_BT_FAST_PAIR_BN Kconfig option in your application configuration.

  2. Call the bt_fast_pair_battery_set() function to provide battery information.

  3. Set bt_fast_pair_not_disc_adv_info.battery_mode in bt_fast_pair_adv_config to either BT_FAST_PAIR_ADV_BATTERY_MODE_SHOW_UI_IND or BT_FAST_PAIR_ADV_BATTERY_MODE_HIDE_UI_IND to include the battery notification in the generated advertising payload.

See the Fast Pair Battery Notification extension documentation for more details about this extension.

FHN extension

The FHN extension requires an independent advertising set for location tracking operations. This advertising set hosts the FHN payload as defined in the FHN Accessory specification. The tracking protocol uses the Bluetooth LE Extended Advertising Zephyr API (CONFIG_BT_EXT_ADV) to support simultaneous broadcast of advertising sets, which are managed by the application and the FHN advertising set. The extension manages the FHN advertising set without the user’s assistance in the following ways:

  • It creates (bt_le_ext_adv_create()) and deletes (bt_le_ext_adv_delete()) the FHN advertising set. When the extension is enabled, you must reserve one Bluetooth advertising set from the Bluetooth advertising set pool (CONFIG_BT_EXT_ADV_MAX_ADV_SET). If all advertising sets are reserved for other purposes, the bt_le_ext_adv_create() function fails to create the FHN advertising set.

  • It starts (bt_le_ext_adv_start()) and stops (bt_le_ext_adv_stop()) the FHN advertising. The extension starts the FHN advertising after a successful FHN provisioning process and stops it after a successful unprovisioning process. Once provisioned, the Provider keeps advertising until Seekers use all connection slots (CONFIG_BT_FAST_PAIR_FHN_MAX_CONN) by connecting to the FHN advertising set. You must reserve CONFIG_BT_FAST_PAIR_FHN_MAX_CONN connection slots from the Bluetooth connection pool (CONFIG_BT_MAX_CONN).

  • It sets the advertising TX power for the FHN advertising set using the CONFIG_BT_FAST_PAIR_FHN_TX_POWER Kconfig option. The configuration is independent from the configuration option that is available for the standard Fast Pair advertising payload. FHN connections also use the same TX power as the FHN advertising set. The connection TX power is inherited from the advertising set that was used to establish it. Ensure that the chosen TX power configuration is supported by your hardware setup.

  • After successful FHN provisioning, it controls the Resolvable Private Address (RPA) rotation process for the whole Zephyr Bluetooth subsystem. The extension sets the RPA timeout using the bt_le_set_rpa_timeout() function to match the timeout for the FHN advertising payload update. The timeout is slightly different in each interval because it consists of a random component. The random part is used to improve the privacy properties of the protocol. In some cases, the extension triggers the RPA rotation asynchronously using the bt_le_oob_get_local() function. Such asynchronous RPA rotations currently happen right after successful FHN provisioning or when advertising is started after a period of inactivity (for example, due to unavailable connection slots).

    If you have any other advertising set in your application that contains unique device data in its advertising payload (for example, random nonce or identifiers), you must synchronize updates to their payload and RPA address with the FHN advertising set. Otherwise, the Bluetooth LE advertising process could potentially leak the privacy of your device. The Fast Pair not discoverable advertising payload is an example of a payload that needs to be updated in synchronization with the FHN payload.

Even though the FHN advertising is controlled by the extension, you must still manage the Fast Pair advertising process in your application. To comply with the requirements of the FHN extension, you must manage the Fast Pair advertising payload as part of application’s advertising set using the Bluetooth LE Extended Advertising Zephyr API. When creating the Fast Pair advertising set with the bt_le_ext_adv_create() function, register the bt_le_ext_adv_cb structure with the following callbacks:

  • The bt_le_ext_adv_cb.connected callback to track connections that are part of the application’s connection pool (and were not created from the FHN advertising set).

  • The bt_le_ext_adv_cb.rpa_expired() callback to synchronize the update of the application’s advertising sets’ payloads together with their respective Resolvable Private Addresses (RPA).

Important

You must manage application advertising sets according to the FHN provisioning state:

  • For the provisioned device, only update the Fast Pair advertising payload during the bt_le_ext_adv_cb.rpa_expired() callback execution. The FHN extension controls the RPA rotation time in this state, and no other module in your application is allowed to change the rotation time.

  • For the unprovisioned device, control the Fast Pair advertising rotation time using the bt_le_set_rpa_timeout() and bt_le_oob_get_local() functions. You must still comply with the requirements of the Fast Pair protocol.

The bt_fast_pair_fhn_is_provisioned() function can be used to check the current FHN provisioning state synchronously. Also, the provisioning state changes are indicated by the bt_fast_pair_fhn_info_cb.provisioning_state_changed callback. See Using the information callbacks for more details.

See the Bluetooth Fast Pair: Locator tag sample that demonstrates how to comply with the rules described in this section.

Bluetooth identity

To set the Bluetooth identity for FHN advertising and connections, use the bt_fast_pair_fhn_id_set() function. The Bluetooth identity cannot be updated if the Fast Pair module is in the ready state (see the bt_fast_pair_is_ready() function). The extension uses the BT_ID_DEFAULT identity by default.

Advertising interval

To configure the advertising interval for the FHN advertising set, use the bt_fast_pair_fhn_adv_param_set() function. You can change the advertising interval even when the FHN advertising is active. By default, the FHN advertising interval is set to two seconds, which is the maximum possible value.

Note

The advertising interval configuration has a significant impact on the battery life of your product. It also affects the time necessary to establish a new connection from the FHN advertising set.

The FHN Accessory specification determines the recommended ratio between the Fast Pair and FHN frames in the Fast Pair FHN advertising documentation section. To follow this recommendation, the application is responsible for adjusting the advertising interval of both the FHN and Fast Pair advertising sets.

Battery level indication

To specify the battery level broadcasted in the FHN advertising payload, use the bt_fast_pair_fhn_battery_level_set() function. You can update the battery level asynchronously without having to wait on the bt_le_ext_adv_cb.rpa_expired() callback.

The current API accepts the battery level as a percentage value, and ranges from 0% to 100%. This percentage value is first translated according to the quantified battery states defined in the FHN Accessory specification and then encoded in the FHN advertising set according to the following rules:

You can change the CONFIG_BT_FAST_PAIR_FHN_BATTERY_LEVEL_LOW_THR and the CONFIG_BT_FAST_PAIR_FHN_BATTERY_LEVEL_CRITICAL_THR Kconfig options to control the mapping of the battery percentage values to the battery levels as defined by the FHN Accessory specification. The mapping is implementation-specific and is up to you to select threshold values that fit your application requirements.

If an application does not specify the battery level using the API, the default level, battery level indication unsupported, is encoded in the FHN advertising payload.

In case the CONFIG_BT_FAST_PAIR_FHN_BATTERY_DULT Kconfig is enabled, you must initialize battery level with this API before you enable Fast Pair with the bt_fast_pair_enable() function. This requirement is necessary as the DULT battery mechanism does not support unknown battery levels. As a result, you must not call this API with the BT_FAST_PAIR_FHN_BATTERY_LEVEL_NONE value in this configuration variant.

If you want to support the battery information also in the DULT module, follow the instructions in the Battery information with DULT section.

Elliptic curve configuration

The key field in the FHN advertising payload is the Ephemeral Identifier (EID). The extension calculates the EID using elliptic curve cryptography. You can choose one of the supported elliptic curves for the EID calculation:

  • The secp160r1 elliptic curve configuration (CONFIG_BT_FAST_PAIR_FHN_ECC_SECP160R1):

    • The FHN advertising frames use the legacy PDU type (ADV_IND). The legacy advertising is understood by a wider range of devices than the extended advertising (higher adoption).

    • The 160-bit curve is less secure than the 256-bit curve.

    • The EID is 20 bytes long.

  • The secp256r1 elliptic curve configuration (CONFIG_BT_FAST_PAIR_FHN_ECC_SECP256R1):

    • The FHN advertising frames use the extended advertising PDU type (ADV_EXT_IND). The extended advertising is understood by a smaller range of devices than the legacy advertising (lower adoption).

    • The 256-bit curve is more secure than the 160-bit curve.

    • The EID is 32 bytes long.

By default, the FHN extension uses the secp160r1 elliptic curve configuration.

TX power

The Fast Pair Seeker receives the calibrated TX power from the Provider during the FHN provisioning process and uses it to measure distance based on the RSSI value. The Provider includes the calibrated TX power value in the Read Beacon Parameters response. Typically, the Seeker displays different status messages based on the measured distance when its user is trying to find the Provider device. For example, the It’s here status message is displayed in the Hot & Cold experience of the Find Hub app when the missing device is in very close proximity of the smartphone.

You can set the TX power for the FHN advertising and connections using the CONFIG_BT_FAST_PAIR_FHN_TX_POWER Kconfig option. The configured value is directly used to set the TX power in the Bluetooth LE controller using an HCI command. This Kconfig option must be set to 0 at minimum as the Fast Pair specification requires that the conducted Bluetooth transmit power for FHN advertisements must not be lower than 0 dBm. By default, 0 dBm is used for the FHN TX power configuration.

You can use the CONFIG_BT_FAST_PAIR_FHN_TX_POWER_CORRECTION_VAL Kconfig option to define a correction value that is added to TX power readout from the Bluetooth LE controller (usually equal to the CONFIG_BT_FAST_PAIR_FHN_TX_POWER Kconfig option), when calculating the calibrated TX power reported in the Read Beacon Parameters response. The hardware configuration, for example used antenna and device casing, may affect the actual TX power of packets broadcasted by the Fast Pair Provider. The correction value allows to improve the accuracy of the Fast Pair Seeker’s distance measurement. The calculated calibrated TX power should range between –100 dBm and 20 dBm.

You need to adjust the correction value for both the FHN extension and the TX power AD type in the Fast Pair advertising set. If your application uses the Bluetooth LE advertising providers library, see the Advertising data provider section for details on how to configure the TX power AD type in the Fast Pair advertising set. Otherwise, make sure to encode the calibrated TX power in the TX power AD type of the Fast Pair advertising set.

To select proper correction values, use the Calibration test from the FAST PAIR test category that is available in the Fast Pair Validator app.

Tip

If you plan to use a different TX power configuration for the FHN extension than for the Fast Pair advertising set, you need to perform individual calibration for the extension to select a proper correction value.

Interacting with GATT service

The Fast Pair GATT service is implemented by the Google Fast Pair Service (GFPS). The service implements functionalities required by the Fast Pair Procedure. The procedure is initiated by the Fast Pair Seeker after Bluetooth LE connection is established. No application interaction is required.

The Fast Pair GATT service is statically defined, so it is still present in the GATT database after the Fast Pair subsystem is disabled. In the Fast Pair subsystem disabled state, GATT operations on the Fast Pair service are rejected.

The Fast Pair GATT service modifies default values of related Kconfig options to follow Fast Pair requirements. The service also enables the needed functionalities using Kconfig select statement. For details, see the Google Fast Pair Service (GFPS) Bluetooth service documentation in the nRF Connect SDK.

Subsequent pairing

The Fast Pair specification supports the subsequent pairing feature. Subsequent pairing refers to the procedure between a Fast Pair Provider, initially paired with your Google account, and another Fast Pair Seeker logged into the same account.

To support the subsequent pairing feature in the Fast Pair Procedure, enable the CONFIG_BT_FAST_PAIR_SUBSEQUENT_PAIRING Kconfig option.

Consequently, the Fast Pair not discoverable advertising with UI indications, which is used to trigger the subsequent pairing UI flow, is only available when the subsequent pairing feature is supported.

Procedure without Bluetooth pairing

The Fast Pair specification allows the Fast Pair Procedure to operate in a special mode. In this mode, the Provider and Seeker skip the steps that involve Bluetooth pairing and bonding. In this case, the Fast Pair Procedure is only used to pass the Account Key from the Seeker to the Provider device.

You can enable the CONFIG_BT_FAST_PAIR_REQ_PAIRING configuration option to restrict the Fast Pair Procedure and allow it to execute only with the Bluetooth pairing and bonding step. By default, the CONFIG_BT_FAST_PAIR_REQ_PAIRING configuration option is disabled, and the procedure is not restricted by the Provider.

Using the information callbacks

To register the information callbacks, use the bt_fast_pair_info_cb_register() function.

All Account Key writes are indicated by the bt_fast_pair_info_cb.account_key_written callback. This callback is optional to register and is triggered on a successful Account Key write operation over the Account Key characteristic.

The typical use case of this callback is to have a notification mechanism that informs you about any updates to the Account Key storage. You may decide to use the Fast Pair not discoverable advertising mode on the first Account Key write or update this type of advertising payload on subsequent Account Key writes. In the Fast Pair not discoverable advertising mode, the Provider informs the listening Seeker devices about all Account Keys that it has stored so far. You can also use the bt_fast_pair_has_account_key() function to check whether your Provider has any Account Keys. This API is especially useful after a system reboot when some Account Keys may already be stored in non-volatile memory.

Fast Pair bond management functionality

To enable the Fast Pair bond management functionality, use the CONFIG_BT_FAST_PAIR_BOND_MANAGER Kconfig option. When this functionality is enabled, the Fast Pair subsystem tracks the Bluetooth bonds created through the Fast Pair Procedure and unpairs them if the procedure is incomplete or the Account Key associated with the bonds is removed. It also unpairs the Fast Pair Bluetooth bonds on Fast Pair factory reset, because the factory reset removes all Account Keys stored on device. Enabling the functionality imposes additional limitations related to enabling Fast Pair in runtime (bt_fast_pair_enable()). See the CONFIG_BT_FAST_PAIR_BOND_MANAGER Kconfig option help for more details about using the functionality.

The Fast Pair bond management functionality is disabled by default. Make sure that it is enabled for the following use cases of the Google Fast Pair application as it is highly recommended:

  • Input device

  • Mouse

See Tailoring protocol for specific use case for more details about the use cases of the Google Fast Pair application.

Firmware update intent

See Firmware update intent for a basic introduction regarding the firmware update intent feature and for information on how to configure your device in the Google Nearby Device console to support this feature.

To use the Android intent feature for firmware updates, your device must support the Device Information Service (DIS) and its Firmware Revision characteristic. You can disable all other DIS characteristics if they are not used for other purposes.

To enable the Zephyr DIS module and the Firmware Revision characteristic, set the CONFIG_BT_DIS and CONFIG_BT_DIS_FW_REV Kconfig options. If you use Zephyr’s Application version management feature and define the VERSION file in your project, the CONFIG_BT_DIS_FW_REV_STR Kconfig option is automatically set. Otherwise, set the CONFIG_BT_DIS_FW_REV_STR Kconfig option explicitly.

If your device model supports the FHN extension, also follow the additional guidelines to authenticate the connection before the firmware version read operation. For further details, see the Connection authentication section.

FHN extension

The FHN extension defines a new characteristic inside the Fast Pair service. The new characteristic is called Beacon Actions and is used to exchange extension-related messages between the Seeker and the Provider.

Using the information callbacks

Register the information callbacks in the FHN extension using the bt_fast_pair_fhn_info_cb_register() function. This callback registration is optional. You can register multiple callback sets using the bt_fast_pair_fhn_info_cb_register() function.

This function supports the following callbacks:

Provisioning state

The bt_fast_pair_fhn_is_provisioned() function can be used to check the current FHN provisioning state synchronously. You can only call this function in the ready state of the Fast Pair module (see the bt_fast_pair_is_ready() function).

The provisioning state changes are indicated by the bt_fast_pair_fhn_info_cb.provisioning_state_changed callback. This callback is triggered in the following scenarios:

  • On the successful provisioning operation over Beacon Actions characteristic.

  • On the successful unprovisioning operation over Beacon Actions characteristic.

The bt_fast_pair_fhn_is_provisioned() function and the bt_fast_pair_fhn_info_cb.provisioning_state_changed callback are two complementary API elements that can be used to track the FHN provisioning state in your application code. The recommended usage scenario is described in the next paragraph.

Use the bt_fast_pair_fhn_is_provisioned() function to initialize the provisioning state right after enabling the Fast Pair module with the bt_fast_pair_enable() function call. Then, handle the bt_fast_pair_fhn_info_cb.provisioning_state_changed callback to track the provisioning state changes until the Fast Pair module is disabled again with the bt_fast_pair_disable() function call.

The accurate tracking of the FHN provisioning state is mandatory for proper management of the Fast Pair and FHN advertising policies. The advertising policies are extensively described in the Setting up Bluetooth LE advertising section of this integration guide.

Clock synchronization

The clock synchronization is indicated by the bt_fast_pair_fhn_info_cb.clock_synced callback. This callback is triggered on a successful beacon clock read operation over Beacon Actions characteristic.

A typical use case for this callback is to synchronize the beacon clock after the system reboot of the accessory (for example, due to battery replacement). In this case, the affected device might have stayed in the power-down state for an unknown period of time. As a result, the beacon clock drift may become so high that the Ephemeral Identifier (EID) from the FHN advertising payload is no longer recognized by the Seeker devices. As a fallback mechanism for clock synchronization, the accessory must simultaneously advertise the Fast Pair not discoverable and FHN payloads right after the system reboot. The Fast Pair advertising frames make the affected Provider visible to nearby Seekers. Once one of the Seeker devices connects to the accessory and synchronizes the clock, the bt_fast_pair_fhn_info_cb.clock_synced callback is called to indicate that the Provider is no longer required to advertise the Fast Pair payload.

Connection authentication

The connected peer authentication is indicated by the bt_fast_pair_fhn_info_cb.conn_authenticated callback. This callback is triggered on a successful provisioning state read operation over the Beacon Actions characteristic. A successful operation proves that the connected peer has at least one of the Provider’s Account Keys.

A typical use case for this callback is to authenticate the connected peer and allow it to read the firmware version to support firmware update intents on the Android platform. See Firmware update intent for general information about the firmware update intent feature and the required configuration steps in the Google Nearby Device console. See Firmware update intent to learn how to prepare your Provider firmware to support the firmware update intent feature. You must meet the requirements in the linked sections before following the guidelines related to the FHN extension.

The firmware version is read by the Fast Pair Seeker over the Firmware Revision characteristic in the Device Information Service (DIS). It is assumed that DIS characteristics contain the identifying information and access to these characteristics should be limited to prevent tracking.

If the defined device model from the Google Nearby Devices console supports Bluetooth bonding during the Fast Pair procedure, you can replace the connection authentication mechanism based on the bt_fast_pair_fhn_info_cb.conn_authenticated callback with an alternative mechanism based on Bluetooth bonds. In this case, bonded devices are allowed to read the firmware version.

For further details on firmware updates in the FHN extension context, see the Fast Pair FHN firmware updates section in the FHN specification.

For an example of how to use the firmware update intents with the FHN extension, see the Bluetooth Fast Pair: Locator tag sample.

Using the read mode callbacks and managing the read mode state

The FHN extension defines special read modes, in which sensitive data can be read from the device by the connected peer. The read mode persists only for limited time after which it is deactivated.

To enter the chosen read mode, you must call the bt_fast_pair_fhn_read_mode_enter() function and pass the supported read mode type as a function parameter. You can only call this function in the ready state of the Fast Pair module (see the bt_fast_pair_is_ready() function) and in the FHN provisioned state (see the bt_fast_pair_fhn_is_provisioned() function). The FHN extension supports the following read mode types:

  • BT_FAST_PAIR_FHN_READ_MODE_FHN_RECOVERY - Ephemeral Identity Key (EIK) recovery mode

  • BT_FAST_PAIR_FHN_READ_MODE_DULT_ID - Identification mode This mode is available only when the CONFIG_BT_FAST_PAIR_FHN_DULT Kconfig option is enabled.

To register the read mode callbacks, use the bt_fast_pair_fhn_read_mode_cb_register() function. Callback registration is optional. You can register only one callback set with this function, as the subsequent call overrides the previous set. The bt_fast_pair_fhn_read_mode_cb_register() function supports currently only one callback type, bt_fast_pair_fhn_read_mode_cb.exited, that provides a notification when the specific read mode is over. Read mode exit occurs when the read mode naturally times out or when it is forcefully canceled (for example, during the bt_fast_pair_disable() function call).

When the device is already in the selected read mode, you can call the bt_fast_pair_fhn_read_mode_enter() function with the same read mode type to prolong its timeout.

The BT_FAST_PAIR_FHN_READ_MODE_FHN_RECOVERY read mode type is called EIK recovery mode. This mode is mandatory to support, as it enables the EIK recovery operation. The FHN extension validates if the mode is active during the EIK read operation over Beacon Actions characteristic. This read operation is accepted only when the device is in the recovery mode. It is recommended to enter this mode after a user interaction (for example, a button press). This physical interaction constitutes user consent to activate the recovery mode. You can configure the timeout of the recovery mode using the CONFIG_BT_FAST_PAIR_FHN_READ_MODE_FHN_RECOVERY_TIMEOUT Kconfig option.

The BT_FAST_PAIR_FHN_READ_MODE_DULT_ID read mode type is called identification mode. This mode is only available when the DULT integration with the FHN extension is enabled with the CONFIG_BT_FAST_PAIR_FHN_DULT Kconfig option. In this configuration, your application must implement support for this mode. The identification mode allows for reading the Identifier Payload defined in the Detecting Unwanted Location Trackers (DULT) specification. This read operation is accepted only when the device is in the identification mode. For more details on the Identifier Payload in the DULT module, see the Managing the identification process documentation. It is recommended to enter this mode after a user interaction (for example, a button press). This physical interaction constitutes user consent to activate the identification mode. Apart from that, the device should emit visual or audio signal to indicate mode activation. The timeout of the identification mode is equal to five minutes according to the DULT specification requirements and cannot be configured by the user. For more details on the identification mode, refer to the Fast Pair Unwanted Tracking Prevention Guidelines documentation.

Using the ringing callbacks and managing the ringing state

Select the number of ringing components that you want to support in your application configuration (see the CONFIG_BT_FAST_PAIR_FHN_RING_COMP choice configuration). You can only pick one of the following options:

Apart from the ringing component configuration, you can enable support for the ringing volume feature by setting the CONFIG_BT_FAST_PAIR_FHN_RING_VOLUME option. When this option is enabled, you should be able to individually set the volume for all of your ringing components, choosing from the three provided levels. For some devices, however, volume adjustment options may not be available. In such a case, you should keep the ringing volume feature disabled and use the default volume (BT_FAST_PAIR_FHN_RING_VOLUME_DEFAULT) for all declared ringing components.

To adjust volume levels for the devices that support the feature, use the following options:

  • Low (BT_FAST_PAIR_FHN_RING_VOLUME_LOW)

  • Medium (BT_FAST_PAIR_FHN_RING_VOLUME_MEDIUM)

  • High (BT_FAST_PAIR_FHN_RING_VOLUME_HIGH)

If your application configuration supports at least one ringing component, you must register the ringing callbacks using the bt_fast_pair_fhn_ring_cb_register() function. In this case, all ringing callbacks defined in the bt_fast_pair_fhn_ring_cb structure are mandatory to register.

Ringing callbacks pass the information about the source that triggered the ringing activity as the first parameter of the callback function. The following sources of ringing activity are supported:

  • BT_FAST_PAIR_FHN_RING_SRC_FHN_BT_GATT - This ringing source originates from the Bluetooth Fast Pair service and its Beacon Actions characteristic that is defined in the FHN Accessory specification.

  • BT_FAST_PAIR_FHN_RING_SRC_DULT_BT_GATT - This ringing source originates from the Bluetooth Accessory Non-owner service and its characteristic that are defined in the DULT specification. This source is available only when the CONFIG_BT_FAST_PAIR_FHN_DULT Kconfig option is enabled.

  • BT_FAST_PAIR_FHN_RING_SRC_DULT_MOTION_DETECTOR - This ringing source originates from the DULT motion detector module. This source is available only when the CONFIG_BT_FAST_PAIR_FHN_DULT_MOTION_DETECTOR Kconfig option is enabled.

The following callbacks are defined in the bt_fast_pair_fhn_ring_cb structure:

You must treat all callbacks from the bt_fast_pair_fhn_ring_cb structure as requests. The internal ringing state of the extension is not automatically changed on any callback event. The state is only changed when you acknowledge such a request in your application using the bt_fast_pair_fhn_ring_state_update() function.

Note

The ringing timeout countdown starts once you report a start or restart of the ringing action using the bt_fast_pair_fhn_ring_state_update() function.

You must call the bt_fast_pair_fhn_ring_state_update() function whenever the bitmask with active ringing components changes due to the extension initiated operations. Additionally, you must also call this function in response to the bt_fast_pair_fhn_ring_cb.start_request and the bt_fast_pair_fhn_ring_cb.stop_request callbacks in case of a failure (no bitmask change). A call to the bt_fast_pair_fhn_ring_state_update() function sends a message with the ringing state update. The message is sent over the ringing source that is used by the connected peer.

You must select the ringing source that is passed to the bt_fast_pair_fhn_ring_state_update() function as a first parameter. Typically, you pass the ringing source that is used in the last ringing callback that triggered the ringing state update. In certain edge cases, you can get two simultaneous requests to start ringing with two different sources before you are able to indicate the start of ringing with the bt_fast_pair_fhn_ring_state_update() function. In this situation, you need to select the preferred ringing source.

You must also configure the following fields in the bt_fast_pair_fhn_ring_state_param structure that is passed to the bt_fast_pair_fhn_ring_state_update() function as a second parameter:

  • Trigger for the new ringing state:

    • Started (BT_FAST_PAIR_FHN_RING_TRIGGER_STARTED): set in response to the bt_fast_pair_fhn_ring_cb.start_request callback when at least one component from the requested set has started to ring.

    • Failed (BT_FAST_PAIR_FHN_RING_TRIGGER_FAILED):

    • Stopped on timeout (BT_FAST_PAIR_FHN_RING_TRIGGER_TIMEOUT_STOPPED): set in response to the bt_fast_pair_fhn_ring_cb.timeout_expired callback when at least one component has stopped ringing.

    • Stopped on a button press (BT_FAST_PAIR_FHN_RING_TRIGGER_UI_STOPPED): set in response to the application-specific button press when at least one component has stopped ringing.

    • Stopped on a GATT request (BT_FAST_PAIR_FHN_RING_TRIGGER_GATT_STOPPED): set in response to the bt_fast_pair_fhn_ring_cb.stop_request callback when at least one component has stopped ringing.

  • Bitmask with currently ringing components.

  • Remaining ringing timeout in deciseconds (can be set to zero to preserve the existing timeout).

If you cannot start the ringing action on all requested components (for example, one of them is out of range), you must set the started trigger and update the connected peer with a ringing state update using the bt_fast_pair_fhn_ring_state_update() function. Once an unavailable component becomes reachable, you can start the delayed ringing action on it and send another update to the connected peer with the bt_fast_pair_fhn_ring_state_update() function. Alternatively, you can also ignore it and exclude it altogether from the current ringing action.

Handle a partially executed ringing stop request (with at least one of the components still ringing) in the similar way. This update policy applies to all listed stop trigger types.

To satisfy the requirements from the DULT specification when the CONFIG_BT_FAST_PAIR_FHN_DULT Kconfig option is enabled, the FHN extension communicates with the DULT module to receive ringing requests from the DULT peers and to send updates regarding the ringing state. For more details on the ringing mechanism in the DULT module, see the Using the sound callbacks and managing the sound state documentation.

Interacting with the motion detector from DULT

The motion detector is an optional feature of the DULT subsystem that can be integrated into the FHN extension. For more details about the feature, see the DULT motion detector section of the DULT specification. To activate the DULT motion detector functionality in the FHN extension, enable the CONFIG_BT_FAST_PAIR_FHN_DULT_MOTION_DETECTOR Kconfig option. The FHN extension implementation acts as a thin wrapper for the DULT motion detector module callbacks. It passes callbacks from the DULT motion detector module to the user application.

To register the motion detector callbacks, use the bt_fast_pair_fhn_motion_detector_cb_register() function. You must register all motion detector callbacks defined in the bt_fast_pair_fhn_motion_detector_cb structure:

The motion detector is started by the DULT subsystem when the accessory is in the separated state for an amount of time controlled by the CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MIN and CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MAX Kconfig options. When the motion is detected during the motion detector active period, the bt_fast_pair_fhn_ring_cb.start_request callback is called to request the ringing action with the BT_FAST_PAIR_FHN_RING_SRC_DULT_MOTION_DETECTOR parameter as the ringing source. Emitted sounds help to alert the non-owner that they are carrying an accessory that does not belong to them and might be used by the original owner to track their location.

Battery information with DULT

Enable the CONFIG_BT_FAST_PAIR_FHN_BATTERY_DULT Kconfig option to pass the battery level information from the FHN extension to the DULT module. You need to have the CONFIG_BT_FAST_PAIR_FHN_DULT Kconfig option enabled that indicates the general DULT integration in the FHN extension.

The battery level information is passed using the bt_fast_pair_fhn_battery_level_set() function. For more details on how to use this function, see the Battery level indication section. Similarly to the FHN battery level indication feature, the DULT module uses Kconfig options to map percentage values to battery levels that are defined in the DULT specification. For more details on how to use these Kconfig options, see the Managing the battery information documentation.

Using the Precision Finding callbacks

The optional Precision Finding feature uses the Beacon Actions characteristic to exchange ranging management messages between the Seeker and the Provider. Register the ranging management callbacks using the bt_fast_pair_fhn_pf_ranging_mgmt_cb_register() function before enabling the Fast Pair module with the bt_fast_pair_enable() function. See the Precision Finding section for more details on the prerequisite operations.

The ranging management workflow consists of the following phases:

  1. Capability discovery - The Seeker sends a Ranging Capability Request to discover which ranging technologies the Provider supports. This request is indicated by the bt_fast_pair_fhn_pf_ranging_mgmt_cb.ranging_capability_request callback. The application must determine which of the requested ranging technologies it supports and respond using the bt_fast_pair_fhn_pf_ranging_capability_response_send() function. The response includes a bitmask of the supported technologies and an array of technology-specific capability payloads. The order of capability payloads in the array determines the ranging technology priority, with the first element having the highest priority.

  2. Configuration and start - The Seeker sends a Ranging Configuration Request to configure and start the ranging sessions for the selected technologies. This request is indicated by the bt_fast_pair_fhn_pf_ranging_mgmt_cb.ranging_config_request callback. The callback provides the technology-specific configuration payloads for each ranging technology that must be configured and started. The application must configure the requested technologies, start the ranging sessions, and respond using the bt_fast_pair_fhn_pf_ranging_config_response_send() function.

  3. Stop - The Seeker sends a Stop Ranging Request to stop active ranging sessions. This request is indicated by the bt_fast_pair_fhn_pf_ranging_mgmt_cb.stop_ranging_request callback. The application must stop the specified ranging technologies and respond using the bt_fast_pair_fhn_pf_stop_ranging_response_send() function.

You can call all response functions asynchronously outside of the callback context, as the preparation, configuration, or teardown of certain ranging technologies may require time to complete.

The optional bt_fast_pair_fhn_pf_ranging_mgmt_cb.comm_channel_terminated callback is called when the communication channel for ranging is terminated. This can occur on a Bluetooth LE disconnection or when the Fast Pair module is disabled. The application can use this callback to implement the ranging timeout and clean up any active ranging sessions associated with the connection.

Bluetooth Low Energy Channel Sounding

The Precision Finding API provides helper functions for encoding and decoding the technology-specific payloads when using Bluetooth Low Energy Channel Sounding as the ranging technology.

Use the bt_fast_pair_fhn_pf_ble_cs_ranging_capability_encode() function to encode the Bluetooth Low Energy Channel Sounding ranging capability descriptor (bt_fast_pair_fhn_pf_ble_cs_ranging_capability) into a technology-specific payload for the Ranging Capability Response. The capability descriptor includes the bitmask of supported Bluetooth Low Energy Channel Sounding security levels and the local Bluetooth device address to use for the ranging session.

Note

To work around the Android platform limitations, the local Bluetooth device address provided in the Bluetooth Low Energy Channel Sounding ranging capability descriptor must be set to the Resolvable Private Address (RPA) that was used for pairing during the Fast Pair procedure. It is recommended that the application saves the pairing address in non-volatile memory to ensure that the Precision Finding feature remains functional across device reboots.

Use the bt_fast_pair_fhn_pf_ble_cs_ranging_config_decode() function to decode the Bluetooth Low Energy Channel Sounding configuration data from the technology-specific payload received in the Ranging Configuration Request callback. The decoded configuration descriptor (bt_fast_pair_fhn_pf_ble_cs_ranging_config) contains the security level selected by the Seeker and the peer’s Bluetooth device address.

For a complete integration example with Bluetooth Low Energy Channel Sounding, see the ranging module of the Bluetooth Fast Pair: Locator tag sample.

Managing factory resets

The Fast Pair GATT service uses a non-volatile memory to store the Fast Pair user data such as Account Keys and the Personalized Name. This data can be cleared by calling the bt_fast_pair_factory_reset() function. Calling the bt_fast_pair_factory_reset() function does not affect the Fast Pair subsystem’s readiness. If the subsystem is enabled with the bt_fast_pair_enable() function, it stays enabled after calling the bt_fast_pair_factory_reset() function. The same applies for the Fast Pair subsystem disabled state. For details, see the bt_fast_pair_factory_reset() function documentation.

Custom user reset action

Use the CONFIG_BT_FAST_PAIR_STORAGE_USER_RESET_ACTION Kconfig option to enable a custom user reset action that executes together with the factory reset operation. To define the custom user reset action, you need to implement the bt_fast_pair_factory_reset_user_action_perform() function in your application code. The function is defined as a weak, no-op function. Ensure that your reset action implementation executes correctly in the following execution contexts:

Caution

If the factory reset operation constantly fails due to an error in the custom user reset action, the system may never be able to properly boot-up.

During the custom user reset action, you can safely delete additional non-volatile data that are not owned by the Fast Pair modules. A typical use case is to delete Bluetooth bonding information using either the bt_unpair() or the bt_id_reset() function.

For an example on how to use the custom reset action, see the Bluetooth Fast Pair: Locator tag sample.

FHN extension

The FHN extension additionally stores the following data in the non-volatile memory:

  • Owner Account Key (a special Account Key with additional permissions).

  • Ephemeral Identity Key (EIK).

  • Beacon clock.

To perform the factory reset of all Fast Pair non-volatile data, ensure that the Fast Pair module is in the unready state (see the bt_fast_pair_is_ready() function). In the ready state of the module, the bt_fast_pair_factory_reset() function does not perform a factory reset and returns with an error.

Tailoring protocol for specific use case

The specific use case of the Google Fast Pair application is indicated by the chosen device type in the Google Nearby Devices console (see the Device type subsection). In the official Fast Pair documentation, the Fast Pair Device Feature Requirements category defines additional requirements for each supported use case, and specifies a list of mandatory, optional, and unsupported Fast Pair features. If your product is targeting one of the listed use cases, you must align your accessory firmware to meet these requirements.

Depending on your use case, select an option from the following list that is a part of the CONFIG_BT_FAST_PAIR_USE_CASE Kconfig choice:

The selected Kconfig option configures the Fast Pair features and extensions to satisfy the Fast Pair Device Feature Requirements for your target use case. For certain device types, you may need to implement some of these requirements at the application level. In this case, refer to the following subsections describing Fast Pair use cases supported by the nRF Connect SDK.

Note

To learn about the software maturity levels for Google Fast Pair use cases supported by the nRF Connect SDK, see the Google Fast Pair use case support table.

Unknown

The CONFIG_BT_FAST_PAIR_USE_CASE_UNKNOWN Kconfig option is the default selection for the CONFIG_BT_FAST_PAIR_USE_CASE Kconfig choice option. This use case configuration is neutral, which means it does not enable any Fast Pair features and extensions or impose restrictions on Fast Pair Kconfig options. You can use the CONFIG_BT_FAST_PAIR_USE_CASE_UNKNOWN Kconfig option to implement use cases that are not yet supported by the nRF Connect SDK. In this case, you must manually enable the required Fast Pair features and extensions in the application’s Kconfig configuration.

Input device

Input device is a Human Interface Device (HID) such as a mouse, keyboard, remote control, or gaming pad used to interact with electronic devices such as a PC, TV, or console.

If your product is targeting the input device use case, you must enable the CONFIG_BT_FAST_PAIR_USE_CASE_INPUT_DEVICE Kconfig option that automatically selects the appropriate Fast Pair configuration. Currently, the Google Fast Pair specification does not define the input device feature requirements. For this reason, the Fast Pair feature and extension set is chosen arbitrarily to ensure the best user experience.

You must declare support for the input device use case when registering your device in the Google Nearby Device console. To enable the support, select the Input Device option from the Device Type list in the Fast Pair protocol configuration panel.

Locator tag

Locator tag is a small electronic device that can be attached to an object or a person, and is designed to help locate them in case they are missing. The locator tags can use different wireless technologies like GPS, Bluetooth LE or UWB for location tracking. It is even possible to combine multiple technologies in a single product to improve the user experience.

The Fast Pair Device Feature Requirements for Locator Tags documentation defines the Fast Pair requirements for the locator tag use case. If your product is targeting the locator tag use case, you must enable the CONFIG_BT_FAST_PAIR_USE_CASE_LOCATOR_TAG Kconfig option that automatically selects the appropriate Fast Pair configuration according to the use case requirements. This Kconfig option activates the necessary Fast Pair features and extensions while restricting the unsupported ones. For the reference configuration of the Fast Pair Device Feature Requirements for Locator Tags specification, see the Bluetooth Fast Pair: Locator tag sample.

The Fast Pair Device Feature Requirements for Locator Tags documentation refers to the Fast Pair Locator Tag Specific Guidelines section from the FHN Accessory specification. You must implement the guidelines at application level as they cannot be automatically handled by the Fast Pair subsystem. Implement these guidelines in your application if your product is targeting the locator tag use case. To see how to implement Fast Pair Locator Tag Specific Guidelines , see the Bluetooth Fast Pair: Locator tag sample.

Note

You can configure the Fast Pair Advertising Manager helper module to automatically handle locator tag guidelines related to the Fast Pair advertising. Read through the Fast Pair Advertising Manager section to learn more about this module.

You must declare support for the locator tag use case when registering your device in the Google Nearby Device console. To enable the support, populate the Fast Pair protocol configuration panel in the following order:

  1. Select the Locator Tag option from the Device Type list.

  2. Set the Find My Device feature to true.

Note

It is recommended to use the special mode of the Fast Pair Procedure for the locator tag use case (see Procedure without Bluetooth pairing for more details). The Bluetooth bonding information can cause connection establishment issues and delays on some Android devices.

Fast Pair Advertising Manager

It is recommended to use the Fast Pair Advertising Manager helper module for Fast Pair advertising management in the locator tag use case. This module follows the requirements of the FHN extension and is compatible with the FHN advertising set. It also provides additional layer for the locator tag use case. You can configure it using the CONFIG_BT_FAST_PAIR_ADV_MANAGER_USE_CASE_LOCATOR_TAG Kconfig option, that implements Fast Pair advertising requirements specified in the Fast Pair Locator Tag Specific Guidelines section of the FHN Accessory specification. The Bluetooth Fast Pair: Locator tag sample demonstrates how you can integrate the Fast Pair Advertising Manager in your application. See also Google Fast Pair Advertising Manager integration page that provides a comprehensive guide on how to integrate it in your application.

Precision Finding

You can optionally integrate the Precision Finding in the locator tag use case to enable precise distance measurement between the locator tag and the Seeker device. To enable this feature, follow the instructions in the Precision Finding section. The Bluetooth Fast Pair: Locator tag sample demonstrates how to use the Precision Finding with Bluetooth Low Energy Channel Sounding as the ranging technology. The ranging module in the sample is enabled by default on board targets with Bluetooth Low Energy Channel Sounding hardware support.

Note

Using the Precision Finding feature with Bluetooth Low Energy CS as the ranging technology requires Bluetooth bond creation during the Fast Pair Procedure, since bonding is mandatory for Bluetooth Low Energy CS. If Bluetooth bonding was previously disabled for your device model, enabling this feature changes the Fast Pair Procedure flow by adding the bonding step to the existing flow.

Mouse

Mouse is a Human Interface Device (HID) used to interact with electronic devices such as a PC. This use case is a specific variant of the Input device and shares many similarities with it.

If your product is targeting the mouse use case, you must enable the CONFIG_BT_FAST_PAIR_USE_CASE_MOUSE Kconfig option that automatically selects the appropriate Fast Pair configuration. Currently, the Google Fast Pair specification does not specify the mouse feature requirements. For this reason, the Fast Pair feature and extension set is chosen arbitrarily to ensure the best user experience.

You must declare support for the mouse use case when registering your device in the Google Nearby Device console. To enable the support, select the Mouse option from the Device Type list in the Fast Pair protocol configuration panel.

Note

The mouse device type is not supported on Android devices.

Applications and samples

The following application and sample use the Fast Pair integration in the nRF Connect SDK:

Library support

The following nRF Connect SDK libraries support the Fast Pair integration:

Required scripts

The Fast Pair provision script is required to generate the provisioning data for the device. The build system calls it automatically when building with Fast Pair in the nRF Connect SDK.

Terms and licensing

The use of Google Fast Pair may be subject to Google’s terms and licensing. Refer to the official Fast Pair documentation for development-related licensing information.

Dependencies

The following are the required dependencies for the Fast Pair integration: