doc: Document DULT motion detector feature

Jira: NCSDK-28984

Signed-off-by: Aleksander Strzebonski <[email protected]>

doc/nrf/external_comp/bt_fast_pair.rst

@@ -284,6 +284,7 @@ You can use the following API functions only in the *unready* state of the FMDN
   * The :c:func:`bt_fast_pair_fmdn_info_cb_register` function (optional)
   * The :c:func:`bt_fast_pair_fmdn_ring_cb_register` function (mandatory with the Kconfig configuration for at least one ringing component)
   * The :c:func:`bt_fast_pair_fmdn_read_mode_cb_register` function (optional)
+  * The :c:func:`bt_fast_pair_fmdn_motion_detector_cb_register` function (mandatory if the :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT_MOTION_DETECTOR` Kconfig option is enabled)
 
 * The :c:func:`bt_fast_pair_fmdn_id_set` API function used for assigning Bluetooth identity to FMDN activities (like advertising and connections)
 * The :c:func:`bt_fast_pair_factory_reset` API function used for performing factory reset of all Fast Pair data
@@ -768,6 +769,8 @@ The following sources of ringing activity are supported:
 * :c:enum:`BT_FAST_PAIR_FMDN_RING_SRC_FMDN_BT_GATT` - This ringing source originates from the Bluetooth Fast Pair service and its Beacon Actions characteristic that is defined in the FMDN Accessory specification.
 * :c:enum:`BT_FAST_PAIR_FMDN_RING_SRC_DULT_BT_GATT` - This ringing source originates from the Bluetooth Accessory Non-owner service and its characteristic that are defined in the DULT specification.
   This source is available only when the :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT` Kconfig option is enabled.
+* :c:enum:`BT_FAST_PAIR_FMDN_RING_SRC_DULT_MOTION_DETECTOR` - This ringing source originates from the DULT motion detector module.
+  This source is available only when the :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT_MOTION_DETECTOR` Kconfig option is enabled.
 
 The following callbacks are defined in the :c:struct:`bt_fast_pair_fmdn_ring_cb` structure:
 
@@ -780,6 +783,8 @@ The following callbacks are defined in the :c:struct:`bt_fast_pair_fmdn_ring_cb`
     * Ringing timeout in deciseconds.
       The timeout value of the :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_RING_REQ_TIMEOUT_DULT_BT_GATT` Kconfig option is used for the :c:enum:`BT_FAST_PAIR_FMDN_RING_SRC_DULT_BT_GATT` DULT source.
       The default value of this Kconfig is in line with the `Fast Pair Unwanted Tracking Prevention Guidelines`_ documentation.
+      The timeout value of the :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_RING_REQ_TIMEOUT_DULT_MOTION_DETECTOR` Kconfig option is used for the :c:enum:`BT_FAST_PAIR_FMDN_RING_SRC_DULT_MOTION_DETECTOR` DULT source.
+      There are no specific requirements for this Kconfig value in neither the FMDN nor the DULT specification.
     * Ringing volume level.
 
   The :c:member:`bt_fast_pair_fmdn_ring_cb.start_request` callback can be called again when the ringing action has already started.
@@ -835,6 +840,38 @@ This update policy applies to all listed stop trigger types.
 To satisfy the requirements from the DULT specification when the :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT` Kconfig option is enabled, the FMDN extension communicates with the DULT module to receive ringing requests from the DULT peers and to send updates regarding the ringing state.
 For more details on the ringing mechanism in the DULT module, see the :ref:`ug_dult_sound` documentation.
 
+.. _ug_bt_fast_pair_gatt_service_fmdn_dult_motion_detector:
+
+Interacting with the motion detector from DULT
+----------------------------------------------
+
+The motion detector is an optional feature of the DULT subsystem that can be integrated into the FMDN extension.
+For more details about the feature, see the `DULT motion detector`_ section of the DULT specification.
+To activate the DULT motion detector functionality in the FMDN extension, enable the :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT_MOTION_DETECTOR` Kconfig option.
+The FMDN extension implementation acts as a thin wrapper for the DULT motion detector module callbacks.
+It passes callbacks from the DULT motion detector module to the user application.
+
+To register the motion detector callbacks, use the :c:func:`bt_fast_pair_fmdn_motion_detector_cb_register` function.
+You must register all motion detector callbacks defined in the :c:struct:`bt_fast_pair_fmdn_motion_detector_cb` structure:
+
+* The motion detector start request is indicated by the :c:member:`bt_fast_pair_fmdn_motion_detector_cb.start` callback.
+  After this callback is called, the motion detector events are polled periodically with the :c:member:`bt_fast_pair_fmdn_motion_detector_cb.period_expired` callback.
+  A typical action after the motion detector start request is to power up the accelerometer and start collecting motion data.
+* The motion detector period expired event is indicated by the :c:member:`bt_fast_pair_fmdn_motion_detector_cb.period_expired` callback.
+  This callback is called at the end of each motion detector period.
+  The :c:member:`bt_fast_pair_fmdn_motion_detector_cb.start` callback indicates the beginning of the first motion detector period.
+  The next period is started as soon as the previous period expires.
+  You need to notify the DULT module if motion was detected in the previous period.
+  The return value of this callback is used to pass this information.
+  The motion must be considered as detected if it fulfills the requirements defined in the `DULT motion detector`_ section of the DULT documentation.
+* The motion detector stop request is indicated by the :c:member:`bt_fast_pair_fmdn_motion_detector_cb.stop` callback.
+  It concludes the motion detector activity that was started by the :c:member:`bt_fast_pair_fmdn_motion_detector_cb.start` callback.
+  A typical action after the motion detector stop request is to power down the accelerometer.
+
+The motion detector is started by the DULT subsystem when the accessory is in the separated state for an amount of time controlled by the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MIN` and :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MAX` Kconfig options.
+When the motion is detected during the motion detector active period, the :c:member:`bt_fast_pair_fmdn_ring_cb.start_request` callback is called to request the ringing action with the :c:enum:`BT_FAST_PAIR_FMDN_RING_SRC_DULT_MOTION_DETECTOR` parameter as the ringing source.
+Played sounds help a non-owner identify an accessory that is moving with them, as the device might have been used to track the non-owner location by its owner.
+
 .. _ug_bt_fast_pair_gatt_service_fmdn_battery_dult:
 
 Battery information with DULT

doc/nrf/external_comp/dult.rst

@@ -47,6 +47,7 @@ The DULT integration in the |NCS| consists of the following steps:
 #. :ref:`Managing the identification process <ug_dult_identifier>`
 #. :ref:`Using the sound callbacks and managing the sound state <ug_dult_sound>`
 #. :ref:`Managing the battery information <ug_dult_battery>`
+#. :ref:`Interacting with the motion detector <ug_dult_motion_detector>`
 
 These steps are described in the following sections.
 
@@ -128,6 +129,7 @@ Use the following functions to register callbacks:
 
   * :c:func:`dult_id_read_state_cb_register` (mandatory)
   * :c:func:`dult_sound_cb_register` (mandatory)
+  * :c:func:`dult_motion_detector_cb_register` (mandatory if the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR` Kconfig option is enabled)
 
 Preset configuration
 ====================
