diff --git a/doc/nrf/config_and_build/configuring_app/output_build_files.rst b/doc/nrf/config_and_build/configuring_app/output_build_files.rst index 87af63897428..953c822c9661 100644 --- a/doc/nrf/config_and_build/configuring_app/output_build_files.rst +++ b/doc/nrf/config_and_build/configuring_app/output_build_files.rst @@ -148,6 +148,29 @@ MCUboot output build files | | Created when the :kconfig:option:`CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT` Kconfig option is enabled. | +------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. _app_build_output_files_suit_dfu: + +SUIT output build files +*********************** + +The following table lists secondary build files that can be generated when building firmware update packages using the :ref:`Software Updates for Internet of Things (SUIT) DFU procedure `. + ++------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| File | Description | ++================================================+========================================================================================================================================================================+ +| :file:`root_hierarchical_envelope.yaml.jinja2` | SUIT Manifest templates automatically placed in the sample directory after the first build of the ``nrf54h_suit_sample`` sample. | +| | They serve as the basis for generating the specific SUIT envelopes tailored to the requirements of different domains within the device (root, application, and radio). | +| :file:`app_envelope.yaml.jinja2` | | +| | | +| :file:`rad_envelope.yaml.jinja2` | | ++------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :file:`root.suit` | Binary SUIT envelopes that are generated from their respective YAML manifest templates during the build process of the ``nrf54h_suit_sample`` sample. | +| | The :file:`root.suit` contains embedded application core manifest (:file:`application.suit`) and radio core manifest (:file:`radio.suit`). | +| :file:`application.suit` | The :file:`radio.suit` is not generated for the UART version of the ``nrf54h_suit_sample``. | +| | These files can be found in the :file:`build/zephyr` directory after building the sample. | +| :file:`radio.suit` | | ++------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + .. _app_build_output_files_other: Other output build files diff --git a/doc/nrf/images/suit_smp_firmware_upload_complete.png b/doc/nrf/images/suit_smp_firmware_upload_complete.png new file mode 100644 index 000000000000..9257fbe7f973 Binary files /dev/null and b/doc/nrf/images/suit_smp_firmware_upload_complete.png differ diff --git a/doc/nrf/images/suit_smp_firmware_uploading.png b/doc/nrf/images/suit_smp_firmware_uploading.png new file mode 100644 index 000000000000..fa5bd1d220e4 Binary files /dev/null and b/doc/nrf/images/suit_smp_firmware_uploading.png differ diff --git a/doc/nrf/images/suit_smp_images_v2.png b/doc/nrf/images/suit_smp_images_v2.png new file mode 100644 index 000000000000..3fecf44bb232 Binary files /dev/null and b/doc/nrf/images/suit_smp_images_v2.png differ diff --git a/doc/nrf/images/suit_smp_select_advanced.png b/doc/nrf/images/suit_smp_select_advanced.png new file mode 100644 index 000000000000..022b5298dc37 Binary files /dev/null and b/doc/nrf/images/suit_smp_select_advanced.png differ diff --git a/doc/nrf/images/suit_smp_select_firmware_select_file.png b/doc/nrf/images/suit_smp_select_firmware_select_file.png new file mode 100644 index 000000000000..6d437462ee0c Binary files /dev/null and b/doc/nrf/images/suit_smp_select_firmware_select_file.png differ diff --git a/doc/nrf/images/suit_smp_select_image_read.png b/doc/nrf/images/suit_smp_select_image_read.png new file mode 100644 index 000000000000..3529ad3277f6 Binary files /dev/null and b/doc/nrf/images/suit_smp_select_image_read.png differ diff --git a/doc/nrf/images/suit_smp_select_suit_smp_sample.png b/doc/nrf/images/suit_smp_select_suit_smp_sample.png new file mode 100644 index 000000000000..163a8511619e Binary files /dev/null and b/doc/nrf/images/suit_smp_select_suit_smp_sample.png differ diff --git a/samples/suit/smp_transfer/README.rst b/samples/suit/smp_transfer/README.rst new file mode 100644 index 000000000000..2c5ae3cd5d91 --- /dev/null +++ b/samples/suit/smp_transfer/README.rst @@ -0,0 +1,394 @@ +:orphan: + +.. _nrf54h_suit_sample: + +SUIT DFU: Firmware update on the nRF54H20 SoC +############################################# + +.. contents:: + :local: + :depth: 2 + +The sample demonstrates how to update and boot the nRF54H20 System-on-Chip (SoC) using the Software Update for Internet of Things (SUIT) procedure on the application and radio cores of the SoC. +The update on the nRF54H20 SoC can be done over Bluetooth® Low Energy or UART. + +Requirements +************ + +The sample supports the following development kit: + +.. table-from-rows:: /includes/sample_board_rows.txt + :header: heading + :rows: nrf54h20dk_nrf54h20_cpuapp + +You need the nRF Device Manager app for SUIT update over Bluetooth Low Energy: + +* `nRF Device Manager mobile app for Android`_ + (The minimum required version is v1.9.) + +* `nRF Device Manager mobile app for iOS`_ + (The minimum required version is v1.5.) + +For a SUIT update over UART, you need to install MCUmgr. +MCUmgr is a tool that can be used to upload SUIT envelopes through the SMP protocol. +For more information on MCUmgr installation, see :ref:`zephyr:mcu_mgr`. + +Overview +******** + +The sample uses one of the following methods to perform a firmware update on the nRF54H20 SoC, featuring Nordic Semiconductor’s implementation of the SUIT procedure: + +* Bluetooth Low Energy and the nRF Device Manager app +* UART and MCUmgr + +The sample demonstrates how to perform a DFU of the application and radio firmware. + +SUIT is the only DFU procedure supported for the nRF54H20 SoCs. +To read more about the SUIT procedure, see :ref:`ug_nrf54h20_suit_intro`. + +|NCS|-specific SUIT limitations +=============================== + +The sample and the SUIT DFU procedure currently only support the application core and the radio core firmware updates. +Additionally, this sample is an early version and is only meant to showcase the start of Nordic Semiconductor’s implementation of the SUIT DFU procedure. + +User interface +************** + +LED 1: + The number of blinks indicates the application SUIT envelope sequence number. + The default is set to ``1`` to blink once, indicating "Version 1". + +Configuration +************* + +|config| + +The default configuration uses UART with sequence number 1 (shown as Version 1 in the nRF Device Manager app). +To change the sequence number of the application, configure the :ref:`CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM` Kconfig option. +This also changes the number of blinks on **LED 1** and sets the :ref:`sequence number ` of the SUIT :ref:`envelope `’s manifest. + +To use this configuration, include the ``SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=x`` option with the build command, where x is the version number. + +For example: + +.. code-block:: console + + west build -p -b nrf54h20dk/nrf54h20/cpuapp --sysbuild -- -SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=2 + +If you do not specify this configuration, the sample is built with sequence number 1 (shown as Version 1 in the nRF Device Manager app. + +Configuration options +===================== + +Check and configure the following configuration option for the sample: + +.. _CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM: + +CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM - Configuration for the sequence number. + The sample configuration updates the sequence number of the SUIT envelope, which is reflected as the version of the application in the nRF Device Manager app. + The default value is ``1``. + +Modify partition sizes +====================== + +You can also modify the size and location of the partitions. +This is done by modifying the values for the desired location and size of the partition in the devicetree :file:`.overlay` files. + +* To modify the application core’s partition size, modify the values for ``cpuapp_slot0_partition`` defined in the :file:`zephyr/blob/main/boards/nordic/nrf54h20dk/nrf54h20dk_nrf54h20-memory_map.dtsi` file within the Zephyr repository. + +* To modify the DFU partition, modify the values for ``dfu_partition`` defined in :file:`samples/suit/smp_transfer/boards/nrf54h20dk_nrf54h20_cpuapp.overlay`. + + * ``dfu_partition`` is where the update candidate is stored before the update process begins. + +Manifest files +============== + +The SUIT DFU procedure requires an envelope to transport the firmware update, and SUIT envelopes require a SUIT manifest. +All required manifest files (used to later create SUIT envelopes) are automatically created after the sample is built for the first time, and are the following: + +* The root manifest - :file:`root_hierarchical_envelope.yaml.jinja2` + +* The application domain manifest - :file:`app_envelope.yaml.jinja2` + +* The radio domain manifest - :file:`rad_envelope.yaml.jinja2` + +.. note:: + + The radio domain manifest template (:file:`radio.suit`) is only created when building the Bluetooth Low Energy version of the sample, and not the UART version. + Currently, it is not needed for the UART version. + +If you want to make modifications to how the DFU is executed in this sample, you can do so by editing the manifest templates, or generating your own custom manifests. +See the :ref:`ug_nrf54h20_suit_customize_dfu` user guide for instructions and examples. + +Building and running +******************** + +.. |sample path| replace:: :file:`samples/suit/smp_transfer` + +This sample can be found under |sample path| in the |NCS| folder structure. + +.. include:: /includes/build_and_run.txt + + +Building and programming using the command line +=============================================== + +To build and program the sample to the nRF54H20 DK, complete the following steps: + +.. tabs:: + + .. group-tab:: Over Bluetooth Low Energy + + 1. Open a terminal window in |sample path|. + #. Build the sample using the following ``west`` command, with the following Kconfig options set: + + .. code-block:: console + + west build -p -b nrf54h20dk/nrf54h20/cpuapp --sysbuild -- -DFILE_SUFFIX=bt -SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=1 + + .. note:: + + |application_sample_long_path_windows| + + In this case, you may need to run the following instead: + + .. code-block:: console + + west build -p -b nrf54h20dk/nrf54h20/cpuapp -d C:/ncs-lcs/work-dir --sysbuild -- -DFILE_SUFFIX=bt -SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=1 + + The output build files can be found in the :file:`build/DFU` directory. + The following build artifacts are found with both firmware binaries embedded as integrated payloads: + + * :file:`root.suit` - This file is the most important envelope, containing the embedded :file:`application.suit` and :file:`radio.suit` files as integrated dependencies. + These files are used to execute DFU. + * :file:`application.suit` - This file is the envelope for the application core, containing embedded application core firmware as an integrated payload. + * :file:`radio.suit` - This file is the envelope for the radio core, containing embedded radio core firmware as an integrated payload. + + For more information about files generated as output of the build process, see :ref:`app_build_output_files`, specifically :ref:`app_build_output_files_suit_dfu`. + For more information on the contents of the build directory, see :ref:`zephyr:build-directory-contents` in the Zephyr documentation. + For more information on the directory contents and structure provided by Sysbuild, see :ref:`zephyr:sysbuild` in the Zephyr documentation. + + #. Connect the DK to your computer using a USB cable. + #. Power on the DK. + #. Program the sample to the kit (see :ref:`programming_cmd` for instructions). + + .. note:: + + |application_sample_long_path_windows| + + In this case, you may need to run the following instead: + + .. code-block:: console + + west flash --erase -d C:/ncs-lcs/work-dir + + #. Update the SUIT envelope sequence number, by rebuilding the sample with an updated sequence number: + + .. code-block:: console + + west build -p -b nrf54h20dk/nrf54h20/cpuapp --sysbuild -- -DFILE_SUFFIX=bt -SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=2 + + .. note:: + + |application_sample_long_path_windows| + + In this case, you may need to run the following instead: + + .. code-block:: console + + west build -p -b --sysbuild nrf54h20dk/nrf54h20/cpuapp -d C:/ncs-lcs/work-dir -- -DFILE_SUFFIX=bt -SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=2 + + Another :file:`root.suit` file is created after running this command, that contains the updated firmware. + You must manually transfer this file onto the same mobile device you will use with the nRF Device Manager app. + + .. group-tab:: Over UART + + 1. Open a terminal window in |sample path|. + #. Build the sample: + + .. code-block:: console + + west build -p -b --sysbuild nrf54h20dk/nrf54h20/cpuapp + + .. note:: + + |application_sample_long_path_windows| + + In this case, you may need to run the following instead: + + .. code-block:: console + + west build -p -b --sysbuild nrf54h20dk/nrf54h20/cpuapp -d C:\ncs-lcs\west_working_dir\build\ + + If you want to further configure your sample, see :ref:`configure_application` for additional information. + + After running the ``west build`` command, the output build files can be found in the :file:`build/dfu` directory. + The following build artifacts are found with both firmware binaries embedded as integrated payloads: + + * :file:`root.suit` - This file is the most important envelope, containing embedded :file:`app.suit` as an integrated dependency. + This file is used to execute DFU. + * :file:`application.suit` - This file is the envelope for the application core, containing embedded application core firmware as an integrated payload. + + For more information about files generated as output of the build process, see :ref:`app_build_output_files`, specifically :ref:`app_build_output_files_suit_dfu`. + For more information on the contents of the build directory, see :ref:`zephyr:build-directory-contents` in the Zephyr documentation. + For more information on the directory contents and structure provided by Sysbuild, see :ref:`zephyr:sysbuild` in the Zephyr documentation.. + + #. Connect the DK to your computer using a USB cable. + #. Power on the DK. + #. Program the sample to the kit (see :ref:`programming_cmd` for instructions). + + .. note:: + + |application_sample_long_path_windows| + + In this case, you may need to run the following instead: + + .. code-block:: console + + west flash --erase -d C:/ncs-lcs/work-dir + + #. Update the SUIT envelope sequence number, by rebuilding the sample with an updated sequence number: + + .. code-block:: console + + west build -p -b nrf54h20dk/nrf54h20/cpuapp --sysbuild -- -SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=2 + + .. note:: + + |application_sample_long_path_windows| + + In this case, you may need to run the following instead: + + .. code-block:: console + + west build -p -b nrf54h20dk/nrf54h20/cpuapp -d C:/ncs-lcs/work-dir --sysbuild -- -SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=2 + + Another :file:`root.suit` file is created after running this command, that contains the updated firmware. + +Testing +======= + +After programming the sample to your development kit and updating the sequence number of the SUIT envelope, complete the following steps to test it. + +.. tabs:: + + .. group-tab:: Over Bluetooth Low Energy + + 1. Upload the signed envelope onto your mobile phone: + + a. Open the nRF Device Manager app on your mobile phone. + #. Select the device **SUIT SMP Sample**. You should see the following: + + .. figure:: /images/suit_smp_select_suit_smp_sample.png + :alt: Select SUIT SMP Sample + + #. From the **SUIT SMP Sample** screen, on the **Images** tab at the bottom of the screen, click on :guilabel:`ADVANCED` in the upper right corner of the app to open a new section called **Images**. + + .. figure:: /images/suit_smp_select_advanced.png + :alt: Select ADVANCED + + #. Click on the :guilabel:`READ` button within the **Images** section. + + .. figure:: /images/suit_smp_select_image_read.png + :alt: Select READ from Images + + You should now see that "Version: 1" is printed in the **Images** section of the mobile app. + + #. From the **Firmware Upload** section, click on :guilabel:`SELECT FILE` and select the :file:`root.suit` file from your mobile device. + + .. note:: + As described in Step 1, you must manually add the :file:`root.suit` file to the same mobile device you are using for nRF Device Manager. + + .. figure:: /images/suit_smp_select_firmware_select_file.png + :alt: Select Firmware Upload and Select File + + #. Click on :guilabel:`UPLOAD` to reveal the **Select Image** menu. + + #. From the **Select Image** menu, select :guilabel:`Application Core (0)` and click the :guilabel:`OK` button to upload the :file:`root.suit` file. + + You should see an upload progress bar below the "UPLOADING…" text in the **Firmware Upload** section. + + .. figure:: /images/suit_smp_firmware_uploading.png + :alt: Firmware UPLOADING + + + The text "UPLOAD COMPLETE" appears in the **Firmware Upload** section once completed. + + .. figure:: /images/suit_smp_firmware_upload_complete.png + :alt: Firmware UPLOAD COMPLETE + + #. Reconnect your device. + #. Select the device **SUIT SMP Sample** once again. + + .. figure:: /images/suit_smp_images_v2.png + :alt: Images Version 2 + + #. Under the **Images** section, click on :guilabel:`READ`. + + You should see that "Version: 2" is now printed in the **Images** section of the mobile app. + + Additional, **LED 1** now flashes twice now to indicate "Version 2" of the firmware. + + .. group-tab:: Over UART + + 1. Upload the signed envelope: + + a. Read the version and digest of the installed root manifest with MCUmgr: + + .. code-block:: console + + mcumgr --conntype serial --connstring "dev=/dev/ttyACM0,baud=115200,mtu=512" image list + + You should see an output similar to the following logged on UART: + + .. parsed-literal:: + :class: highlight + + image=0 slot=0 + version: 1 + bootable: true + flags: active confirmed permanent + hash: d496cdc8fa4969d271204e8c42c86c7499ae8632f131e098e2e0fb5c7bbe3a5f + Split status: N/A (0) + + #. Upload the image with MCUmgr: + + .. code-block:: console + + mcumgr --conntype serial --connstring "dev=/dev/ttyACM0,baud=115200,mtu=512" image upload root.suit + + You should see an output similar to the following logged on UART: + + .. parsed-literal:: + :class: highlight + + 0 / 250443 [---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------] 0.00% + 18.99 KiB / 244.57 KiB [============>-------------------------------------------------------------------------------------------------------------------------------------------------] 7.76% 11.83 KiB/s 00m19s + 66.56 KiB / 244.57 KiB [==========================================>-------------------------------------------------------------------------------------------------------------------] 27.21% 18.44 KiB/s 00m09s + 112.12 KiB / 244.57 KiB [=======================================================================>-------------------------------------------------------------------------------------] 45.84% 19.97 KiB/s 00m06s + 154.08 KiB / 244.57 KiB [==================================================================================================>----------------------------------------------------------] 63.00% 20.22 KiB/s 00m04s + 197.40 KiB / 244.57 KiB [==============================================================================================================================>------------------------------] 80.71% 20.51 KiB/s 00m02s + 241.16 KiB / 244.57 KiB [=================================================================================================================================================================>--] 98.60% 20.74 KiB/s + Done + + #. Read the version and digest of the uploaded root manifest with MCUmgr: + + .. code-block:: console + + mcumgr --conntype serial --connstring "dev=/dev/ttyACM0,baud=115200,mtu=512" image list + + + You should see an output similar to the following logged on UART: + + .. parsed-literal:: + :class: highlight + + image=0 slot=0 + version: 2 + bootable: true + flags: active confirmed permanent + hash: 707efbd3e3dfcbda1c0ce72f069a55f35c30836b79ab8132556ed92ce609f943 + Split status: N/A (0) + + You should now see that **LED 1** flashes twice now to indicate "Version 2" of the firmware.