doc: update SUIT firmware upgrade with external flash

Updated the SUIT firmware upgrade documentation to reflect the latest
state.

Signed-off-by: Rafał Kuźnia <[email protected]>

doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst

@@ -51,37 +51,37 @@ Enabling external flash support in SUIT DFU
 The :file:`nrf/samples/suit/smp_transfer` sample contains a premade configuration enabling the external memory in SUIT DFU.
 To enable the external memory, you must apply the :file:`nrf/samples/suit/smp_transfer/overlay-extmem.conf` and :file:`nrf/samples/suit/smp_transfer/ext_flash_nrf54h20dk.overlay` overlays to the sample build or complete the following steps:
 
-1. Create a partition named ``companion_partition`` in the executable memory region that is accessible to the application domain by editing the devicetree (DTS) file:
+1. Power-up the external flash chip on nRF54H20 DK using the `nRF Connect Board Configurator`_ app in `nRF Connect for Desktop`_ .
 
-   .. code-block:: devicetree
-
-      &mram0 {
-         partitions {
-            companion_partition: partition@116000 {
-               label = "companion-image";
-               reg = <0x116000 DT_SIZE_K(64)>;
-            };
-         };
-      };
+   .. note::
+      This step is needed only on nRF54H20 DK. Skip this step if you are using different hardware.
 
-   The ``companion_partition`` is the region where the companion image will be executed.
-   Adjust the addresses accordingly to your application.
+#. Enable the :kconfig:option:`SB_CONFIG_SUIT_BUILD_FLASH_COMPANION` Sysbuild Kconfig option, which enables the build of the reference companion image.
+   See :ref:`suit_flash_companion` for instructions on how to configure the companion image using Sysbuild.
 
 #. Define a new DFU cache partition in the external memory in the DTS file:
 
    .. code-block:: devicetree
 
