From aea10eac7e74875ff1fe1f92007f9fa34d7efbff Mon Sep 17 00:00:00 2001 From: Kamil Piszczek Date: Mon, 24 Mar 2025 12:33:58 +0100 Subject: [PATCH 1/4] doc: external_comp: fast_pair: doc bt_fast_pair_fmdn_is_provisioned API Updated the Fast Pair integration guide to document changes in the FMDN APIs that are used to track the provisioning state. The callback API - bt_fast_pair_fmdn_info_cb.provisioning_state_changed - has been changed and no longer reports the initial provisioning state after the Fast Pair subsystem is enabled with the bt_fast_pair_enable API. Added the new FMDN API - bt_fast_pair_fmdn_is_provisioned. The API can be used to check the device provisioning state synchronously. Ref: NCSDK-30856 Signed-off-by: Kamil Piszczek --- doc/nrf/external_comp/bt_fast_pair.rst | 21 ++++++++++++++----- .../releases/release-notes-changelog.rst | 1 + 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/doc/nrf/external_comp/bt_fast_pair.rst b/doc/nrf/external_comp/bt_fast_pair.rst index d0e892035ce..21048ae00aa 100644 --- a/doc/nrf/external_comp/bt_fast_pair.rst +++ b/doc/nrf/external_comp/bt_fast_pair.rst @@ -545,7 +545,8 @@ When creating the Fast Pair advertising set with the :c:func:`bt_le_ext_adv_crea * For the unprovisioned device, control the Fast Pair advertising rotation time using the :c:func:`bt_le_set_rpa_timeout` and :c:func:`bt_le_oob_get_local` functions. You must still comply with the requirements of the Fast Pair protocol. - The provisioning state is indicated by the :c:member:`bt_fast_pair_fmdn_info_cb.provisioning_state_changed` callback. + The :c:func:`bt_fast_pair_fmdn_is_provisioned` function can be used to check the current FMDN provisioning state synchronously. + Also, the provisioning state changes are indicated by the :c:member:`bt_fast_pair_fmdn_info_cb.provisioning_state_changed` callback. See :ref:`ug_bt_fast_pair_gatt_service_fmdn_info_callbacks` for more details. See the :ref:`fast_pair_locator_tag` sample that demonstrates how to comply with the rules described in this section. @@ -763,17 +764,27 @@ This function supports the following callbacks: * :c:member:`bt_fast_pair_fmdn_info_cb.clock_synced` - Notification about the beacon clock synchronization event * :c:member:`bt_fast_pair_fmdn_info_cb.conn_authenticated` - Notification about the connected peer authentication event +.. _ug_bt_fast_pair_gatt_service_fmdn_info_callbacks_provisioning_state: + Provisioning state ~~~~~~~~~~~~~~~~~~ -The provisioning state is indicated by the :c:member:`bt_fast_pair_fmdn_info_cb.provisioning_state_changed` callback. +The :c:func:`bt_fast_pair_fmdn_is_provisioned` function can be used to check the current FMDN provisioning state synchronously. +You can only call this function in the ready state of the Fast Pair module (see the :c:func:`bt_fast_pair_is_ready` function). + +The provisioning state changes are indicated by the :c:member:`bt_fast_pair_fmdn_info_cb.provisioning_state_changed` callback. This callback is triggered in the following scenarios: -* Right after the :c:func:`bt_fast_pair_enable` enable operation to indicate the initial provisioning state of the extension. * On the successful provisioning operation over Beacon Actions characteristic. * On the successful unprovisioning operation over Beacon Actions characteristic. -The provisioning state callback is used to notify the application about switching to a proper advertising policy. +The :c:func:`bt_fast_pair_fmdn_is_provisioned` function and the :c:member:`bt_fast_pair_fmdn_info_cb.provisioning_state_changed` callback are two complementary API elements that can be used to track the FMDN provisioning state in your application code. +The recommended usage scenario is described in the next paragraph. + +Use the :c:func:`bt_fast_pair_fmdn_is_provisioned` function to initialize the provisioning state right after enabling the Fast Pair module with the :c:func:`bt_fast_pair_enable` function call. +Then, handle the :c:member:`bt_fast_pair_fmdn_info_cb.provisioning_state_changed` callback to track the provisioning state changes until the Fast Pair module is disabled again with the :c:func:`bt_fast_pair_disable` function call. + +The accurate tracking of the FMDN provisioning state is mandatory for proper management of the Fast Pair and FMDN advertising policies. The advertising policies are extensively described in the :ref:`Setting up Bluetooth LE advertising ` section of this integration guide. Clock synchronization @@ -822,7 +833,7 @@ The FMDN extension defines special read modes, in which sensitive data can be re The read mode persists only for limited time after which it is deactivated. To enter the chosen read mode, you must call the :c:func:`bt_fast_pair_fmdn_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 :c:func:`bt_fast_pair_is_ready` function) and in the FMDN provisioned state (see the :c:member:`bt_fast_pair_fmdn_info_cb.provisioning_state_changed` callback). +You can only call this function in the ready state of the Fast Pair module (see the :c:func:`bt_fast_pair_is_ready` function) and in the FMDN provisioned state (see the :c:func:`bt_fast_pair_fmdn_is_provisioned` function). The FMDN extension supports the following read mode types: * :c:enum:`BT_FAST_PAIR_FMDN_READ_MODE_FMDN_RECOVERY` - Ephemeral Identity Key (EIK) recovery mode diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index 5ff3bc42a69..e6688bfedd7 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst @@ -962,6 +962,7 @@ Google Fast Pair integration * The :ref:`ug_bt_fast_pair_provisioning_register_hex_generation` section that describes how to generate the hex file with the Fast Pair provisioning data. * The :ref:`ug_bt_fast_pair_prerequisite_ops_kconfig` section to align it with recent changes in the sysbuild configuration for Fast Pair. + * The :ref:`ug_bt_fast_pair_gatt_service_fmdn_info_callbacks_provisioning_state` section with changes to the FMDN API elements that are used for tracking of the FMDN provisioning state. Edge Impulse integration ------------------------ From f6302c4e5d730d4a9bddd943c645ba427ca73dfc Mon Sep 17 00:00:00 2001 From: Kamil Piszczek Date: Mon, 24 Mar 2025 13:11:42 +0100 Subject: [PATCH 2/4] doc: migration guide v3.0: add steps to align with Fast Pair FMDN change Added new content to the NCS v3.0 migration guide. The new documentation describes how to align your Fast Pair application with support for the Find My Device Network (FMDN) extension with the recent changes to the FMDN API elements that are used to track the FMDN provisioning state. Ref: NCSDK-30856 Signed-off-by: Kamil Piszczek --- .../releases_and_maturity/migration/migration_guide_3.0.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/nrf/releases_and_maturity/migration/migration_guide_3.0.rst b/doc/nrf/releases_and_maturity/migration/migration_guide_3.0.rst index 121d82d8d6c..67f0e4ba169 100644 --- a/doc/nrf/releases_and_maturity/migration/migration_guide_3.0.rst +++ b/doc/nrf/releases_and_maturity/migration/migration_guide_3.0.rst @@ -91,6 +91,11 @@ Google Fast Pair The ``SB_CONFIG_BT_FAST_PAIR`` option no longer exists in this |NCS| release. Additionally, if you rely on the ``SB_CONFIG_BT_FAST_PAIR`` Kconfig option to set the :kconfig:option:`CONFIG_BT_FAST_PAIR` Kconfig option in the main image configuration of your application, you must align your main image configuration and set the :kconfig:option:`CONFIG_BT_FAST_PAIR` Kconfig option explicitly. + * If your Fast Pair application uses the Find My Device (FMD) extension, you must update your application code to correctly track the FMDN provisioning state. + From this |NCS| release, you must not rely on the :c:member:`bt_fast_pair_fmdn_info_cb.provisioning_state_changed` callback to report the initial provisioning state right after the Fast Pair module is enabled with the :c:func:`bt_fast_pair_enable` function call. + Instead, you must use the :c:func:`bt_fast_pair_fmdn_is_provisioned` function to initialize the FMDN provisioning state right after the :c:func:`bt_fast_pair_enable` function call. + For more details, see the :ref:`ug_bt_fast_pair_gatt_service_fmdn_info_callbacks_provisioning_state` section in the Fast Pair integration guide. + nRF Cloud library ----------------- From 357309fb95247b7474f72008fc8ae7c6ddafaf74 Mon Sep 17 00:00:00 2001 From: Kamil Piszczek Date: Mon, 24 Mar 2025 13:53:42 +0100 Subject: [PATCH 3/4] doc: changelog: fast_pair: add items related to the FMDN API changes Updated the release changelog to describe the changes to the FMDN API elements that are used to track the Find My Device Network (FMDN) provisioning state. Described the addition of the new FMDN API: bt_fast_pair_fmdn_is_provisioned. The API can be used to check the device provisioning state synchronously. Described the change in the behavior of the bt_fast_pair_fmdn_info_cb.provisioning_state_changed callback. The callback no longer reports the initial provisioning state after the Fast Pair subsystem is enabled with the bt_fast_pair_enable API. Ref: NCSDK-30856 Signed-off-by: Kamil Piszczek --- .../releases/release-notes-changelog.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index e6688bfedd7..5ab17247a95 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst @@ -738,6 +738,9 @@ Bluetooth libraries and services For further details on the Android intent feature for firmware updates, see the :ref:`ug_bt_fast_pair_provisioning_register_firmware_update_intent` section in the Fast Pair integration guide. * A workaround for the issue where the FMDN clock value might not be correctly set after the system reboot for nRF54L Series devices. For details, see the ``NCSDK-32268`` issue in the :ref:`known_issues` page. + * A new function :c:func:`bt_fast_pair_fmdn_is_provisioned` for the FMDN extension API. + This function can be used to synchronously check the current FMDN provisioning state. + For more details, see the :ref:`ug_bt_fast_pair_gatt_service_fmdn_info_callbacks_provisioning_state` section in the Fast Pair integration guide. * Updated: @@ -746,6 +749,9 @@ Bluetooth libraries and services * The method of supplying the Fast Pair Model ID and Anti-Spoofing Private Key to generate the Fast Pair provisioning data HEX file. The ``FP_MODEL_ID`` and ``FP_ANTI_SPOOFING_KEY`` CMake variables are replaced by the corresponding ``SB_CONFIG_BT_FAST_PAIR_MODEL_ID`` and ``SB_CONFIG_BT_FAST_PAIR_ANTI_SPOOFING_PRIVATE_KEY`` Kconfig options. * The automatically generated ``bt_fast_pair`` partition definition (in the :file:`subsys/partition_manager/pm.yml.bt_fast_pair` file) to work correctly when building with TF-M. + * The behavior of the :c:member:`bt_fast_pair_fmdn_info_cb.provisioning_state_changed` callback. + The callback no longer reports the initial provisioning state after the Fast Pair subsystem is enabled with the :c:func:`bt_fast_pair_enable` function call. + See the :ref:`migration guide ` for mandatory changes and the :ref:`ug_bt_fast_pair_gatt_service_fmdn_info_callbacks_provisioning_state` section in the Fast Pair integration guide for the description on how to track the FMDN provisioning state with the new approach. * Removed the sysbuild control over the :kconfig:option:`CONFIG_BT_FAST_PAIR` Kconfig option that is defined in the main (default) image. Sysbuild no longer sets the value of this Kconfig option. From c56a744aeb130b9716e6e0aff8d8cd84c3cb5343 Mon Sep 17 00:00:00 2001 From: Kamil Piszczek Date: Mon, 24 Mar 2025 13:58:08 +0100 Subject: [PATCH 4/4] doc: changelog: fast_pair: merge duplicated Fast Pair library section Updated the release changelog to remove the duplicated sections for the Fast Pair library changelog. Signed-off-by: Kamil Piszczek --- .../releases/release-notes-changelog.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index 5ab17247a95..fa0144ba2a1 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst @@ -744,6 +744,7 @@ Bluetooth libraries and services * Updated: + * The :c:func:`bt_fast_pair_info_cb_register` API to allow registration of multiple callbacks. * The Fast Pair sysbuild Kconfig options. The ``SB_CONFIG_BT_FAST_PAIR`` Kconfig option is replaced with the ``SB_CONFIG_BT_FAST_PAIR_MODEL_ID`` and ``SB_CONFIG_BT_FAST_PAIR_ANTI_SPOOFING_PRIVATE_KEY``. * The method of supplying the Fast Pair Model ID and Anti-Spoofing Private Key to generate the Fast Pair provisioning data HEX file. @@ -760,11 +761,6 @@ Bluetooth libraries and services * Fixed an issue in the :ref:`bt_mesh_light_ctrl_srv_readme` model to automatically resume the Lightness Controller after recalling a scene (``NCSDK-30033`` known issue). - -* :ref:`bt_fast_pair_readme` library: - - * Updated the :c:func:`bt_fast_pair_info_cb_register` API to allow registration of multiple callbacks. - Common Application Framework ----------------------------