doc: Describe CAF module suspend/resume request events support

Updates docs related to newly introduced CAF module
suspend/resume request events. Describes how the events
are used in nRF Desktop and CAF.

Jira: NCSDK-34237

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

Author: alstrzebonski

applications/nrf_desktop/board_configuration.rst

@@ -173,6 +173,7 @@ Sample mouse or dongle (``nrf54h20dk/nrf54h20/cpuapp``)
       * Bluetooth LE and USB High-Speed transports are enabled.
         Bluetooth LE is configured to use Nordic Semiconductor's SoftDevice Link Layer and Low Latency Packet Mode (LLPM).
         USB High-Speed is configured to use the USB next stack (:kconfig:option:`CONFIG_USB_DEVICE_STACK_NEXT`).
+        The :kconfig:option:`CONFIG_DESKTOP_BLE_ADV_CTRL_ENABLE` and :kconfig:option:`CONFIG_DESKTOP_BLE_ADV_CTRL_SUSPEND_ON_USB` Kconfig options are enabled in mouse configurations to improve the USB High-Speed report rate.
       * In ``debug`` configurations, logs are provided through the UART.
         For detailed information on working with the nRF54H20 DK, see the :ref:`ug_nrf54h20_gs` documentation.
       * The configurations use the Software Updates for Internet of Things (SUIT) and support firmware updates using the :ref:`nrf_desktop_dfu`.

applications/nrf_desktop/doc/ble_adv_ctrl.rst

@@ -0,0 +1,39 @@
+.. _nrf_desktop_ble_adv_ctrl:
+
+Bluetooth LE advertising control module
+#######################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+The Bluetooth LE advertising control module is responsible for controlling :ref:`caf_ble_adv`.
+The module is used to suspend and resume the |ble_adv|.
+For now, the module can only react to the USB state changes.
+It suspends the |ble_adv| when the active USB device is connected (USB state is set to :c:enum:`USB_STATE_ACTIVE`).
+It resumes the |ble_adv| when the USB is disconnected (USB state is set to :c:enum:`USB_STATE_DISCONNECTED`) and the |ble_adv| was earlier suspended.
+This improves the USB High-Speed performance.
+
+Module events
+*************
+
+.. include:: event_propagation.rst
+    :start-after: table_ble_adv_ctrl_start
+    :end-before: table_ble_adv_ctrl_end
+
+.. note::
+    |nrf_desktop_module_event_note|
+
+Configuration
+*************
+
+This module is disabled by default.
+To enable it, set the :ref:`CONFIG_DESKTOP_BLE_ADV_CTRL_ENABLE <config_desktop_app_options>` Kconfig option to ``y``.
+To enable the module to suspend and resume the :ref:`caf_ble_adv` when USB state changes, set the :ref:`CONFIG_DESKTOP_BLE_ADV_CTRL_SUSPEND_ON_USB <config_desktop_app_options>` Kconfig option to ``y``.
+It is recommended to enable this option if the device supports the USB High-Speed.
+
+Implementation details
+**********************
+
+This module subscribes to :c:struct:`usb_state_event` events sent by the |usb_state|.
+It reacts to these events by submitting :c:struct:`module_suspend_req_event` and :c:struct:`module_resume_req_event` events to the |ble_adv| when it is required.

applications/nrf_desktop/doc/event_propagation.rst

@@ -89,6 +89,10 @@ nRF Desktop event propagation
 +-----------------------------------------------+------------------------------+             |                            |                                             |
 | :ref:`nrf_desktop_ble_bond`                   | ``ble_peer_operation_event`` |             |                            |                                             |
 +-----------------------------------------------+------------------------------+             |                            |                                             |
+| :ref:`nrf_desktop_ble_adv_ctrl`               | ``module_resume_req_event``  |             |                            |                                             |
++-----------------------------------------------+------------------------------+             |                            |                                             |
+| :ref:`nrf_desktop_ble_adv_ctrl`               | ``module_suspend_req_event`` |             |                            |                                             |
++-----------------------------------------------+------------------------------+             |                            |                                             |
 | :ref:`nrf_desktop_module_state_event_sources` | ``module_state_event``       |             |                            |                                             |
 +-----------------------------------------------+------------------------------+             |                            |                                             |
 | :ref:`nrf_desktop_power_manager`              | ``power_down_event``         |             |                            |                                             |
