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:

Configuration

The Fast Pair Service is enabled with CONFIG_BT_FAST_PAIR Kconfig option set in the main application image.

Note

When building with sysbuild, value of the CONFIG_BT_FAST_PAIR Kconfig option is overwritten by SB_CONFIG_BT_FAST_PAIR. For more details about enabling Fast Pair for your application, see the Enabling Fast Pair in Kconfig section in the Fast Pair integration guide.

With the CONFIG_BT_FAST_PAIR Kconfig option enabled, the following Kconfig options are 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.

Note

If you use the FMDN extension, and your Provider is provisioned as an FMDN beacon, do not use the bt_le_oob_get_local() function. For more details, see the Setting up Bluetooth LE advertising section of the Fast Pair integration guide.

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 selected Fast Pair use cases (for example, the input device use case).

For this reason, the relevant use case Kconfig options (for example, the CONFIG_BT_FAST_PAIR_USE_CASE_INPUT_DEVICE Kconfig option) select the CONFIG_BT_DIS and CONFIG_BT_DIS_FW_REV Kconfig options. If the target project uses Zephyr’s application version management, the default value of the CONFIG_BT_DIS_FW_REV_STR Kconfig option is set according to the versioning information found in the VERSION file. 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. With the FMDN extension enabled, it additionally stores the Owner Account Key, the EIK and the Beacon Clock. Because of this, the GFPS selects the CONFIG_SETTINGS Kconfig option.

Bluetooth LE extended advertising for the FMDN extension

The FMDN extension (see CONFIG_BT_FAST_PAIR_FMDN) selects the CONFIG_BT_EXT_ADV Kconfig option. The extension uses the Bluetooth LE Extended Advertising Zephyr API to support simultaneous broadcast of multiple advertising sets. In the simplest scenario, you should have the following two advertising sets in your application:

  • The application-specific advertising set with the Fast Pair payload.

  • The FMDN advertising set for the FMDN extension.

For more details regarding the advertising policy of the FMDN extension, see the Setting up Bluetooth LE advertising section of the Fast Pair integration guide.

DULT module for the FMDN extension

The CONFIG_BT_FAST_PAIR_FMDN_DULT of the FMDN extension selects the CONFIG_DULT Kconfig option to enable the DULT module. The FMDN extension implementation also acts as middleware between the user application and the DULT module. The DULT module integration is required for small and not easily discoverable accessories. The CONFIG_BT_FAST_PAIR_FMDN_DULT is enabled by default.

The CONFIG_BT_FAST_PAIR_FMDN_BATTERY_DULT of the FMDN extension selects the CONFIG_DULT_BATTERY Kconfig option to enable the battery support in the DULT module. With this option enabled, the FMDN extension passes the battery information also to the DULT module.

For more details on the DULT module, see the Detecting Unwanted Location Trackers (DULT) module documentation.

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 requests received from the Fast Pair Seeker except for operations on the Beacon Actions characteristic that is part of the FMDN extension. For more details, see the Setting up GATT service section of the Fast Pair integration guide.

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).

Used only when the CONFIG_BT_FAST_PAIR_BN Kconfig option is enabled.

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. Used only when the CONFIG_BT_FAST_PAIR_SUBSEQUENT_PAIRING is enabled.

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.

Used only when the CONFIG_BT_FAST_PAIR_BN Kconfig option is enabled.

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 possession 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.

Used only when the CONFIG_BT_FAST_PAIR_BN Kconfig option is enabled.

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.

Mandatory callbacks must be registered before the user enables the Fast Pair module with this API. The mandatory callback set may depend on the chosen Fast Pair extension set that is selected in the application Kconfig configuration. The enable API fails with an error if mandatory callbacks are not registered. An example of a mandatory callback is the bt_fast_pair_fmdn_ring_cb structure defined in the API header of the Find My Device Network extension when this extension is configured to support ringing operations. The Fast Pair module configuration without any extensions does not require any mandatory callbacks.

If the application uses non-mandatory callbacks, like the bt_fast_pair_fmdn_ring_cb structure, these callbacks must also be registered before the bt_fast_pair_enable API call.

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.