@@ -213,6 +215,9 @@ There are following sound sources available:
 
 * Bluetooth GATT (:c:enum:`DULT_SOUND_SRC_BT_GATT`) - Sound source type originating from the Bluetooth ANOS.
   The non-owner device can trigger the sound callbacks by sending the relevant request message over the DULT GATT service.
+* Motion detector (:c:enum:`DULT_SOUND_SRC_MOTION_DETECTOR`) - Sound source type originating from the motion detector.
+  The motion detector may trigger the sound callbacks if the accessory separated from the owner for an amount of time controlled by the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MIN` and :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MAX` Kconfig options is moving.
+  Used only when the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR` Kconfig option is enabled.
 * External (:c:enum:`DULT_SOUND_SRC_EXTERNAL`) - Sound source type originating from the location unknown to the DULT module.
   The accessory-locating network often provides a native mechanism for playing sounds.
   The :c:enum:`DULT_SOUND_SRC_EXTERNAL` sound source is used to notify the DULT module that externally defined sound action is in progress.
@@ -221,12 +226,12 @@ To register the sound callbacks, use the :c:func:`dult_sound_cb_register` functi
 All sound callbacks defined in the :c:struct:`dult_sound_cb` structure are mandatory to register:
 
 * The sound start request is indicated by the :c:member:`dult_sound_cb.sound_start` callback.
-  The minimum duration for the DULT sound action is defined by the :c:macro:`DULT_SOUND_DURATION_MIN_MS`.
-  The upper layer determines the sound duration, and the duration must be greater than the value set in the :c:macro:`DULT_SOUND_DURATION_MIN_MS` macro.
+  The minimum duration for the DULT sound action originating from the Bluetooth ANOS is defined by the :c:macro:`DULT_SOUND_DURATION_BT_GATT_MIN_MS`.
+  The upper layer determines the sound duration, and for the sound action originating from the Bluetooth ANOS, the duration must exceed the value set in the :c:macro:`DULT_SOUND_DURATION_BT_GATT_MIN_MS` macro.
+  In case of the sound action originating from the motion detector, the minimum duration is not defined.
 * The sound stop request is indicated by the :c:member:`dult_sound_cb.sound_stop` callback.
 
-All callbacks pass the sound source as a first parameter and only report the internal sound sources.
-Currently, callbacks always use the :c:enum:`DULT_SOUND_SRC_BT_GATT` (internal) sound source.
+All callbacks pass the sound source as a first parameter and only report the internal sound sources (:c:enum:`DULT_SOUND_SRC_BT_GATT` or :c:enum:`DULT_SOUND_SRC_MOTION_DETECTOR`).
 The :c:enum:`DULT_SOUND_SRC_EXTERNAL` never appears as the callback parameter as the external sound source cannot originate from the DULT module.
 You must treat all callbacks from the :c:struct:`dult_sound_cb` structure as requests.
 The internal sound state of the DULT subsystem is not automatically changed on any callback event.
@@ -244,6 +249,41 @@ Asynchronous support is also necessary to report sound state changes that are tr
 
 .. rst-class:: numbered-step
 
+.. _ug_dult_motion_detector:
+
+Interacting with the motion detector
+************************************
+
+DULT motion detector is an optional feature of the DULT subsystem.
+For more details, see the `DULT motion detector`_ section of the DULT documentation.
+To support the DULT motion detector feature in your project, enable the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR` Kconfig option.
+
+To integrate the motion detector feature, set the motion detector unwanted tracking accessory capability bit (:c:enum:`DULT_ACCESSORY_CAPABILITY_MOTION_DETECTOR_UT_BIT_POS`) in the accessory capabilities bitmask.
+You must do this when registering the DULT user to indicate support for this feature.
+
+To register the motion detector callbacks, use the :c:func:`dult_motion_detector_cb_register` function.
+You must register all motion detector callbacks defined in the :c:struct:`dult_motion_detector_cb` structure:
+
+* The motion detector start request is indicated by the :c:member:`dult_motion_detector_cb.start` callback.
+  After this callback is called, the motion detector events are polled periodically with the :c:member:`dult_motion_detector_cb.period_expired` callback.
+  A typical action after the motion detector start request is to power up the accelerometer and start collecting motion data.
+* The motion detector period expired event is indicated by the :c:member:`dult_motion_detector_cb.period_expired` callback.
+  This callback is called at the end of each motion detector period.
+  The :c:member:`dult_motion_detector_cb.start` callback 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 DULT module if motion was detected in the previous period.
+  The return value of this callback is used to pass this information.
+  The motion must be considered as detected if it fulfills the requirements defined in the `DULT motion detector`_ section of the DULT documentation.
+* The motion detector stop request is indicated by the :c:member:`dult_motion_detector_cb.stop` callback.
+  It concludes the motion detector activity that was started by the :c:member:`dult_motion_detector_cb.start` callback.
+  A typical action after the motion detector stop request is to power down the accelerometer.
+
+The motion detector is started by the DULT subsystem when the accessory is in the separated state for an amount of time controlled by the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MIN` and :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MAX` Kconfig options.
+When the motion is detected during the motion detector active period, the DULT subsystem calls the :c:member:`dult_sound_cb.sound_start` callback to request the sound action with the :c:enum:`DULT_SOUND_SRC_MOTION_DETECTOR` parameter as the sound source.
+Played sounds help a non-owner identify an accessory that is moving with them, as the device might have been used to track the non-owner location by its owner.
+
+.. rst-class:: numbered-step
+
 .. _ug_dult_battery:
 
 Managing the battery information