@@ -119,6 +123,21 @@ nRF Desktop event propagation
 .. table_ble_adv_end
 
 
+.. table_ble_adv_ctrl_start
+
++------------------------------+---------------------+------------------+------------------------------+----------------------------+
+| Source Module                | Input Event         | This Module      | Output Event                 | Sink Module                |
++==============================+=====================+==================+==============================+============================+
+| :ref:`nrf_desktop_usb_state` | ``usb_state_event`` | ``ble_adv_ctrl`` |                              |                            |
++------------------------------+---------------------+                  +------------------------------+----------------------------+
+|                              |                     |                  | ``module_resume_req_event``  | :ref:`nrf_desktop_ble_adv` |
+|                              |                     |                  +------------------------------+----------------------------+
+|                              |                     |                  | ``module_suspend_req_event`` | :ref:`nrf_desktop_ble_adv` |
++------------------------------+---------------------+------------------+------------------------------+----------------------------+
+
+.. table_ble_adv_ctrl_end
+
+
 .. table_ble_bond_start
 
 +-----------------------------------------------+------------------------+--------------+------------------------------+---------------------------------------------+
@@ -1346,6 +1365,8 @@ nRF Desktop event propagation
 |                                               |                        |               +-----------------------------------+---------------------------------------------+
 |                                               |                        |               | ``usb_state_event``               | :ref:`nrf_desktop_battery_charger`          |
 |                                               |                        |               |                                   +---------------------------------------------+
+|                                               |                        |               |                                   | :ref:`nrf_desktop_ble_adv_ctrl`             |
+|                                               |                        |               |                                   +---------------------------------------------+
 |                                               |                        |               |                                   | :ref:`nrf_desktop_ble_conn_params`          |
 |                                               |                        |               |                                   +---------------------------------------------+
 |                                               |                        |               |                                   | :ref:`nrf_desktop_dvfs`                     |

applications/nrf_desktop/doc/usb_state_pm.rst

