Fast Pair: FMDN provisioning state APIs: documentation update

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 <ug_bt_fast_pair_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

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

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -738,14 +738,21 @@ 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:
 
+    * 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.
       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 <migration_3.0_recommended>` 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.
@@ -754,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
 ----------------------------
 
@@ -962,6 +964,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
 ------------------------