applications: nrf_desktop: Improve motion buttons documentation

Change introduces additional information related to the configuration
and implementation details of the module.

Jira: NCSDK-22789

Signed-off-by: Marek Pieta <[email protected]>

Author: MarekPieta

applications/nrf_desktop/doc/motion.rst

@@ -40,6 +40,8 @@ Depending on the selected configuration option, a different implementation file
 
 You can use the :ref:`CONFIG_DESKTOP_MOTION_PM_EVENTS <config_desktop_app_options>` Kconfig option to enable or disable handling of the power management events, such as :c:struct:`power_down_event` and :c:struct:`wake_up_event`.
 The option is enabled by default and depends on the :kconfig:option:`CONFIG_CAF_PM_EVENTS` Kconfig option.
+The option is unavailable for the motion module implementation that generates movement data using buttons (:ref:`CONFIG_DESKTOP_MOTION_BUTTONS_ENABLE <config_desktop_app_options>`).
+The implementation does not react to the power management events.
 
 Movement data from motion sensors
 =================================
@@ -63,6 +65,20 @@ Movement data from buttons
 
 Selecting the :ref:`CONFIG_DESKTOP_MOTION_BUTTONS_ENABLE <config_desktop_app_options>` option adds the :file:`src/hw_interface/motion_buttons.c` file to the compilation.
 
+The movement data is generated when pressing a button.
+The module detects the button presses by relying on the received :c:struct:`button_event`.
+Generating motion for every direction is triggered using a separate button.
+Key ID (:c:member:`button_event.key_id`) of the button used to generate motion for a given direction can be configured with a dedicated Kconfig option:
+
+* Up (:ref:`CONFIG_DESKTOP_MOTION_BUTTONS_UP_KEY_ID <config_desktop_app_options>`)
+* Down (:ref:`CONFIG_DESKTOP_MOTION_BUTTONS_DOWN_KEY_ID <config_desktop_app_options>`)
+* Left (:ref:`CONFIG_DESKTOP_MOTION_BUTTONS_LEFT_KEY_ID <config_desktop_app_options>`)
+* Right (:ref:`CONFIG_DESKTOP_MOTION_BUTTONS_RIGHT_KEY_ID <config_desktop_app_options>`)
+
+Pressing and holding one of the mentioned buttons results in generating data for movement in a given direction.
+The :ref:`CONFIG_DESKTOP_MOTION_BUTTONS_MOTION_PER_SEC <config_desktop_app_options>` can be used to control a motion generated per second during a button press.
+By default, ``1000`` of motion is generated per second during a button press.
+
 Simulated movement data
 =======================
 
@@ -166,6 +182,18 @@ The module continues to sample data until disconnection or when there is no moti
 The ``motion`` module assumes no motion when a number of consecutive samples equal to :ref:`CONFIG_DESKTOP_MOTION_SENSOR_EMPTY_SAMPLES_COUNT <config_desktop_app_options>` returns zero on both axis.
 In such case, the module will switch back to ``STATE_IDLE`` and wait for the motion sensor trigger.
 
+Movement data from buttons
+==========================
+
+Motion is generated based on the total time a button is pressed.
+The time measurements rely on the hardware clock.
+If available, the module uses the :c:func:`k_cycle_get_64` function to read the hardware clock.
+Otherwise, the :c:func:`k_cycle_get_32` function is used for that purpose.
+
+When a HID subscriber is connected, that is when the device is connected either over USB or Bluetooth LE, the module forwards the generated motion to the subscriber using :c:struct:`motion_event`.
+The first :c:struct:`motion_event` is generated when a button is pressed.
+The subsequent :c:struct:`motion_event` is submitted when the previously generated motion data is sent to the subscriber, that is when :c:struct:`hid_report_sent_event` is received by the module.
+
 Simulated movement data
 =======================
 

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

@@ -206,13 +206,17 @@ nRF Machine Learning (Edge Impulse)
 nRF Desktop
 -----------
 
-* Added Kconfig options to enable handling of the power management events for the following nRF Desktop modules:
+* Added:
+
+  * Kconfig options to enable handling of the power management events for the following nRF Desktop modules:
 
-  * :ref:`nrf_desktop_board` - The :ref:`CONFIG_DESKTOP_BOARD_PM_EVENTS <config_desktop_app_options>` Kconfig option.
-  * :ref:`nrf_desktop_motion` - The :ref:`CONFIG_DESKTOP_MOTION_PM_EVENTS <config_desktop_app_options>` Kconfig option.
-  * :ref:`nrf_desktop_ble_latency` - The :ref:`CONFIG_DESKTOP_BLE_LATENCY_PM_EVENTS <config_desktop_app_options>` Kconfig option.
+    * :ref:`nrf_desktop_board` - The :ref:`CONFIG_DESKTOP_BOARD_PM_EVENTS <config_desktop_app_options>` Kconfig option.
+    * :ref:`nrf_desktop_motion` - The :ref:`CONFIG_DESKTOP_MOTION_PM_EVENTS <config_desktop_app_options>` Kconfig option.
+    * :ref:`nrf_desktop_ble_latency` - The :ref:`CONFIG_DESKTOP_BLE_LATENCY_PM_EVENTS <config_desktop_app_options>` Kconfig option.
 
-  All listed Kconfig options are enabled by default and depend on the :kconfig:option:`CONFIG_CAF_PM_EVENTS` Kconfig option.
+    All listed Kconfig options are enabled by default and depend on the :kconfig:option:`CONFIG_CAF_PM_EVENTS` Kconfig option.
+  * Kconfig option to configure a motion generated per second during a button press (:ref:`CONFIG_DESKTOP_MOTION_BUTTONS_MOTION_PER_SEC <config_desktop_app_options>`) in the :ref:`nrf_desktop_motion`.
+    The implementation relies on the hardware clock instead of system uptime to improve accuracy of the motion data generated when pressing a button.
 
 * Updated:
 
@@ -223,6 +227,8 @@ nRF Desktop
   * Disabled ``CONFIG_BOOT_SERIAL_IMG_GRP_HASH`` in MCUboot bootloader release configurations of boards that use nRF52820 SoC.
     This is done to reduce the memory consumption.
   * To improve the accuracy, the generation of simulated movement data in the :ref:`nrf_desktop_motion` now uses a timestamp in microseconds based on the cycle count (either :c:func:`k_cycle_get_32` or :c:func:`k_cycle_get_64` function depending on the :kconfig:option:`CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER` Kconfig option).
+  * Aligned Kconfig option names in the :ref:`nrf_desktop_motion` implementation that generates motion from button presses.
+    The Kconfig options defining used key IDs are prefixed with ``CONFIG_MOTION_BUTTONS_`` instead of ``CONFIG_MOTION_`` to ensure consistency with configuration of other implementations of the motion module.
 
 Thingy:53: Matter weather station
 ---------------------------------