doc/nrf/libraries/bluetooth_services/services/fast_pair.rst

@@ -62,6 +62,7 @@ With the :kconfig:option:`CONFIG_BT_FAST_PAIR` Kconfig option enabled, the follo
     * :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT_MODEL_NAME` - The option configures the model name parameter.
     * :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT_ACCESSORY_CATEGORY` - The option configures the accessory category parameter.
     * :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT_FIRMWARE_VERSION_MAJOR`, :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT_FIRMWARE_VERSION_MINOR` and :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT_FIRMWARE_VERSION_REVISION` - These options configure the firmware version parameter.
+    * :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT_MOTION_DETECTOR` - The option enables the DULT motion detector functionality support in the FMDN extension (see :ref:`ug_bt_fast_pair_gatt_service_fmdn_dult_motion_detector`).
 
   * There are following advertising configuration options for the FMDN extension (see :ref:`ug_bt_fast_pair_advertising_fmdn`):
 
@@ -90,6 +91,8 @@ With the :kconfig:option:`CONFIG_BT_FAST_PAIR` Kconfig option enabled, the follo
     * :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_RING_VOLUME` - The option enables ringing volume support.
     * :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_RING_REQ_TIMEOUT_DULT_BT_GATT` - The option configures the ringing timeout for connected peers that use DULT-based ringing mechanism.
       This option can only be used when the :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT` is enabled.
+    * :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_RING_REQ_TIMEOUT_DULT_MOTION_DETECTOR` - The option configures the ringing timeout for ringing requests from the DULT motion detector.
+      This option can only be used when the :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT` is enabled.
 
   * There are following beacon clock service configuration options for the FMDN extension (see :ref:`ug_bt_fast_pair_prerequisite_ops_fmdn_clock_svc`):
 
@@ -193,6 +196,10 @@ The FMDN extension implementation also acts as middleware between the user appli
 The DULT module integration is required for small and not easily discoverable accessories.
 The :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT` is enabled by default.
 