This function can only be used only when the CONFIG_BT_FAST_PAIR_BN Kconfig option is enabled.

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.

If the Find My Network Device extension is enabled, this function can only be called in the disabled state of the Fast Pair module (see the bt_fast_pair_is_ready function).

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.

This field is used only when the CONFIG_BT_FAST_PAIR_BN Kconfig option is enabled. Otherwise, it should be set to BT_FAST_PAIR_ADV_BATTERY_MODE_NONE or zero.

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.

Used only when the CONFIG_BT_FAST_PAIR_BN Kconfig option is enabled.

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.

FMDN extension

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

Fast Pair FMDN API.

It is required to use the Fast Pair FMDN API in the cooperative thread context (for example, system workqueue thread). Following this requirement guarantees a proper synchronization between the user operations and the module operations.

Defines

BT_FAST_PAIR_FMDN_RING_COMP_BM_NONE

Ringing component bitmask with no active component (typically used to stop the ongoing ringing action).

BT_FAST_PAIR_FMDN_RING_COMP_BM_ALL

Special value of the ringing component bitmask to request ringing from all available components on the device. This value can only appear in the callback request and cannot be used in the application response passed to the bt_fast_pair_fmdn_ring_state_update API.

BT_FAST_PAIR_FMDN_RING_MSEC_PER_DSEC

Number of milliseconds per decisecond.

BT_FAST_PAIR_FMDN_RING_TIMEOUT_DS_TO_MS(_timeout_ds)

Convert the ringing timeout value from deciseconds to milliseconds.

Deciseconds are the native time unit used by the FMDN extension.

Parameters:

  • _timeout_ds – The ringing timeout value in deciseconds.

BT_FAST_PAIR_FMDN_RING_TIMEOUT_MS_TO_DS(_timeout_ms)

Convert the ringing timeout value from milliseconds to deciseconds.

Deciseconds are the native time unit used by the FMDN extension.

Parameters:

  • _timeout_ms – The ringing timeout value in milliseconds.

BT_FAST_PAIR_FMDN_BATTERY_LEVEL_NONE

Unknown battery level.

BT_FAST_PAIR_FMDN_ADV_PARAM_INIT(_int_min, _int_max)

Helper to declare FMDN advertising parameters inline.

Parameters:

  • _int_min – Minimum advertising interval.

  • _int_max – Maximum advertising interval.

BT_FAST_PAIR_FMDN_ADV_PARAM_DEFAULT

Default value of FMDN advertising parameters.

Enums

enum bt_fast_pair_fmdn_ring_src

Ringing activity source types.

Values:

enumerator BT_FAST_PAIR_FMDN_RING_SRC_FMDN_BT_GATT

Ringing source type originating from the Bluetooth Fast Pair service that is defined in the FMDN Accessory specification (Beacon Actions operations).

enumerator BT_FAST_PAIR_FMDN_RING_SRC_DULT_BT_GATT

Ringing source type originating from the Bluetooth accessory non-owner service that is defined in the DULT specification. Used only when the CONFIG_BT_FAST_PAIR_FMDN_DULT is enabled.

enumerator BT_FAST_PAIR_FMDN_RING_SRC_DULT_MOTION_DETECTOR

Ringing source type originating from the Motion detector defined in the DULT specification. Used only when the CONFIG_BT_FAST_PAIR_FMDN_DULT_MOTION_DETECTOR is enabled.

enum bt_fast_pair_fmdn_ring_comp

Ringing component identifiers.

Values:

enumerator BT_FAST_PAIR_FMDN_RING_COMP_RIGHT

Identifier of the right component.

enumerator BT_FAST_PAIR_FMDN_RING_COMP_LEFT

Identifier of the left component.

enumerator BT_FAST_PAIR_FMDN_RING_COMP_CASE

Identifier of the case component.

enum bt_fast_pair_fmdn_ring_volume

Ringing volume.

Values:

enumerator BT_FAST_PAIR_FMDN_RING_VOLUME_DEFAULT

Default level of the ringing volume.

enumerator BT_FAST_PAIR_FMDN_RING_VOLUME_LOW