-      mx66um1g: mx66um1g45g@0 {
+      &mx25uw63 {
          ...
+         status = "okay";
          partitions {
+            compatible = "fixed-partitions";
+            #address-cells = <1>;
+            #size-cells = <1>;
+
             dfu_cache_partition_1: partition@0 {
-               reg = <0x0 DT_SIZE_K(512)>;
+               reg = <0x0 DT_SIZE_K(1024)>;
             };
          };
       };
 
    Note the name of the partition.
+   It must follow the ``dfu_cache_partition_<n>`` format.
    The number at the end determines the ``CACHE_POOL`` ID, which will be used later in the SUIT manifest.
+   The number must be between greater than 0 and less than :kconfig:option:`CONFIG_SUIT_CACHE_MAX_CACHES`.
+   The Secure Domain firmware supports up to 8 DFU cache partitions.
 
 #. Modify the application manifest file :file:`app_envelope.yaml.jinja2` by completing the following:
 
@@ -103,9 +103,9 @@ To enable the external memory, you must apply the :file:`nrf/samples/suit/smp_tr
          suit-components:
              ...
          - - MEM
-           - {{ flash_companion_subimage['dt'].label2node['cpu'].unit_addr }}
-           - {{ get_absolute_address(flash_companion_subimage['dt'].chosen_nodes['zephyr,code-partition']) }}
-           - {{ flash_companion_subimage['dt'].chosen_nodes['zephyr,code-partition'].regs[0].size }}
+           - {{ flash_companion['dt'].label2node['cpu'].unit_addr }}
+           - {{ get_absolute_address(flash_companion['dt'].chosen_nodes['zephyr,code-partition']) }}
+           - {{ flash_companion['dt'].chosen_nodes['zephyr,code-partition'].regs[0].size }}
 
       In this example, the component index is ``3``.
       In the following steps, the companion image component is selected with ``suit-directive-set-component-index: 3``.
@@ -121,18 +121,47 @@ To enable the external memory, you must apply the :file:`nrf/samples/suit/smp_tr
 
       The companion image can be optionally upgraded and have its integrity checked.
 
-#. Enable the :kconfig:option:`CONFIG_SUIT_EXTERNAL_MEMORY_SUPPORT` Kconfig option, which enables the build of the reference companion image to be used as a child image of the application firmware.
-   It also enables other additional options that are required for the external memory DFU to work.
+#. Build and flash the application.
+
+   .. code-block:: console
+
+      $ west build -b nrf54h20dk/nrf54h20/cpuapp --sysbuild
+      $ west flash
+
+   The build system will automatically generate :file:`build/suit.zip` archive, which contains the SUIT envelope and candidate images.
+
+#. Build a new version of the application with incremented :kconfig:option:`SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM` value.
+
+#. Download the new :file:`suit.zip` archive to your mobile device.
+
+#. Use the `nRF Connect Device Manager`_ mobile app to update your device with the new firmware.
+
+   a. Ensure that you can access the :file:`suit.zip` archive from your phone or tablet.
+
+   #. In the mobile app, scan and select the device to update.
+
+   #. Switch to the :guilabel:`Image` tab.
+
+   #. Tap the :guilabel:`SELECT FILE` button and select the :file:`suit.zip` archive.
+
+   #. Tap the :guilabel:`UPLOAD` button.
+
+   #. Initiate the DFU process of transferring the image to the device.
+
+      The Device Manager mobile application will unpack the file and upload the SUIT envelope to the device.
+      The firmware images will be uploaded separately by the mobile application to the device, if the device requests it.
+
+   #. Wait for the DFU to finish and then verify that the application works properly.
 
 Create custom companion images
 ******************************
 
-Nordic Semiconductor provides a reference companion image in the :file:`samples/suit/flash_companion` file, which can serve as a base for developing a customized companion image.
+Nordic Semiconductor provides a reference companion image in the :file:`samples/suit/flash_companion` directory, which can serve as a base for developing a customized companion image.
 
 Limitations
 ***********
 
-* The Secure Domain and companion image candidates must always be stored in MRAM.
+* The Secure Domain, System Controller and companion image update candidates must always be stored in MRAM.
   Trying to store those candidates in external memory will result in failure during the installation process.
 
 * The companion image needs a dedicated area in the executable region of the MRAM that is assigned to the application domain.

doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_fetch.rst

@@ -11,7 +11,7 @@ In the Software Updates for Internet of Things (SUIT), it is possible for a devi
 
 1. The push model - where all necessary candidate images are integrated into the SUIT envelope, and uploaded to a device as a single unit.
 
-#. The fetch model - where the envelope contains 0 or not all necessary candidate images, and is performed by the application firmware.
+#. The fetch model - where the envelope contains 0 or not all necessary candidate images.
    The manifest contains logic that instructs the device to fetch other required candidate images through a user-defined mechanism during the envelope processing.
 
 This guide explains how to reconfigure an application that uses the push model to a fetch model-based upgrade.
@@ -38,7 +38,7 @@ The fetch model has greater flexibility compared to the push model in the follow
   For example, fetching up-to-date firmware can be completely skipped, which saves battery life and transfer costs.
 
 * Custom fetch source can be implemented.
-  Nordic Semiconductor provides a reference fetch source implementation which uses the SMP protocol over serial or Bluetooth® LE.
+  Nordic Semiconductor provides a reference fetch source implementation which uses the SMP protocol over serial or Bluetooth® LE.
   You have the option to implement any fetching mechanism needed for the application, such as fetching from an HTTP resource.
 
 * Candidate images can be stored in a different memory partition than the envelope itself.
@@ -54,12 +54,12 @@ To reconfigure the sample to use the fetch model, complete the following steps:
 1. Enable the following three Kconfig options:
 
    * :kconfig:option:`CONFIG_SUIT_DFU_CANDIDATE_PROCESSING_FULL` - This enables SUIT envelope processing in the application firmware.
-     The application firmware will execute the ``suit-payload-fetch`` sequence, if is already in the root manifest.
+     The application firmware will execute the ``suit-payload-fetch`` sequence, if it is defined in the root manifest.
    * :kconfig:option:`CONFIG_MGMT_SUITFU_GRP_SUIT_CAND_ENV_UPLOAD` and :kconfig:option:`CONFIG_MGMT_SUITFU_GRP_SUIT_IMAGE_FETCH`.
      These options enable Nordic Semiconductor's reference implementation of the SMP-based fetch source.
      In this implementation, the SMP server (the device being updated) uses the SMP client (a computer or a mobile phone) as a proxy to fetch the required candidate images.
 
-#. Add the ``suit-payload-fetch`` sequence to the root manifest :file:`root_hierarchical_envelope.yaml.jinja2`:
+#. Add the ``suit-payload-fetch`` sequence to the root manifest :file:`root_with_binary_nordic_top.yaml.jinja2`:
 
    .. code-block:: console
 
@@ -80,7 +80,7 @@ To reconfigure the sample to use the fetch model, complete the following steps:
           - suit-send-sysinfo-success
           - suit-send-sysinfo-failure
 
-   This instructs the SUIT processor to execute the ``suit-payload-fetch`` in the application manifest, which will be added in the next step.
+   This instructs the SUIT processor to execute the ``suit-payload-fetch`` sequence in the application manifest, which will be added in the next step.
 
 #. Modify the application manifest :file:`app_envelope.yaml.jinja2` by completing the following:
 
@@ -110,13 +110,6 @@ To reconfigure the sample to use the fetch model, complete the following steps:
          - suit-directive-fetch:
            - suit-send-record-failure
 
-   #. Modify the ``suit-install`` sequence to use an identical URI, (as in the ``suit-payload-fetch``), instead of the integrated one:
-
-     The SUIT procedure attempts to use all fetch sources registered with :c:func:`suit_dfu_fetch_source_register` until one of them fetches the payload.
-     If no sources are able to fetch the payload, the update process ends with an error.
-
-     The reference SMP fetch source implementation only recognizes URIs that start with ``file://``.
-
    #. Modify the ``suit-install`` sequence to use an identical URI, as in the ``suit-payload-fetch``, instead of the integrated one.
 
       .. code-block:: diff
@@ -130,8 +123,13 @@ To reconfigure the sample to use the fetch model, complete the following steps:
            - suit-directive-fetch:
              - suit-send-record-failure
 
-     When the secure domain firmware processes the ``suit-install`` sequence, this sequence of directives instructs the secure domain to search for a payload with a given URI in all cache partitions.
-     If no such payload is found, the update process ends with an error.
+      The SUIT procedure attempts to use all fetch sources registered with :c:func:`suit_dfu_fetch_source_register` until one of them fetches the payload.
+      If no sources are able to fetch the payload, the update process ends with an error.
+
+      The reference SMP fetch source implementation only recognizes URIs that start with ``file://``.
+
+      When the secure domain firmware processes the ``suit-install`` sequence, this sequence of directives instructs the secure domain to search for a payload with a given URI in all cache partitions.
+      If no such payload is found, the update process ends with an error.
 
 
    #. Remove the application binary from the integrated payloads:
@@ -142,8 +140,8 @@ To reconfigure the sample to use the fetch model, complete the following steps:
          -   '#{{ app['name'] }}': {{ app['binary'] }}
          + suit-integrated-payloads: {}
 
-     In the fetch model-based firmware upgrade, it is not necessary to integrate the payload into the envelope.
-     However, you may still choose to integrate certain payloads.
+      In the fetch model-based firmware upgrade, it is not necessary to integrate the payload into the envelope.
+      However, you may still choose to integrate certain payloads.
 
 Creating a custom fetch source
 ******************************

samples/suit/flash_companion/README.rst

@@ -78,7 +78,7 @@ Perform the following steps in the main application directory:
                reg = <0xa6000 DT_SIZE_K(448)>;
             };
             companion_partition: partition@116000 {
-               reg = <0x116000 DT_SIZE_K(64)>;
+               reg = <0x116000 DT_SIZE_K(36)>;
             };
          };
 
@@ -95,13 +95,14 @@ Perform the following steps in the main application directory:
             status = "okay";
          };
 
-#. Build the main application:
+#. Build and flash the main application:
 
    .. code-block:: console
 
       $ west build -b nrf54h20dk/nrf54h20/cpuapp --sysbuild
+      $ west flash
 
-The flash companion sample will be built automatically by Sysbuild.
+The flash companion sample will be built and flashed automatically by Sysbuild.
 
 Dependencies
 ************