Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: Document DULT motion detector feature #18138

Merged
merged 2 commits into from
Oct 30, 2024
Merged

doc: Document DULT motion detector feature #18138

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e2d9361
doc: Document DULT motion detector feature
alstrzebonski Oct 22, 2024
9218c3d
doc: samples: locator_tag: Add motion detector testing steps
alstrzebonski Oct 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions doc/nrf/external_comp/bt_fast_pair.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:

Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down
48 changes: 44 additions & 4 deletions doc/nrf/external_comp/dult.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ The DULT integration in the |NCS| consists of the following steps:
#. :ref:`Managing the near-owner state <ug_dult_near_owner_state>`
#. :ref:`Managing the identification process <ug_dult_identifier>`
#. :ref:`Using the sound callbacks and managing the sound state <ug_dult_sound>`
#. :ref:`Interacting with the motion detector <ug_dult_motion_detector>`
kapi-no marked this conversation as resolved.
Show resolved Hide resolved
#. :ref:`Managing the battery information <ug_dult_battery>`

These steps are described in the following sections.
Expand Down Expand Up @@ -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
====================
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part down to the line 283 seems to be the same as in the Fast Pair doc, so you could do some reuse. Check https://github.com/nrfconnect/sdk-nrf/blob/main/doc/nrf/templates/cheat_sheet.rst (Reuse chapter). So in this case, add link tags just before the text to be copied and right after it something like this:

.. _motion_detector_reqs_start

To register...

.. _motion_detector_reqs_end

And then use them like this:

.. include:: ../bt_fast_pair.rst
:start-after: motion_detector_reqs_start
:end-before: motion_detector_reqs_end

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a difference in the structure name. One is dult_motion_detector_cb and the other one is bt_fast_pair_fmdn_motion_detector_cb.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a way to substitute it in all places without copying the whole part.

Copy link
Contributor

@peknis peknis Oct 25, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can use the same mechanism up until the part where the difference is found. And right after that, have another pair of link tags, so have two different includes. At least, you can reuse quite a bit.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The difference is present 6 times across 19 lines so I think it would be a mess to do it that way.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. Sorry for the hassle, I did not read thoroughly enough. But at least, you now know how to reuse when possible.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No problem, It's a shame that you can't use it as a "function" and include it with the parameter that could be changed in each include.

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
Expand Down
7 changes: 7 additions & 0 deletions doc/nrf/libraries/bluetooth_services/services/fast_pair.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`):

Expand Down Expand Up @@ -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.
kapi-no marked this conversation as resolved.
Show resolved Hide resolved

* There are following beacon clock service configuration options for the FMDN extension (see :ref:`ug_bt_fast_pair_prerequisite_ops_fmdn_clock_svc`):

Expand Down Expand Up @@ -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.
kapi-no marked this conversation as resolved.
Show resolved Hide resolved
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.

Expand Down
19 changes: 19 additions & 0 deletions doc/nrf/libraries/others/dult.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
kapi-no marked this conversation as resolved.
Show resolved Hide resolved

* :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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Take these three bullets back two steps. I guess they can be on the same level as the one above.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They have prompt only if the CONFIG_DULT_MOTION_DETECTOR_TEST_MODE is enabled so I wanted to group them under this kconfig description.

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
kapi-no marked this conversation as resolved.
Show resolved Hide resolved
Expand Down
1 change: 1 addition & 0 deletions doc/nrf/links.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading
Loading