+The :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_DULT_MOTION_DETECTOR` of the FMDN extension selects the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR` Kconfig option to enable the motion detector feature of the DULT module.
+With this option enabled, the FMDN extension passes the DULT motion detector callbacks from the DULT module to application.
+To learn about implementation details for the DULT motion detector, see :ref:`ug_dult_motion_detector`.
+
 The :kconfig:option:`CONFIG_BT_FAST_PAIR_FMDN_BATTERY_DULT` of the FMDN extension selects the :kconfig:option:`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.
 

doc/nrf/libraries/others/dult.rst

@@ -44,6 +44,25 @@ The following Kconfig options are also available for this module:
   * :kconfig:option:`CONFIG_DULT_BT_ANOS_INDICATION_COUNT` - This option allows to configure the number of simultaneously processed GATT indications by the ANOS.
     The default value is set to ``2``.
 
+* :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR` - This option enables support for motion detector.
+  The motion detector is an optional feature in the DULT specification.
+  For more details see the `DULT motion detector`_ section of the DULT specification.
+  This option is disabled by default.
+
+  * :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_TEST_MODE` - This option allows to configure motion detector parameters for testing purposes.
+    These values are defined in the DULT specification and should not be changed in the production code.
+    This option is disabled by default.
+
+    * :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_BACKOFF_PERIOD` - This option allows to configure the period in minutes to disable the motion detector if the accessory is in the separated state.
+      If this option is configurable, its default value is set to ``2``.
+      Otherwise, its default value is set to ``360`` according to the DULT specification.
+    * :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MIN` - This option allows to configure the minimum time span in minutes in separated state before enabling motion detector.
+      If this option is configurable, its default value is set to ``3``.
+      Otherwise, its default value is set to ``480`` according to the DULT specification.
+    * :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MAX` - This option allows to configure the maximum time span in minutes in separated state before enabling motion detector.
+      If this option is configurable, its default value is set to ``3``.
+      Otherwise, its default value is set to ``1440`` according to the DULT specification.
+
 See the Kconfig help for details.
 
 Implementation details

doc/nrf/links.txt

@@ -1118,6 +1118,7 @@
 .. _`DULT Manufacturer Network ID Registry`: https://www.ietf.org/archive/id/draft-detecting-unwanted-location-trackers-01.html#name-manufacturer-network-id-reg
 .. _`DULT Accessory Category Values table`: https://www.ietf.org/archive/id/draft-detecting-unwanted-location-trackers-01.html#_table-accessory-category-values
 .. _`DULT Sound maker`: https://www.ietf.org/archive/id/draft-detecting-unwanted-location-trackers-01.html#name-sound-maker
+.. _`DULT motion detector`: https://www.ietf.org/archive/id/draft-detecting-unwanted-location-trackers-01.html#name-motion-detector
 
 .. ### Source: *.amazon.com