@@ -54,10 +54,15 @@ The application power level is imposed using the :c:struct:`power_manager_restri
 
 * If the USB state is set to :c:enum:`USB_STATE_POWERED`, the module restricts the power down level to the :c:enum:`POWER_MANAGER_LEVEL_SUSPENDED`.
 * If the USB state is set to :c:enum:`USB_STATE_ACTIVE`, the :c:enum:`POWER_MANAGER_LEVEL_ALIVE` is required.
-* If the USB state is set to :c:enum:`USB_STATE_DISCONNECTED`, any power level is allowed.
 * If the USB state is set to :c:enum:`USB_STATE_SUSPENDED`, the :c:enum:`POWER_MANAGER_LEVEL_SUSPENDED` is imposed.
   The module restricts the power down level to the :c:enum:`POWER_MANAGER_LEVEL_SUSPENDED`.
   The module also submits a :c:struct:`force_power_down_event` to force a quick power down.
+* If the USB state is set to :c:enum:`USB_STATE_DISCONNECTED`, any power level is allowed.
+  While disconnecting the USB cable, the :c:enum:`USB_STATE_SUSPENDED` USB state might be reported before the :c:enum:`USB_STATE_DISCONNECTED` USB state.
+  For the application to behave consistently regardless of whether the :c:enum:`USB_STATE_SUSPENDED` USB state was reported, the module also submits a :c:struct:`force_power_down_event` to force a quick power down.
+  The module initially restricts the power down level to the :c:enum:`POWER_MANAGER_LEVEL_SUSPENDED`.
+  Then, after the :ref:`CONFIG_DESKTOP_USB_PM_RESTRICT_REMOVE_DELAY_MS <config_desktop_app_options>` configurable delay, the module removes the power down level restriction.
+  This allows you to take actions, such as restart Bluetooth LE advertising, after disconnecting the USB cable without going through reboot.
 
 System power management latency
 ===============================

applications/nrf_desktop/modules.rst

@@ -19,6 +19,7 @@ These are valid for events that have many listeners or sources, and are gathered
    doc/battery_charger.rst
    doc/battery_meas.rst
    doc/ble_adv.rst
+   doc/ble_adv_ctrl.rst
    doc/ble_bond.rst
    doc/ble_conn_params.rst
    doc/ble_discovery.rst

applications/nrf_desktop/src/modules/Kconfig.ble_adv_ctrl

@@ -15,7 +15,7 @@ menuconfig DESKTOP_BLE_ADV_CTRL_ENABLE
 if DESKTOP_BLE_ADV_CTRL_ENABLE
 
 config DESKTOP_BLE_ADV_CTRL_SUSPEND_ON_USB
-	bool "Suspend Bluetooth LE adverising when USB is connected"
+	bool "Suspend Bluetooth LE advertising when USB is connected"
 	depends on DESKTOP_USB_ENABLE
 	help
 	  Suspend CAF Bluetooth LE advertising module while HID USB is active.

doc/nrf/libraries/caf/ble_adv.rst

@@ -20,6 +20,8 @@ The following Kconfig options are available for this module:
 * :kconfig:option:`CONFIG_CAF_BLE_ADV`
 * :kconfig:option:`CONFIG_CAF_BLE_ADV_PM_EVENTS`
 * :kconfig:option:`CONFIG_CAF_BLE_ADV_POWER_DOWN_ON_DISCONNECTION_REASON_0X15`
+* :kconfig:option:`CONFIG_CAF_BLE_ADV_MODULE_SUSPEND_EVENTS`
+* :kconfig:option:`CONFIG_CAF_BLE_ADV_SUSPEND_ON_READY`
 * :kconfig:option:`CONFIG_CAF_BLE_ADV_DIRECT_ADV`
 * :kconfig:option:`CONFIG_CAF_BLE_ADV_FAST_ADV`
 * :kconfig:option:`CONFIG_CAF_BLE_ADV_FAST_ADV_TIMEOUT`
@@ -71,6 +73,14 @@ Synchronizing RPA and advertising data updates
 With the :kconfig:option:`CONFIG_BT_PRIVACY` Kconfig option enabled, set the :kconfig:option:`CONFIG_CAF_BLE_ADV_ROTATE_RPA` option to synchronize Resolvable Private Address (RPA) rotation with the undirected advertising data update.
 You can control the rotation period with the :kconfig:option:`CONFIG_CAF_BLE_ADV_ROTATE_RPA_TIMEOUT` option and change the randomization factor of the rotation period with the :kconfig:option:`CONFIG_CAF_BLE_ADV_ROTATE_RPA_TIMEOUT_RAND` option.
 
+Suspending the module
+=====================
+
+When the :kconfig:option:`CONFIG_CAF_BLE_ADV_MODULE_SUSPEND_EVENTS` Kconfig option is enabled, you can suspend the module using a module suspend request event (:c:struct:`module_suspend_req_event`) directed to this module.
+When entering the suspended state, the module stops Bluetooth LE advertising and disconnects connected peers.
+You can resume the module using a module resume request event (:c:struct:`module_resume_req_event`) directed to this module.
+When the :kconfig:option:`CONFIG_CAF_BLE_ADV_SUSPEND_ON_READY` Kconfig option is enabled, the module is suspended automatically right after initialization.
+
 Power-down
 ==========
 

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

@@ -317,6 +317,13 @@ nRF Desktop
   * The :ref:`CONFIG_DESKTOP_HIDS_SUBSCRIBER_REPORT_MAX <config_desktop_app_options>` Kconfig option to :ref:`nrf_desktop_hids`.
     The option allows you to limit the number of HID input reports that can be simultaneously processed by the module.
     This limits the number of GATT notifications with HID reports in the Bluetooth stack.
+  * The :ref:`nrf_desktop_ble_adv_ctrl` module that is responsible for controlling the :ref:`caf_ble_adv`.
+    The module suspends the |ble_adv| when the active USB device is connected (USB state is set to :c:enum:`USB_STATE_ACTIVE`).
+    The module resumes the |ble_adv| when the USB is disconnected (USB state is set to :c:enum:`USB_STATE_DISCONNECTED`) and the |ble_adv| was earlier suspended.
+    This improves the USB High-Speed performance.
+    To enable the module, set the :ref:`CONFIG_DESKTOP_BLE_ADV_CTRL_ENABLE <config_desktop_app_options>` Kconfig option to ``y``.
+    To enable the module to suspend and resume the |ble_adv| when the USB state changes, set the :ref:`CONFIG_DESKTOP_BLE_ADV_CTRL_SUSPEND_ON_USB <config_desktop_app_options>` Kconfig option to ``y``.
+    These options are enabled for targets that support the USB High-Speed.
 
 * Updated:
 
@@ -364,6 +371,12 @@ nRF Desktop
 
     This change in the nRF54L10 partition map is a breaking change and cannot be performed using DFU.
     As a result, the DFU procedure will fail if you attempt to upgrade the sample firmware based on one of the |NCS| v3.0 releases.
+  * The behavior of the :ref:`nrf_desktop_usb_state_pm` on USB cable disconnection.
+    While disconnecting the USB cable, the :c:enum:`USB_STATE_SUSPENDED` USB state might be reported before the :c:enum:`USB_STATE_DISCONNECTED` USB state.
+    For application to behave consistently regardless of whether the :c:enum:`USB_STATE_SUSPENDED` USB state was reported, the module submits a :c:struct:`force_power_down_event` to force a quick power down.
+    The module also restricts the power down level to the :c:enum:`POWER_MANAGER_LEVEL_SUSPENDED`.
+    Then, after the :ref:`CONFIG_DESKTOP_USB_PM_RESTRICT_REMOVE_DELAY_MS <config_desktop_app_options>` configurable delay, the module removes the power down level restriction.
+    This allows you to take actions, such as restart Bluetooth LE advertising, after disconnecting the USB cable without going through reboot.
 
 nRF Machine Learning (Edge Impulse)
 -----------------------------------
@@ -744,6 +757,13 @@ Common Application Framework
   * Removed the tracking of the active Bluetooth connections.
     CAF no longer assumes that the Bluetooth Peripheral device (:kconfig:option:`CONFIG_BT_PERIPHERAL`) supports only one simultaneous connection (:kconfig:option:`CONFIG_BT_MAX_CONN`).
 
+* :ref:`caf_ble_adv`:
+
+  * Updated the module implementation to handle the newly introduced module suspend request event (:c:struct:`module_suspend_req_event`) and module resume request event (:c:struct:`module_resume_req_event`).
+    When entering the suspended state, the module stops Bluetooth LE advertising and disconnects connected peers.
+    To enable support for these events, use the :kconfig:option:`CONFIG_CAF_BLE_ADV_MODULE_SUSPEND_EVENTS` Kconfig option, which is enabled by default.
+    When the :kconfig:option:`CONFIG_CAF_BLE_ADV_SUSPEND_ON_READY` Kconfig option is enabled, the module is suspended automatically right after initialization.
+
 Debug libraries
 ---------------
 

include/caf/events/module_suspend_event.h

@@ -22,6 +22,11 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Module suspend request event
+ *
+ * The event is submitted by a module to request the suspension of another module.
+ */
 struct module_suspend_req_event {
 	/** Event header. */
 	struct app_event_header header;
@@ -35,6 +40,11 @@ struct module_suspend_req_event {
 
 APP_EVENT_TYPE_DECLARE(module_suspend_req_event);
 
+/**
+ * @brief Module resume request event
+ *
+ * The event is submitted by a module to request the resumption of another module.
+ */
 struct module_resume_req_event {
 	/** Event header. */
 	struct app_event_header header;