Google Fast Pair Service (GFPS)

The Google Fast Pair Service (Fast Pair for short) implements a Bluetooth® Low Energy (LE) GATT Service required for Google Fast Pair integration 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.

The Fast Pair service also contains additional GATT characteristics under the following conditions:

  • The Additional Data GATT characteristic is enabled when an extension requires it. Currently, only the Personalized Name extension (CONFIG_BT_FAST_PAIR_PN) requires this characteristic.

Configuration

Set the CONFIG_BT_FAST_PAIR Kconfig option to enable the service.

The following Kconfig options are also available for this service:

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 the bt_le_oob_get_local() function to trigger RPA rotation and reset the RPA timeout right before advertising starts.

Bluetooth Security Manager Protocol (SMP)

The service selects the Kconfig options CONFIG_BT_SMP, CONFIG_BT_SMP_APP_PAIRING_ACCEPT, and CONFIG_BT_SMP_ENFORCE_MITM. The Fast Pair specification requires support for Bluetooth® Low Energy 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 the Kconfig options 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_IMGTOOL_SIGN_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

When using nRF53 Series devices, 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 the 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 allows a 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 the CONFIG_PM_SINGLE_IMAGE Kconfig option to enable the Partition Manager.

Settings

The GFPS uses Zephyr’s Settings to store Account Keys and the Personalized Name. Because of this, the GFPS selects the CONFIG_SETTINGS Kconfig option.

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 the bt_conn_auth_cb_overlay() function 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 the 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/fast_pair.h
Source files: subsys/bluetooth/services/fast_pair
group bt_fast_pair

Fast Pair API.

The Fast Pair subsystem needs the Bluetooth GATT operations to be run from the cooperative thread context. It requires proper configuration of the CONFIG_BT_RECV_CONTEXT Kconfig option.

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.

Values:

enumerator BT_FAST_PAIR_ADV_MODE_DISC

Fast Pair discoverable advertising.

enumerator BT_FAST_PAIR_ADV_MODE_NOT_DISC

Fast Pair not discoverable advertising.

enumerator BT_FAST_PAIR_ADV_MODE_COUNT

Number of Fast Pair advertising modes.

enum bt_fast_pair_not_disc_adv_type

Fast Pair not discoverable advertising type. Used to generate advertising packet.

Values:

enumerator BT_FAST_PAIR_NOT_DISC_ADV_TYPE_SHOW_UI_IND

Show UI indication.

enumerator BT_FAST_PAIR_NOT_DISC_ADV_TYPE_HIDE_UI_IND

Hide UI indication.

enumerator BT_FAST_PAIR_NOT_DISC_ADV_TYPE_COUNT

Number of Fast Pair not discoverable advertising types.

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 and is in possesion of at least one Account Key. 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

int bt_fast_pair_enable(void)

Enable Fast Pair.

This function shall only be used after calling the bt_enable and the settings_load functions. The Fast Pair operations require the enabled Bluetooth subsystem (see the bt_is_ready function) and the load operation of the settings subsystem.

This function must be called in the cooperative thread context.

Returns:

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

int bt_fast_pair_disable(void)

Disable Fast Pair.

This function can only be called if Fast Pair was previously enabled with the bt_fast_pair_enable API. After the device boot-up, Fast Pair is disabled.

This function must be called in the cooperative thread context.

Returns:

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

bool bt_fast_pair_is_ready(void)

Check if Fast Pair is ready.

Returns:

true when Fast Pair is ready, false otherwise.

size_t bt_fast_pair_adv_data_size(struct bt_fast_pair_adv_config fp_adv_config)

Get Fast Pair advertising data buffer size.

This function can only be called if Fast Pair was previously enabled with the bt_fast_pair_enable API.

This function must be called in the cooperative thread context.

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 must be called from context with cooperative priority.