Low level of the ringing volume.

enumerator BT_FAST_PAIR_FMDN_RING_VOLUME_MEDIUM

Medium level of the ringing volume.

enumerator BT_FAST_PAIR_FMDN_RING_VOLUME_HIGH

High level of the ringing volume.

enum bt_fast_pair_fmdn_ring_trigger

Trigger for the new ringing state.

Values:

enumerator BT_FAST_PAIR_FMDN_RING_TRIGGER_STARTED

Ringing action started.

enumerator BT_FAST_PAIR_FMDN_RING_TRIGGER_FAILED

Ringing action failed (all requested components are out of range).

enumerator BT_FAST_PAIR_FMDN_RING_TRIGGER_TIMEOUT_STOPPED

Ringing action stopped due to the timeout.

enumerator BT_FAST_PAIR_FMDN_RING_TRIGGER_UI_STOPPED

Ringing action stopped due to the UI action (e.g button press, touch sense).

enumerator BT_FAST_PAIR_FMDN_RING_TRIGGER_GATT_STOPPED

Ringing action stopped due to the GATT request.

enum bt_fast_pair_fmdn_read_mode

Read modes.

Values:

enumerator BT_FAST_PAIR_FMDN_READ_MODE_FMDN_RECOVERY

EIK recovery read mode.

enumerator BT_FAST_PAIR_FMDN_READ_MODE_DULT_ID

Identification read mode. Used only when the CONFIG_BT_FAST_PAIR_FMDN_DULT is enabled.

Functions

int bt_fast_pair_fmdn_ring_cb_register(const struct bt_fast_pair_fmdn_ring_cb *cb)

Register the ringing callbacks in the FMDN module.

This function registers the ringing callbacks. If you declare at least one ringing component using the CONFIG_BT_FAST_PAIR_FMDN_RING_COMP Kconfig choice option, you shall call this API before you enable Fast Pair with the bt_fast_pair_enable function. Otherwise, the enable operation fails.

You can call this function only in the disabled state of the FMDN module (see bt_fast_pair_is_ready function).

Parameters:

  • cb – Ringing callback structure.

Returns:

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

int bt_fast_pair_fmdn_ring_state_update(enum bt_fast_pair_fmdn_ring_src src, const struct bt_fast_pair_fmdn_ring_state_param *param)

Update the ringing state in the FMDN module.

This function updates the ringing state in the FMDN module and notifies connected peers about the change. The application user is responsible for setting the correct state that reflects the actual state of their ringing components.

You shall use this API to respond to the callbacks defined by the bt_fast_pair_fmdn_ring_cb structure. It is also possible to use this function to change the ringing state asynchronously. For example, you shall call this API when the user stops the ringing action manually (see the BT_FAST_PAIR_FMDN_RING_TRIGGER_UI_STOPPED trigger). In other cases, you may need to update the ringing state asynchronously to recover from the failure. For example, you can indicate the state change once you stop the ringing action on a previously unavailable component.

Parameters:

  • src – Source of the ringing activity that triggered state update.

  • param – Ringing state parameters. See the bt_fast_pair_fmdn_ring_state_param for the detailed description.

Returns:

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

int bt_fast_pair_fmdn_motion_detector_cb_register(const struct bt_fast_pair_fmdn_motion_detector_cb *cb)

Register motion detector callbacks.

This function registers callbacks to handle motion detector activities defined in the Motion detector feature from the DULT specification. This API can only be used when the CONFIG_BT_FAST_PAIR_FMDN_DULT_MOTION_DETECTOR Kconfig option is enabled. If this configuration is active, this function must be called before you enable Fast Pair with the bt_fast_pair_enable function. Otherwise, the enable operation fails.

You can call this function only in the disabled state of the FMDN module (see bt_fast_pair_is_ready function).

Parameters:

  • cb – Motion detector callback structure.

Returns:

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

int bt_fast_pair_fmdn_battery_level_set(uint8_t percentage_level)

Set the current battery level.

This function sets the current battery level. It is recommended to initialize the battery level with this API before you enable Fast Pair with the bt_fast_pair_enable API.

