From 08ad8d4e9b2caf70862771973b22b0b8f4d1cf74 Mon Sep 17 00:00:00 2001 From: Aleksander Strzebonski Date: Tue, 22 Oct 2024 18:02:30 +0200 Subject: [PATCH 1/2] doc: Document DULT motion detector feature Jira: NCSDK-28984 Signed-off-by: Aleksander Strzebonski (cherry picked from commit 61c5c2f3f7dadd78bdc003ce35ebdb60de98d87c) --- doc/nrf/external_comp/bt_fast_pair.rst | 37 ++++++++++++++ doc/nrf/external_comp/dult.rst | 48 +++++++++++++++++-- .../bluetooth_services/services/fast_pair.rst | 7 +++ doc/nrf/libraries/others/dult.rst | 19 ++++++++ doc/nrf/links.txt | 1 + .../fast_pair/locator_tag/README.rst | 37 ++++++++++---- 6 files changed, 135 insertions(+), 14 deletions(-) diff --git a/doc/nrf/external_comp/bt_fast_pair.rst b/doc/nrf/external_comp/bt_fast_pair.rst index 4138f4c37941..bda04d55bdeb 100644 --- a/doc/nrf/external_comp/bt_fast_pair.rst +++ b/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. +Emitted sounds help to alert the non-owner that they are carrying an accessory that does not belong to them and might be used by the original owner to track their location. + .. _ug_bt_fast_pair_gatt_service_fmdn_battery_dult: Battery information with DULT diff --git a/doc/nrf/external_comp/dult.rst b/doc/nrf/external_comp/dult.rst index f03b840df79d..98408648bb1e 100644 --- a/doc/nrf/external_comp/dult.rst +++ b/doc/nrf/external_comp/dult.rst @@ -46,6 +46,7 @@ The DULT integration in the |NCS| consists of the following steps: #. :ref:`Managing the near-owner state ` #. :ref:`Managing the identification process ` #. :ref:`Using the sound callbacks and managing the sound state ` +#. :ref:`Interacting with the motion detector ` #. :ref:`Managing the battery information ` 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. +Emitted sounds help to alert the non-owner that they are carrying an accessory that does not belong to them and might be used by the original owner to track their location. + +.. rst-class:: numbered-step + .. _ug_dult_battery: Managing the battery information diff --git a/doc/nrf/libraries/bluetooth_services/services/fast_pair.rst b/doc/nrf/libraries/bluetooth_services/services/fast_pair.rst index 96c2d07ef898..a7c39d93d346 100644 --- a/doc/nrf/libraries/bluetooth_services/services/fast_pair.rst +++ b/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 more about 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. diff --git a/doc/nrf/libraries/others/dult.rst b/doc/nrf/libraries/others/dult.rst index 5a403fed03e9..a754129532a2 100644 --- a/doc/nrf/libraries/others/dult.rst +++ b/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 diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt index 33f324265f38..f6976cbd1e38 100644 --- a/doc/nrf/links.txt +++ b/doc/nrf/links.txt @@ -1123,6 +1123,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 diff --git a/samples/bluetooth/fast_pair/locator_tag/README.rst b/samples/bluetooth/fast_pair/locator_tag/README.rst index 99d97048e57f..9a6ce41d5646 100644 --- a/samples/bluetooth/fast_pair/locator_tag/README.rst +++ b/samples/bluetooth/fast_pair/locator_tag/README.rst @@ -79,6 +79,18 @@ Recovery mode In the provisioned state, you can enter the recovery mode for a limited time. This mode allows the Android device to recover a lost provisioning key from the locator tag. +Motion detector mode +-------------------- + +In the provisioned state, the accessory can activate the motion detector mode defined in the DULT specification. +The mode is activated when the accessory is separated from the owner for a sufficient amount of time (see :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). +In this state, if motion is detected, the accessory starts the ringing action. +Emitted sounds help to alert the non-owner that they are carrying an accessory that does not belong to them and might be used by the original owner to track their location. +On DKs, you can generate the simulated motion by button action. +On the Thingy:53, the built-in accelerometer is used to detect the motion. +The motion detector is deactivated for the period set in the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_BACKOFF_PERIOD` Kconfig option after 10 sounds has been played or after the motion has been detected and 20 seconds have passed. +The motion detector is also deactivated if the accessory reappears near its owner. + FMDN unprovisioning =================== @@ -220,11 +232,12 @@ The user interface of the sample depends on the hardware platform you are using. * Blinks at a 0.25 second interval if the DFU mode is enabled. LED 2: - Indicates that the ringing action is in progress. - Depending on the ringing state: + Depending on the motion detected event, the ringing state, and the motion detector state: - * Lit if the device is ringing. - * Off if the device is not ringing. + * Blinks fast twice if the motion detected event appears. + * Lit if the device is ringing and no motion detection event is being indicated. + * Blinks at a 0.25 second interval if the motion detector is active and none of the above conditions are met. + * Off if none of the above conditions are met. LED 3: Depending on the FMDN provisioning state and the Fast Pair advertising state: @@ -248,7 +261,8 @@ The user interface of the sample depends on the hardware platform you are using. See the :ref:`fast_pair_locator_tag_fp_adv_policy` section for details. Button 2: - Stops the ongoing ringing action. + Stops the ongoing ringing action on a single press. + Generates simulated motion event on a double press. Button 3: Decrements the battery level by 10% (the default value in the :ref:`CONFIG_APP_BATTERY_LEVEL_DECREMENT ` Kconfig option), starting from the full battery level of 100%. @@ -303,11 +317,12 @@ The user interface of the sample depends on the hardware platform you are using. * Blinks at a 0.25 second interval if the DFU mode is enabled. LED 1: - Indicates that the ringing action is in progress. - Depending on the ringing state: + Depending on the motion detected event, the ringing state, and the motion detector state: - * Lit if the device is ringing. - * Off if the device is not ringing. + * Blinks fast twice if the motion detected event appears. + * Lit if the device is ringing and no motion detection event is being indicated. + * Blinks at a 0.25 second interval if the motion detector is active and none of the above conditions are met. + * Off if none of the above conditions are met. LED 2: Depending on the FMDN provisioning state and the Fast Pair advertising state: @@ -331,7 +346,8 @@ The user interface of the sample depends on the hardware platform you are using. See the :ref:`fast_pair_locator_tag_fp_adv_policy` section for details. Button 1: - Stops the ongoing ringing action. + Stops the ongoing ringing action on a single press. + Generates simulated motion event on a double press. Button 2: Decrements the battery level by 10% (the default value in the :ref:`CONFIG_APP_BATTERY_LEVEL_DECREMENT ` Kconfig option), starting from the full battery level of 100%. @@ -390,6 +406,7 @@ The user interface of the sample depends on the hardware platform you are using. * Red - Indicates that the recovery mode is active. * White - Indicates that the Fast Pair advertising is active. * Purple - Indicates that the DFU mode is active. + * Cyan - Indicates that the motion detector is active. Speaker/Buzzer: Produces sound when the ringing action is in progress and to indicate a new button action. From 89b1ba434b294f0297715ab7eda6b8c0a165e6de Mon Sep 17 00:00:00 2001 From: Aleksander Strzebonski Date: Fri, 25 Oct 2024 11:24:42 +0200 Subject: [PATCH 2/2] doc: samples: locator_tag: Add motion detector testing steps Jira: NCSDK-28984 Signed-off-by: Aleksander Strzebonski (cherry picked from commit da3a1238454e0def13981cd6a31c5cadb34b1a49) --- .../fast_pair/locator_tag/README.rst | 149 +++++++++++++++++- 1 file changed, 148 insertions(+), 1 deletion(-) diff --git a/samples/bluetooth/fast_pair/locator_tag/README.rst b/samples/bluetooth/fast_pair/locator_tag/README.rst index 9a6ce41d5646..5eb9bf809b16 100644 --- a/samples/bluetooth/fast_pair/locator_tag/README.rst +++ b/samples/bluetooth/fast_pair/locator_tag/README.rst @@ -530,6 +530,24 @@ For example, when building from the command line, you can add it as follows: west build -b *board_target* -- -DFILE_SUFFIX=release +.. _fast_pair_locator_tag_motion_detector_test_build: + +Motion detector test build +========================== + +If you want to make testing the motion detector easier, enable the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_TEST_MODE` Kconfig option to shorten the period between the device entering the Unwanted Tracking Protection mode and the activation of the motion detector. +With this option enabled, the values of 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 that are responsible for this period are shortened to three minutes. +Otherwise, the period would be a random value between 8 and 24 hours. +The :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_TEST_MODE` Kconfig option also shortens the motion detector backoff period (:kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_BACKOFF_PERIOD`) from six hours to two minutes. + +See :ref:`configuring_kconfig` for detailed instructions on how to enable the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_TEST_MODE` Kconfig option in your build. +For example, when building from the command line, you can enable it as follows: + +.. parsed-literal:: + :class: highlight + + west build -b *board_target* -- -DCONFIG_DULT_MOTION_DETECTOR_TEST_MODE=y + .. _fast_pair_locator_tag_testing: Testing @@ -540,7 +558,7 @@ Testing The debug device model name is covered by asterisks and the default Fast Pair logo is displayed instead of the one specified during the device model registration. If the test Android device uses a primary email account that is not on Google's email allow list for the FMDN feature, testing steps will fail at the FMDN provisioning stage for the default debug (uncertified) device model. - To be able to test with debug device models, register your development email account by completing Google's device proposal form. + To be able to test with debug device models and use the "Inspect Spot device" tool in the `Find My Device app`_, register your development email account by completing Google's device proposal form. You can find the link to the device proposal form in the `Fast Pair Find My Device Network extension`_ specification. |test_sample| @@ -758,6 +776,135 @@ To test this feature, complete the following steps: #. Start the ringing action on your device by tapping the :guilabel:`Play sound` button. #. Observe that **LED 1** is lit to confirm that the Android device is able to connect to your development kit after a clock synchronization. +Motion detector +--------------- + +To test this feature, complete the following steps: + +.. tabs:: + + .. group-tab:: nRF52 and nRF53 DKs + + 1. Enable the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_TEST_MODE` Kconfig option in the sample configuration to shorten the motion detector activation periods. + Refer to the :ref:`fast_pair_locator_tag_motion_detector_test_build` section for details on how to build the sample in the motion detector test mode. + #. Build and flash the application in the motion detector test mode on your target device. + #. Go to the :ref:`fast_pair_locator_tag_testing` section and follow the instructions on performing the FMDN provisioning operation. + #. Observe that **LED 3** is lit, which indicates that the device is provisioned as an FMDN beacon. + #. Double-click **Button 2** to simulate the motion event. + #. Observe that **LED 2** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that the ringing action does not start, because the motion detector is inactive. + #. Put the device into the Unwanted Tracking Protection mode. + You can do it in two ways. + If you have access to the "Inspect Spot device" tool in the Find My Device Android app, you can: + + 1. Open the Find My Device app. + #. Tap your accessory in the list. + The accessory should have "Nearby" written under its name. + #. Tap the gear icon next to the device name + #. Tap the 3-dot menu and then :guilabel:`Inspect Spot device (internal)`. + #. Tap the 3-dot menu and then :guilabel:`Activate Unwanted Tracking Mode`. + #. Observe the "Changed unwanted tracking mode successfully" message on the screen. + #. Turn off your Android device to prevent it from automatically deactivating the mode. + Do this as quickly as possible after activating the mode. + + Otherwise, you can: + + 1. Turn off your Android device. + #. Wait for minimum 30 minutes for other Android device to put the device into the Unwanted Tracking Protection mode. + The other Android device can belong to anyone around you. + It is recommended to be in a crowded area. + + #. Wait for three minutes (random value between 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) for the motion detector to be activated. + #. Observe that **LED 2** blinks at a 0.25 second interval, which indicates that the motion detector is active. + #. Double-click **Button 2** to simulate the motion event. + #. Observe that **LED 2** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that after up to 10 seconds, the ringing action starts for one second, which is indicated by **LED 2** being lit. + #. Observe that **LED 2** goes back to blinking at a 0.25 second interval, which indicates that the motion detector is active. + #. Double-click **Button 2** to simulate the motion event. + #. Observe that **LED 2** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that after up to 0.5 second, the ringing action starts for one second, which is indicated by **LED 2** being lit. + #. Observe that **LED 2** goes back to blinking at a 0.25 second interval, which indicates that the motion detector is active. + #. Double-click **Button 2** to simulate the motion event. + #. Observe that **LED 2** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that after up to 0.5 second, the ringing action starts, which is indicated by **LED 2** being lit. + #. Double-click **Button 2** to simulate the motion event while the **LED 2** is still lit (ringing action is still in progress). + #. Observe that **LED 2** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that after 0.5 second, of not ringing, the ringing action starts again for one second, which is indicated by **LED 2** being lit. + #. Observe that **LED 2** goes back to blinking at a 0.25 second interval, which indicates that the motion detector is active. + #. Observe that after 20 seconds from the first motion event or after 10 ringing actions completes, the **LED 2** is off, which indicates that the motion detector is inactive. + #. Double-click **Button 2** to simulate the motion event. + #. Observe that **LED 2** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that the ringing action does not start, because the motion detector is inactive. + #. Wait for two minutes (the backoff period defined by the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_BACKOFF_PERIOD` Kconfig option) for the motion detector to be activated again. + #. Observe that **LED 2** blinks at a 0.25 second interval, which indicates that the motion detector is active. + #. Double-click **Button 2** to simulate the motion event and observe the ringing action just as before. + #. Wait for 20 seconds for the **LED 2** to go off, which indicates that the motion detector is inactive. + #. Wait for two minutes for the motion detector to be activated again. + #. Observe that **LED 2** blinks at a 0.25 second interval, which indicates that the motion detector is active. + #. Turn on your Android device. + #. Observe that after up to few hours the **LED 2** goes off, which means that the motion detector has been deactivated, because the device is no longer in the Unwanted Tracking Protection mode. + + .. group-tab:: nRF54 DKs + + 1. Enable the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_TEST_MODE` Kconfig option in the sample configuration to shorten the motion detector activation periods. + Refer to the :ref:`fast_pair_locator_tag_motion_detector_test_build` section for details on how to build the sample in the motion detector test mode. + #. Build and flash the application in the motion detector test mode on your target device. + #. Go to the :ref:`fast_pair_locator_tag_testing` section and follow the instructions on performing the FMDN provisioning operation. + #. Observe that **LED 2** is lit, which indicates that the device is provisioned as an FMDN beacon. + #. Double-click **Button 1** to simulate the motion event. + #. Observe that **LED 1** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that the ringing action does not start, because the motion detector is inactive. + #. Put the device into the Unwanted Tracking Protection mode. + You can do it in two ways. + If you have access to the "Inspect Spot device" tool in the Find My Device Android app, you can: + + 1. Open the Find My Device app. + #. Tap your accessory in the list. + The accessory should have "Nearby" written under its name. + #. Tap the gear icon next to the device name + #. Tap the 3-dot menu and then :guilabel:`Inspect Spot device (internal)`. + #. Tap the 3-dot menu and then :guilabel:`Activate Unwanted Tracking Mode`. + #. Observe the "Changed unwanted tracking mode successfully" message on the screen. + #. Turn off your Android device to prevent it from automatically deactivating the mode. + Do this as quickly as possible after activating the mode. + + Otherwise, you can: + + 1. Turn off your Android device. + #. Wait for minimum 30 minutes for other Android device to put the device into the Unwanted Tracking Protection mode. + The other Android device can belong to anyone around you. + It is recommended to be in a crowded area. + + #. Wait for three minutes (random value between 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) for the motion detector to be activated. + #. Observe that **LED 1** blinks at a 0.25 second interval, which indicates that the motion detector is active. + #. Double-click **Button 1** to simulate the motion event. + #. Observe that **LED 1** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that after up to 10 seconds, the ringing action starts for one second, which is indicated by **LED 1** being lit. + #. Observe that **LED 1** goes back to blinking at a 0.25 second interval, which indicates that the motion detector is active. + #. Double-click **Button 1** to simulate the motion event. + #. Observe that **LED 1** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that after up to 0.5 second, the ringing action starts for one second, which is indicated by **LED 1** being lit. + #. Observe that **LED 1** goes back to blinking at a 0.25 second interval, which indicates that the motion detector is active. + #. Double-click **Button 1** to simulate the motion event. + #. Observe that **LED 1** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that after up to 0.5 second, the ringing action starts, which is indicated by **LED 1** being lit. + #. Double-click **Button 1** to simulate the motion event while the **LED 1** is still lit (ringing action is still in progress). + #. Observe that **LED 1** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that after 0.5 second, of not ringing, the ringing action starts again for one second, which is indicated by **LED 1** being lit. + #. Observe that **LED 1** goes back to blinking at a 0.25 second interval, which indicates that the motion detector is active. + #. Observe that after 20 seconds from the first motion event or after 10 ringing actions completes, the **LED 1** is off, which indicates that the motion detector is inactive. + #. Double-click **Button 1** to simulate the motion event. + #. Observe that **LED 1** blinks fast twice, which indicates that the motion detected event appears. + #. Observe that the ringing action does not start, because the motion detector is inactive. + #. Wait for two minutes (the backoff period defined by the :kconfig:option:`CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_BACKOFF_PERIOD` Kconfig option) for the motion detector to be activated again. + #. Observe that **LED 1** blinks at a 0.25 second interval, which indicates that the motion detector is active. + #. Double-click **Button 1** to simulate the motion event and observe the ringing action just as before. + #. Wait for 20 seconds for the **LED 1** to go off, which indicates that the motion detector is inactive. + #. Wait for two minutes for the motion detector to be activated again. + #. Observe that **LED 1** blinks at a 0.25 second interval, which indicates that the motion detector is active. + #. Turn on your Android device. + #. Observe that after up to few hours the **LED 1** goes off, which means that the motion detector has been deactivated, because the device is no longer in the Unwanted Tracking Protection mode. + Performing the DFU procedure ----------------------------