Google Fast Pair Service (GFPS)

The Google Fast Pair Service (Fast Pair for short) implements a Bluetooth® LE GATT Service required when Using Google Fast Pair with the nRF Connect SDK.

Service UUID

The Fast Pair service uses UUID of 0xFE2C.

Characteristics

The Fast Pair GATT characteristics are described in detail in the Fast Pair GATT Characteristics documentation. The implementation in the nRF Connect SDK follows these requirements.

Configuration

Set the CONFIG_BT_FAST_PAIR to enable the module.

The following Kconfig options are also available for this module:

See the Kconfig help for details.

Override of default Kconfig values

To simplify the configuration process, the GFPS modifies the default values of related Kconfig options to meet the Fast Pair requirements. The service also enables some of the functionalities using Kconfig select statement.

Bluetooth privacy

The service selects Bluetooth privacy (CONFIG_BT_PRIVACY).

During not discoverable advertising, the Resolvable Private Address (RPA) rotation must be done together with the Fast Pair payload update. Because of this, the RPA cannot be rotated by Zephyr in the background.

During discoverable advertising session, the Resolvable Private Address (RPA) rotation must not happen. Therefore, consider the following points:

  • Make sure that your advertising session is shorter than the value in the CONFIG_BT_RPA_TIMEOUT option.

  • Call bt_le_oob_get_local() to trigger RPA rotation and reset the RPA timeout right before the start of advertising.

Bluetooth Security Manager Protocol (SMP)

The service selects CONFIG_BT_SMP, CONFIG_BT_SMP_APP_PAIRING_ACCEPT, and CONFIG_BT_SMP_ENFORCE_MITM. The Fast Pair specification requires support for Bluetooth LE pairing and enforcing Man-in-the-Middle (MITM) protection during the Fast Pair procedure.

Firmware Revision characteristic

The Fast Pair specification requires enabling GATT Device Information Service and the Firmware Revision characteristic. For this reason, the default values of CONFIG_BT_DIS and CONFIG_BT_DIS_FW_REV, respectively, are set to enabled. The default value of CONFIG_BT_DIS_FW_REV_STR is set to CONFIG_MCUBOOT_IMAGE_VERSION if CONFIG_BOOTLOADER_MCUBOOT is enabled. Otherwise, it is set to 0.0.0+0.

MTU configuration

The Fast Pair specification suggests using ATT maximum transmission unit (MTU) value of 83 if possible. Because of this requirement, the default values of the following Kconfig options are modified by the GFPS Kconfig:

Tip

In case of nRF53 Series, this part of the configuration cannot be automatically updated for the network core and you must manually align it. The listed options must be set on the network core to default values specified by the GFPS Kconfig options.

Security re-establishment

By default, the Fast Pair service disables the automatic security re-establishment request as a peripheral (CONFIG_BT_GATT_AUTO_SEC_REQ). This is done to allow Fast Pair Seeker to control the security re-establishment.

Partition Manager

The Fast Pair provisioning data is preprogrammed to a dedicated flash memory partition. The GFPS selects CONFIG_PM_SINGLE_IMAGE to enable the Partition Manager.

Settings

The GFPS uses Zephyr’s Settings to store Account Keys. Because of this, the GFPS selects CONFIG_SETTINGS.

Implementation details

The implementation uses BT_GATT_SERVICE_DEFINE to statically define and register the Fast Pair GATT service. The Fast Pair service automatically handles all of the requests received from the Fast Pair Seeker. No application input is required to handle the requests.

Bluetooth authentication

The Bluetooth pairing is handled using a set of Bluetooth authentication callbacks (bt_conn_auth_cb). The pairing flow and the set of Bluetooth authentication callbacks in use depend on whether the connected peer follows the Fast Pair pairing flow:

  • If the peer follows the Fast Pair pairing flow, the Fast Pair service calls bt_conn_auth_cb_overlay() to automatically overlay the Bluetooth authentication callbacks. The function is called while handling the Key-based Pairing request. Overlying callbacks allow the GFPS to take over Bluetooth authentication during Fast Pair Procedure and perform all of the required operations without interacting with the application.

  • If the peer does not follow the Fast Pair pairing flow, normal Bluetooth LE pairing and global Bluetooth authentication callbacks are used.

API documentation

Header file: include/bluetooth/services/fast_pair.h
Source files: subsys/bluetooth/services/fast_pair
group bt_fast_pair

Fast Pair API.

Defines

BT_FAST_PAIR_BATTERY_LEVEL_UNKNOWN

Value that denotes unknown battery level (see bt_fast_pair_battery).

Enums

enum bt_fast_pair_adv_mode

Fast Pair advertising mode. Used to generate advertising packet.

According to Fast Pair specification, when no Account Key has been saved on the device both Fast Pair not discoverable advertising modes result in the same advertising data.

Values:

enumerator BT_FAST_PAIR_ADV_MODE_DISCOVERABLE

Fast Pair discoverable advertising.

enumerator BT_FAST_PAIR_ADV_MODE_NOT_DISCOVERABLE_SHOW_UI_IND

Fast Pair not discoverable advertising, show UI indication.

enumerator BT_FAST_PAIR_ADV_MODE_NOT_DISCOVERABLE_HIDE_UI_IND