By default, the BT_FAST_PAIR_FMDN_BATTERY_LEVEL_NONE value is used, which means that battery levels do not show in the advertising payload. If you do not want to support the battery level indication, you should ignore this API and never call it in their application.

However, if the CONFIG_BT_FAST_PAIR_FMDN_BATTERY_DULT Kconfig is enabled, you must initialize battery level with this API before you enable Fast Pair with the bt_fast_pair_enable API. 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_FMDN_BATTERY_LEVEL_NONE value in this configuration variant.

To keep the Android battery level indications accurate, you should set the battery level to the new value with the help of this API as soon as the device battery level changes.

The exact mapping of the battery percentage to the battery level as defined by the FMDN Accessory specification in the advertising payload is implementation-specific. The mapping configuration is controlled by the following Kconfig options: CONFIG_BT_FAST_PAIR_FMDN_BATTERY_LEVEL_LOW_THR and CONFIG_BT_FAST_PAIR_FMDN_BATTERY_LEVEL_CRITICAL_THR .

Parameters:
Returns:

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

int bt_fast_pair_fmdn_adv_param_set(const struct bt_fast_pair_fmdn_adv_param *adv_param)

Set the FMDN advertising parameters.

This function sets the advertising parameters. It is recommended to initialize the advertising parameters with this API before you enable Fast Pair with the bt_fast_pair_enable API. Otherwise, the default value BT_FAST_PAIR_FMDN_ADV_PARAM_DEFAULT is used for advertising.

In the Fast Pair disabled state, advertising parameters are accepted without any validation but are subsequently validated during the bt_fast_pair_enable API call.

You can use this function to dynamically update advertising parameters during an ongoing FMDN advertising.

The API user is responsible for adjusting this configuration to their application requirements. The advertising intervals parameters from this API have additional constraints when you enable the Fast Pair advertising together with FMDN advertising (see respective specifications for details). This function does not validate if these constraints are met.

Parameters:
Returns:

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

int bt_fast_pair_fmdn_id_set(uint8_t id)

Set the Bluetooth identity for the FMDN extension.

This function sets the Bluetooth identity for the FMDN extension. This identity shall be created with the bt_id_create function that is available in the Bluetooth API. You can change the identity with this API only in the disabled state of the Fast Pair module before you enable it with the bt_fast_pair_enable API. If you do not explicitly set the identity with this API call, the default identity, BT_ID_DEFAULT, is used.

Parameters:

  • id – Bluetooth identity for the FMDN extension.

Returns:

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

int bt_fast_pair_fmdn_info_cb_register(struct bt_fast_pair_fmdn_info_cb *cb)

Register the information callbacks in the FMDN module.

This function registers the information callbacks. You can call this function only in the disabled state of the FMDN module (see bt_fast_pair_is_ready function). This API for callback registration is optional and does not have to be used. You can register multiple instances of information callbacks.

Parameters:

  • cb – Information callback structure.

Returns:

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

int bt_fast_pair_fmdn_read_mode_cb_register(const struct bt_fast_pair_fmdn_read_mode_cb *cb)

Register the read mode callbacks in the FMDN module.

This function registers the read mode callbacks.

You can call this function only in the disabled state of the FMDN module (see bt_fast_pair_is_ready function).

Parameters:

  • cb – Read mode callback structure.

Returns:

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

int bt_fast_pair_fmdn_read_mode_enter(enum bt_fast_pair_fmdn_read_mode mode)

Enter read mode.

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

Parameters:

  • mode – Read mode.

Returns:

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

struct bt_fast_pair_fmdn_ring_req_param
#include <fmdn.h>

Ringing request parameters.

Public Members

uint8_t active_comp_bm

Bitmask with the active ringing components that is composed of the bt_fast_pair_fmdn_ring_comp identifiers.

uint16_t timeout

Ringing timeout in deciseconds.

enum bt_fast_pair_fmdn_ring_volume volume

Ringing volume using bt_fast_pair_fmdn_ring_volume values.

struct bt_fast_pair_fmdn_ring_cb
#include <fmdn.h>

Ringing callback structure.

Public Members

