doc: SUIT recovery button documentation

This commit documents the feature allowing to enter
SUIT recovery via a button press.

Signed-off-by: Artur Hadasz <[email protected]>

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

@@ -39,7 +39,7 @@ These issues can occur in the following scenarios:
   If any bugs are overlooked during the development phase, this could result in inconsistencies in the firmware.
 
 Recovery Mode and Recovery Manifests
-*************************************************
+************************************
 
 The recovery manifests form a separate hierarchy from the normal manifests.
 In this hierarchy, the application recovery (``APP_RECOVERY``) manifest is responsible for managing both the application core image and other manifests, such as the radio recovery manifest.
@@ -236,3 +236,85 @@ To turn an application into a recovery application, the following steps have to
     The value of ``SUIT_RECOVERY_APPLICATION_PATH`` can contain variables like ``${ZEPHYR_NRF_MODULE_DIR}``
 
 #. When building the main application, set ``SB_CONFIG_SUIT_RECOVERY_APPLICATION_CUSTOM`` (or the Kconfig option name if a different one was chosen) to ``y``.
+
+Entering recovery via button press
+**********************************
+
+It is possible to enable a feature that allows the device to enter recovery mode by pressing a button.
+This can be used for several purposes, such as:
+
+* Recovering the device if the main firmware crashes and no JLink connection is available.
+* Using the recovery application as a "foreground update" application, allowing to save some space in the main application.
+* Debugging the recovery application.
+
+When this feature is enabled, the device will enter recovery mode if the button is pressed during boot.
+
+.. note::
+   To exit the recovery mode, a device firmware update must be performed.
+
+There are two variants of this feature:
+
+* Recovery button checked in the recovery application run as a companion image at boot stage (recommended).
+* Recovery button checked in the main application.
+
+The first variant is recommended as it allows to perform the check independently of the main application.
+
+Recovery button checked in the recovery application
+===================================================
+
+In this variant the recovery application is run as a companion image before the main application when the device boots.
+It checks if the device already is in recovery mode.
+If it is, the recovery application proceeds with its normal operation allowing to recover firmware.
+
+If the device is not in recovery mode, the recovery application checks if the specified button is pressed.
+If the button is pressed, the recovery application sets the recovery flag and reboots the device.
+Otherwise it sends a confirmation message to the Secure Domain Firmware, which then halts the recovery application and proceeds with booting the main application.
+
+To enable the feature in this variant perform the following steps:
+
+1. Add the following code to :file:`sysbuild/recovery.overlay` in the main application directory:
+
+   .. code-block:: dts
+
+      / {
+         chosen {
+            ncs,recovery-button = &button0;
+         };
+      };
+
+   Replace ``button0`` with the appropriate button node.
+
+2. Enable :kconfig:option:`CONFIG_SUIT_RECOVERY_BUTTON` in the *recovery application* configuration.
+
+   When building from the command line, this can be done by adding ``-Drecovery_CONFIG_SUIT_RECOVERY_BUTTON=y`` to the build command.
+
+.. note::
+   In this option running the recovery application as a companion image is orchestrated by the root SUIT manifest.
+   Special care must be taken if the root manifest template is modified.
+   If incorrect modifications are made to the root manifest, the button press feature might not work.
+   This might lead to the device being unrecoverable without a JLink connection in case of a crash.
+
+
+Recovery button checked in the main application
+===============================================
+
+In this variant a check if the specified button is pressed is performed at an early stage when inside the main application firmware.
+If the button is pressed, the recovery flag is set and the device reboots.
+
+To enable the feature in this variant perform the following steps:
+
+1. Add the following overlay to the main application's configuration:
+
+   .. code-block:: dts
+
+      / {
+         chosen {
+            ncs,recovery-button = &button0;
+         };
+      };
+
+   Replace ``button0`` with the appropriate button node.
+
+2. Enable :kconfig:option:`CONFIG_SUIT_RECOVERY_BUTTON` in the main application configuration.
+
+   When building from the command line, this can be done by adding ``-DCONFIG_SUIT_RECOVERY_BUTTON=y`` to the build command.