diff --git a/doc/nrf/app_dev/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_dfu.rst b/doc/nrf/app_dev/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_dfu.rst index 5601cb5e2ee1..b466fdbdacc4 100644 --- a/doc/nrf/app_dev/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_dfu.rst +++ b/doc/nrf/app_dev/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_dfu.rst @@ -27,6 +27,7 @@ For a list of available SUIT samples, see the :ref:`suit_samples` page. ug_nrf54h20_suit_device_config.rst ug_nrf54h20_suit_customize_qsg.rst ug_nrf54h20_suit_customize_dfu.rst + ug_nrf54h20_suit_smp.rst ug_nrf54h20_suit_fetch ug_nrf54h20_suit_push ug_nrf54h20_suit_external_memory diff --git a/doc/nrf/app_dev/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_smp.rst b/doc/nrf/app_dev/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_smp.rst new file mode 100644 index 000000000000..0d7e0194696e --- /dev/null +++ b/doc/nrf/app_dev/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_smp.rst @@ -0,0 +1,224 @@ +.. _ug_nrf54h20_suit_smp: + +SUIT and SMP protocol (including SUIT SMP extension) +#################################################### + +.. contents:: + :local: + :depth: 2 + +Adopting SUIT as a firmware update method offers a flexible and extensible update process. +This document illustrates how the Zephyr management subsystem, via the SMP protocol, can be leveraged to manage SUIT-based images alongside existing MCUBoot images, providing an efficient approach to firmware management. + +Slots and Images in Zephyr +========================== + +In the nRF Connect SDK, *slot* and *image* concepts are derived from MCUboot. +An *image* consists of two slots: a *primary* and a *secondary*. +The application runs from the primary slot, while updates are uploaded to the secondary slot. +MCUboot is responsible for swapping these slots during boot. + +The slots support a single upgradable application, with equal sizes. +Zephyr supports up to two images, each represented by an index. + +.. note:: + Image metadata, such as version information, is embedded within the image payload. + +Components in SUIT +================== + +SUIT defines a *component* as an updatable logical block, which can be firmware, software, configuration, or data. +This is similar to how MCUmgr defines an *image*. +Updates are delivered to the device as a SUIT *envelope,* containing SUIT manifests and, optionally, integrated payloads. +The relationships between components are maintained through SUIT manifests. + +The SUIT envelope serves as the main metadata source for the payload. +Adding metadata inside the image can lead to synchronization issues, as the lifecycles of the envelope and image may diverge. +Therefore, manage metadata at the envelope level. + +MCUmgr and SUIT - Key Similarities and Differences +=================================================== + +The following table summarizes key similarities and differences between MCUmgr and SUIT: + ++-----------------------------+-------------------------+----------------------------------+ +| Feature | MCUmgr | SUIT | ++=============================+=========================+==================================+ +| Metadata | Attached to the images | Defined by a separate SUIT | +| | | manifest | ++-----------------------------+-------------------------+----------------------------------+ +| Image Topology | Slots (primary, | Tree structure with manifests | +| | secondary) organized as | grouped into a hierarchical tree | +| | a list | | ++-----------------------------+-------------------------+----------------------------------+ +| Slot/Image Configuration | Slots defined in | Slot definitions can be modified | +| | MCUboot; difficult to | via the SUIT manifest, allowing | +| | change after deployment | greater flexibility | ++-----------------------------+-------------------------+----------------------------------+ +| Installation/Boot | Limited by static | Fully customizable through SUIT | +| Customization | image metadata | manifest directives | ++-----------------------------+-------------------------+----------------------------------+ + +Versioning Information +---------------------- + +MCUmgr and SUIT use different structures for versioning: + +- MCUmgr: Uses ``struct image_version`` with fields for ``major``, ``minor``, ``revision``, and ``build_num``. +- SUIT: Utilizes a manifest sequence number. + +State Information +----------------- + +- MCUmgr: Update state is embedded within the image slot metadata. +- SUIT: Update candidate existence is represented within the SUIT manifest. + +Using MCUmgr SMP Protocol with SUIT +=================================== + +Get State of Images Request +--------------------------- + +This command retrieves images and their states. +The response is in CBOR format: + +.. code-block:: cbor + + { + *images*: [ + { + *image*: 0, // SUIT - always 0, as the system is represented as a *single image* + *slot*: 0, // 0 for primary (installed), 1 for secondary (update candidate) + *version*: *v1.0.0*, // Sequence number from root manifest + *hash*: **, // Digest of root manifest + *bootable*: true, // Root manifest is always bootable + *pending*: true, // True if an update candidate is delivered + *confirmed*: false, // Not applicable for SUIT (no rollback) + *active*: false, // Not applicable for SUIT manifests + *permanent*: false // Not applicable for SUIT + } + ] + } + +Set State of Image Request +-------------------------- + +This command is not applicable to SUIT since it does not support slot swapping or rollback. + +Image Upload Request +-------------------- + +This command uploads an image to the device. +Payloads for all SUIT components are delivered integrally. +The CBOR data format is: + +.. code-block:: cbor + + { + *image*: 0, // SUIT - always 0 as a *single image* + *len*: , + *off*: , + *sha*: **, + *data*: + } + +Image Erase Request +------------------- + +This command clears the content of the DFU partition when using SUIT. + +Feasibility Analysis +==================== + +The following table describes the feasibility of using existing tools to work with SUIT: + ++-----------------------------+--------------------------------------+--------------------------------+ +| Tool | Get State of Images Request | Image Upload | ++=============================+======================================+================================+ +| Android Device Manager Tool | Supports version info retrieval; | Does not support non-MCUboot | +| | unsupported flags are displayed as | compatible files. | +| | false. | | ++-----------------------------+--------------------------------------+--------------------------------+ +| MCUmgr Command Line Tool | Works as expected; supports strings | Accepts files that are not | +| | for version information. | MCUboot compatible. | ++-----------------------------+--------------------------------------+--------------------------------+ +| Zephyr | Support for SUIT to be implemented | | +| | in ``zephyr/subsys/mgmt/mcumgr/lib/ | | +| | cmd/img_mgmt``. | | ++-----------------------------+--------------------------------------+--------------------------------+ + +SUIT SMP Protocol Extension +=========================== + +The existing image management approach works well for basic scenarios involving single-step SUIT envelope pushes. +More advanced scenarios require defining a new SMP management group. + +Management Group ID +------------------- + +The new SUIT SMP protocol will use ``MGMT_GROUP_ID_PERUSER + 2`` (i.e., 66), as ``MGMT_GROUP_ID_PERUSER + 1`` is already allocated for Full Modem Firmware Update for nRF9160. + +Commands +-------- + +Get SUIT Manifests List Request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command retrieves the roles of the manifests supported by the device. + +Command ID: 0 + +CBOR Data of Successful Response: + +.. code-block:: cbor + + { + *rc*: 0, + *manifests*: [ + { + *role*: // Manifest role encoded as domain ID and index + } + ] + } + +Get SUIT Manifest State Request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command provides information about a specific manifest, including configuration and selected attributes. + +Command ID: 1 + +CBOR Data of Successful Response: + +.. code-block:: cbor + + { + *rc*: 0, + *class_id*: **, + *vendor_id*: **, + *downgrade_prevention_policy*: , + *independent_updateability_policy*: , + *signature_verification_policy*: , + *digest*: **, + *digest_algorithm*: , + *signature_check*: , + *sequence_number*: , + *semantic_version*: [, , , , ] + } + +Additional Commands +------------------- + +- Candidate Envelope Upload Request (Command ID: 2): Uploads a SUIT envelope to the device. +- Get Missing Image State Request (Command ID: 3): Retrieves information about images that need to be updated. +- Image Upload Request (Command ID: 4): Used for uploading a requested image. +- Cache Raw Image Upload Request (Command ID: 5): Uploads an image to a specified cache pool. +- Cleanup Request (Command ID: 6): Clears the DFU and cache partitions. + +Return Codes +------------ + +Each command may return specific status codes, including: + +- ``MGMT_ERR_ENOTSUP``: Unsupported command. +- ``MGMT_ERR_EMSGSIZE``: Unable to encode the response due to insufficient RAM buffer size.