void (*start_request)(enum bt_fast_pair_fmdn_ring_src src, const struct bt_fast_pair_fmdn_ring_req_param *param)

Request the user to start the ringing action.

This callback is called to start the ringing action. The FMDN module requests this action in response to the command from the connected peer. Eventually, the action times out, which is indicated by the timeout_expired callback. This action can also be cancelled by the connected peer (see the stop_request callback) or stopped manually by the user action (see the bt_fast_pair_fmdn_ring_state_update API and the BT_FAST_PAIR_FMDN_RING_TRIGGER_UI_STOPPED trigger).

The input parameters determine how the ringing actions should be executed. See bt_fast_pair_fmdn_ring_req_param for more details.

If the action is accepted for at least one requested component, you shall indicate it using the bt_fast_pair_fmdn_ring_state_update API and set the BT_FAST_PAIR_FMDN_RING_TRIGGER_STARTED as a trigger for the ringing state change. If all components are out of range, you shall set the BT_FAST_PAIR_FMDN_RING_TRIGGER_FAILED as a trigger.

This callback can be called again when the ringing action has already started. In this case, you shall update the ringing activity to match the newest set of parameters.

If you cannot start the ringing action on all requested components (for example, one of them is out of range), you shall still declare success for this request. Once an unavailable component becomes reachable, you can start the ringing action on it and indicate it using the bt_fast_pair_fmdn_ring_state_update API.

This callback is executed in the cooperative thread context. You can learn about the exact thread context by analyzing the CONFIG_BT_RECV_CONTEXT configuration choice. By default, this callback is executed in the Bluetooth-specific workqueue thread ( CONFIG_BT_RECV_WORKQ_BT ).

Param src:

Source of the ringing activity.

Param param:

Requested ringing parameters.

void (*timeout_expired)(enum bt_fast_pair_fmdn_ring_src src)

Request the user to stop the ringing action on timeout.

This callback is called to stop the ongoing ringing action. The FMDN module requests this action when the ringing timeout expires.

If the action is accepted for at least one requested component, you shall indicate it using the bt_fast_pair_fmdn_ring_state_update API and set the BT_FAST_PAIR_FMDN_RING_TRIGGER_TIMEOUT_STOPPED as a trigger for the ringing state change. If all components are out of range, you shall set the BT_FAST_PAIR_FMDN_RING_TRIGGER_FAILED as a trigger.

This callback is called when at least one ringing component is active. The timeout is not stopped unless the API user reports that ringing is stopped for all of the components.

If you cannot stop the ringing action on all requested components (for example, one of them is out of range), you shall still declare success for this request. Once an unavailable component becomes reachable, you can stop the ringing action on it and indicate it using the bt_fast_pair_fmdn_ring_state_update API.

This callback is executed in the cooperative thread context - in the system workqueue thread.

Param src:

Source of the ringing activity.

void (*stop_request)(enum bt_fast_pair_fmdn_ring_src src)

Request the user to stop the ringing action on GATT request.

This callback is called to stop the ongoing ringing action. The FMDN module requests this action in response to the command from the connected peer.

If the action is accepted for at least one requested component, you shall indicate it using the bt_fast_pair_fmdn_ring_state_update API and set the BT_FAST_PAIR_FMDN_RING_TRIGGER_GATT_STOPPED as a trigger for the ringing state change. If all components are out of range, you shall set the BT_FAST_PAIR_FMDN_RING_TRIGGER_FAILED as a trigger.

If you cannot stop the ringing action on all requested components (for example, one of them is out of range), you shall still declare success for this request. Once an unavailable component becomes reachable, you can stop the ringing action on it and indicate it using the bt_fast_pair_fmdn_ring_state_update API.

This callback is executed in the cooperative thread context. You can learn about the exact thread context by analyzing the CONFIG_BT_RECV_CONTEXT configuration choice. By default, this callback is executed in the Bluetooth-specific workqueue thread ( CONFIG_BT_RECV_WORKQ_BT ).

Param src:

Source of the ringing activity.

struct bt_fast_pair_fmdn_ring_state_param
#include <fmdn.h>

Ringing state parameters.

Public Members