Fast Pair not discoverable advertising, hide UI indication.

enumerator BT_FAST_PAIR_ADV_MODE_COUNT

Number of Fast Pair advertising modes.

enum bt_fast_pair_adv_battery_mode

Fast Pair advertising battery mode. Used to generate advertising packet.

Battery data can be included in advertising packet only if the Fast Pair Provider is in Fast Pair not discoverable advertising mode. To prevent tracking, the Fast Pair Provider should not include battery data in the advertising packet all the time.

Values:

enumerator BT_FAST_PAIR_ADV_BATTERY_MODE_NONE

Do not advertise battery data.

enumerator BT_FAST_PAIR_ADV_BATTERY_MODE_SHOW_UI_IND

Show battery data UI indication.

enumerator BT_FAST_PAIR_ADV_BATTERY_MODE_HIDE_UI_IND

Hide battery data UI indication.

enumerator BT_FAST_PAIR_ADV_BATTERY_MODE_COUNT

Number of Fast Pair advertising battery modes.

enum bt_fast_pair_battery_comp

Index of Fast Pair battery component.

Values:

enumerator BT_FAST_PAIR_BATTERY_COMP_LEFT_BUD

Left bud.

enumerator BT_FAST_PAIR_BATTERY_COMP_RIGHT_BUD

Right bud.

enumerator BT_FAST_PAIR_BATTERY_COMP_BUD_CASE

Case.

enumerator BT_FAST_PAIR_BATTERY_COMP_COUNT

Number of battery values.

Functions

size_t bt_fast_pair_adv_data_size(struct bt_fast_pair_adv_config fp_adv_config)

Get Fast Pair advertising data buffer size.

Parameters

  • fp_adv_config – [in] Fast Pair advertising config.

Returns

Fast Pair advertising data buffer size in bytes if the operation was successful. Otherwise zero is returned.

int bt_fast_pair_adv_data_fill(struct bt_data *adv_data, uint8_t *buf, size_t buf_size, struct bt_fast_pair_adv_config fp_adv_config)

Fill Bluetooth advertising packet with Fast Pair advertising data.

Provided buffer will be used in bt_data structure. The data must be valid while the structure is in use.

The buffer size must be at least bt_fast_pair_adv_data_size. Caller shall also make sure that Account Key write from a connected Fast Pair Seeker would not preempt generating Fast Pair not discoverable advertising data. To achieve this, this function and bt_fast_pair_adv_data_size should be called from context with cooperative priority.

Parameters

  • adv_data – [out] Pointer to the Bluetooth advertising data structure to be filled.

  • buf – [out] Pointer to the buffer used to store Fast Pair advertising data.

  • buf_size – [in] Size of the buffer used to store Fast Pair advertising data.

  • fp_adv_config – [in] Fast Pair advertising config.

Returns

0 if the operation was successful. Otherwise, a (negative) error code is returned.

void bt_fast_pair_set_pairing_mode(bool pairing_mode)

Enable or disable Fast Pair pairing mode.

Pairing mode must be enabled if discoverable Fast Pair advertising is used. Pairing mode must be disabled if not discoverable Fast Pair advertising is used.

It is user responsibility to make sure that proper pairing mode is used before advertising is started. Fast Pair pairing mode is enabled by default.

Parameters

  • pairing_mode – [in] Boolean indicating if device is in pairing mode.

bool bt_fast_pair_has_account_key(void)

Check Account Key presence.

Caller shall make sure that Account Key write from a connected Fast Pair Seeker would not preempt this function call. Otherwise invalid value may be returned.

The function always returns false if called before Zephyr settings are loaded.

Returns

True if device already has an Account Key, false otherwise.

int bt_fast_pair_battery_set(enum bt_fast_pair_battery_comp battery_comp, struct bt_fast_pair_battery battery)

Set or update specified battery value.

Battery values are used to generate advertising packet. To include battery values in advertising packet this function must be called before bt_fast_pair_adv_data_fill. It is user responsibility to update battery value and regenerate advertising packet when battery value change.

Parameters

  • battery_comp – [in] Battery component.

  • battery – [in] Battery value.

Return values

  • 0 – on success.

  • -EINVAL – if battery value is invalid.

int bt_fast_pair_factory_reset(void)

Perform a reset to the default factory settings for Google Fast Pair Service.

Clears the Fast Pair storage. If the reset operation is interrupted by system reboot or power outage, the reset is automatically resumed at the stage of loading the Fast Pair storage. It prevents the Fast Pair storage from ending in unwanted state after the reset interruption.

Returns

0 if the operation was successful. Otherwise, a (negative) error code is returned.

struct bt_fast_pair_adv_config
#include <fast_pair.h>

Fast Pair advertising config. Used to generate advertising packet.

Public Members

enum bt_fast_pair_adv_mode adv_mode

Fast Pair advertising mode.

enum bt_fast_pair_adv_battery_mode adv_battery_mode

Fast Pair advertising battery mode.

struct bt_fast_pair_battery
#include <fast_pair.h>

Fast Pair battery component descriptor.

Public Members

bool charging

Battery status. True means that battery is charging and False means that battery is not charging.

uint8_t level

Battery level ranging from 0 to 100 percent. Use BT_FAST_PAIR_BATTERY_LEVEL_UNKNOWN for unknown.