This function can only be called if Fast Pair was previously enabled with the bt_fast_pair_enable API.

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 Fast Pair was not previously enabled with the bt_fast_pair_enable API.

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_info_cb_register(const struct bt_fast_pair_info_cb *cb)

Register Fast Pair information callbacks.

This function registers an instance of information callbacks. The registered instance needs to persist in the memory after this function exits, as it is used directly without the copy operation. It is possible to register only one instance of callbacks with this API.

This function can only be called before enabling Fast Pair with the bt_fast_pair_enable API.

This function must be called in the cooperative thread context.

Parameters:

  • cb – Callback struct.

Returns:

Zero on success or negative error code otherwise

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 initializing the Fast Pair storage when calling the bt_fast_pair_enable API. It prevents the Fast Pair storage from ending in unwanted state after the reset interruption.

This function must be called in the cooperative thread context.

Returns:

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

struct bt_fast_pair_disc_adv_info
#include <fast_pair.h>

Fast Pair discoverable advertising info. Currently empty.

struct bt_fast_pair_not_disc_adv_info
#include <fast_pair.h>

Fast Pair not discoverable advertising info.

Public Members

enum bt_fast_pair_not_disc_adv_type type

Advertising type. According to Fast Pair specification, when no Account Key has been saved on the device, this field has no effect on the advertising data.

enum bt_fast_pair_adv_battery_mode battery_mode

Fast Pair advertising battery mode. Battery values can be set using bt_fast_pair_battery_set.

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 mode

Fast Pair advertising mode.

struct bt_fast_pair_disc_adv_info disc

Fast Pair discoverable advertising info. Relevant if mode field set to BT_FAST_PAIR_ADV_MODE_DISC.

struct bt_fast_pair_not_disc_adv_info not_disc

Fast Pair not discoverable advertising info. Relevant if mode field set to BT_FAST_PAIR_ADV_MODE_NOT_DISC.

union bt_fast_pair_adv_config.[anonymous] [anonymous]

Fast Pair advertising info. Content depends on Fast Pair advertising mode (see mode field).

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.

struct bt_fast_pair_info_cb
#include <fast_pair.h>

Fast Pair information callback descriptor.

Public Members

void (*account_key_written)(struct bt_conn *conn)

Notify that the Account Key has been written.

This information can be used for example to update the Fast Pair advertising data in the not discoverable mode. Due to execution context constraints (Bluetooth RX thread), it is not recommended to block for long periods of time in this callback.

Param conn:

Connection object that wrote the Account Key.

Fast Pair UUID API

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

Fast Pair UUID API.

Defines

BT_FAST_PAIR_UUID_FPS_VAL

Fast Pair Service UUID value

BT_FAST_PAIR_UUID_FPS

Fast Pair Service UUID

BT_FAST_PAIR_UUID_MODEL_ID_VAL

Fast Pair Model ID Characteristic UUID value

BT_FAST_PAIR_UUID_MODEL_ID

Fast Pair Model ID Characteristic UUID

BT_FAST_PAIR_UUID_KEY_BASED_PAIRING_VAL

Fast Pair Key-based Pairing Characteristic UUID value

BT_FAST_PAIR_UUID_KEY_BASED_PAIRING

Fast Pair Key-based Pairing Characteristic UUID

BT_FAST_PAIR_UUID_PASSKEY_VAL

Fast Pair Passkey Characteristic UUID value

BT_FAST_PAIR_UUID_PASSKEY

Fast Pair Passkey Characteristic UUID

BT_FAST_PAIR_UUID_ACCOUNT_KEY_VAL

Fast Pair Account Key Characteristic UUID value

BT_FAST_PAIR_UUID_ACCOUNT_KEY

Fast Pair Account Key Characteristic UUID

BT_FAST_PAIR_UUID_ADDITIONAL_DATA_VAL

Fast Pair Additional Data Characteristic UUID value

BT_FAST_PAIR_UUID_ADDITIONAL_DATA

Fast Pair Additional Data Characteristic UUID