enum bt_fast_pair_fmdn_ring_trigger trigger

Trigger for the new ringing state.

uint8_t active_comp_bm

Bitmask with the active ringing components that is composed of the bt_fast_pair_fmdn_ring_comp identifiers.

uint16_t timeout

Ringing timeout in deciseconds. Relevant only for the BT_FAST_PAIR_FMDN_RING_TRIGGER_STARTED trigger Set to zero to preserve the existing timeout.

struct bt_fast_pair_fmdn_motion_detector_cb
#include <fmdn.h>

Motion detector callback structure.

Used only if the CONFIG_BT_FAST_PAIR_FMDN_DULT_MOTION_DETECTOR Kconfig option is enabled.

Public Members

void (*start)(void)

Request the user to start the motion detector.

This callback is called to start the motion detector activity. From now on, the motion detector events are polled periodically with the period_expired API. The motion detector activity stops when the stop is called.

bool (*period_expired)(void)

Notify the user that the motion detector period has expired.

This callback is called at the end of each motion detector period. The start function indicates the beginning of the first motion detector period. The next period is started as soon as the previous period expires. The user should notify the FMDN module if motion was detected in the previous period. The return value of this callback is used to pass this information.

Return:

true to indicate detected motion in the last period, otherwise false.

void (*stop)(void)

Notify the user that the motion detector can be stopped.

This callback is called to notify the user that the motion detector is no longer used by the FMDN module. It concludes the motion detector activity that was started by the start callback.

struct bt_fast_pair_fmdn_adv_param
#include <fmdn.h>

FMDN advertising parameters.

Public Members

uint32_t interval_min

Minimum Advertising Interval (N * 0.625 milliseconds). Range: 0x0020 to 0x4000.

uint32_t interval_max

Maximum Advertising Interval (N * 0.625 milliseconds). Range: 0x0020 to 0x4000.

struct bt_fast_pair_fmdn_info_cb
#include <fmdn.h>

Information callback structure.

Public Members

void (*clock_synced)(void)

Indicate that the peer was notified about the clock value.

This callback is called to indicate that the authenticated peer was notified about the accessory clock. It can be used to signal the synchronization point between the devices. After this callback, it may no longer be necessary to use the Fast Pair not discoverable advertising as a mechanism to synchronize devices after a long clock drift.

This callback is executed in the cooperative thread context. You can learn about the exact thread context by analyzing the CONFIG_BT_RECV_CONTEXT configuration choice. By default, this callback is executed in the Bluetooth-specific workqueue thread ( CONFIG_BT_RECV_WORKQ_BT ).

void (*provisioning_state_changed)(bool provisioned)

Indicate provisioning state changes.

This callback is called to indicate that the FMDN accessory has been successfully provisioned or unprovisioned.

This callback also reports the initial provisioning state when the user enables Fast Pair with the bt_fast_pair_enable API.

The first callback is executed in the workqueue context after the bt_fast_pair_enable function call. Subsequent callbacks are also executed in the cooperative thread context. You can learn about the exact thread context by analyzing the CONFIG_BT_RECV_CONTEXT configuration choice. By default, this callback is executed in the Bluetooth-specific workqueue thread ( CONFIG_BT_RECV_WORKQ_BT ).

Param provisioned:

true if the accessory has been successfully provisioned. false if the accessory has been successfully unprovisioned.

sys_snode_t node

Internally used field for list handling.

struct bt_fast_pair_fmdn_read_mode_cb
#include <fmdn.h>

Read mode callback structure.

Public Members

void (*exited)(enum bt_fast_pair_fmdn_read_mode mode)

Read mode exited.

This callback is called to indicate that the read mode has been exited. Read mode can be entered by calling the bt_fast_pair_fmdn_read_mode_enter API.

Param mode:

Read mode.

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.

BT_FAST_PAIR_UUID_BEACON_ACTIONS_VAL

Fast Pair Beacon Actions Characteristic UUID value (used in the FMDN extension).

BT_FAST_PAIR_UUID_BEACON_ACTIONS

Fast Pair Beacon Actions Characteristic UUID (used in the FMDN extension).