Merge pull request #133 from NordicSemiconductor/documentation/suit

Documentation improved with regard of SUIT support
NordicSemiconductor · Dec 7, 2023 · 969e0ee · 969e0ee
2 parents 7a3dba8 + 49379d3
commit 969e0ee
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 4 deletions.
diff --git a/mcumgr-core/src/main/java/io/runtime/mcumgr/dfu/FirmwareUpgradeManager.java b/mcumgr-core/src/main/java/io/runtime/mcumgr/dfu/FirmwareUpgradeManager.java
@@ -153,6 +153,10 @@ public Builder(@NotNull final McuMgrTransport transport) {
              * it actually working correctly. This is important with
              * {@link FirmwareUpgradeManager.Mode#TEST_AND_CONFIRM} mode, which
              * reconnects to the device after it resets.
+             * <p>
+             * This value is ignored when the target device supports SUIT (Software Update for
+             * Internet of Things).
+             * </p>
              * @param time the swap time in milliseconds.
              * @return The builder.
              */
@@ -322,6 +326,9 @@ public void setFirmwareUpgradeCallback(@Nullable final FirmwareUpgradeCallback c
     /**
      * Sets the manager mode. By default the {@link Mode#TEST_AND_CONFIRM} mode is used.
      * The mode may be set only before calling {@link #start(byte[])} method.
+     * <p>
+     * This value is ignored when the target device supports SUIT (Software Update for
+     * Internet of Things).
      *
      * @param mode the manager mode.
      * @see Mode#TEST_ONLY
@@ -344,6 +351,9 @@ public void setMode(@NotNull final Mode mode) {
      * <p>
      * For DFU modes without swapping, i.e. Direct XIP with or without revert, this value can be
      * set to 0, as there is no swap.
+     * <p>
+     * This value is ignored when the target device supports SUIT (Software Update for
+     * Internet of Things).
      *
      * @param swapTime estimated time required for swapping images, in milliseconds. 0 by default.
      */
@@ -418,6 +428,8 @@ public void setMemoryAlignment(final int alignment) {
      * boot with the new firmware. The manager will try to connect to the SMP server on the new
      * firmware and confirm the new images if they were not confirmed before, or they didn't confirm
      * automatically.
+     * <p>
+     * This method should be used for SUIT files.
      */
     public synchronized void start(final byte @NotNull [] imageData) throws McuMgrException {
         start(new McuMgrImageSet().add(imageData), false);
@@ -436,7 +448,8 @@ public synchronized void start(final byte @NotNull [] imageData) throws McuMgrEx
      * automatically.
      *
      * @param images       list of images with image index.
-     * @param eraseStorage should the app settings be erased, or not (default true).
+     * @param eraseStorage should the app settings be erased, or not (default true). This param
+     *                     is ignored in case of SUIT files.
      * @deprecated Use {@link #start(McuMgrImageSet, boolean)} instead.
      */
     @Deprecated(since = "1.8")
@@ -459,7 +472,8 @@ public synchronized void start(@NotNull final List<Pair<Integer, byte[]>> images
      *
      * @param images       set of images. For direct XIP this set should contain images compiled
      *                     for both slots. The correct image will be chosen automatically.
-     * @param eraseStorage should the app settings be erased, or not (default true).
+     * @param eraseStorage should the app settings be erased, or not (default true). This param
+     *      *              is ignored in case of SUIT files.
      * @since 1.8
      */
     public synchronized void start(@NotNull final McuMgrImageSet images,

diff --git a/moustache/README.mo b/moustache/README.mo
@@ -157,13 +157,18 @@ The different firmware upgrade modes are as follows:
   command, and the bootloader is in DirectXIP without revert mode, this mode will be selected
   automatically. This mode was added in library version 1.8.
 
-> **Note**
+> [!Note]
 > Devices based on nRF5340 SoC support only `CONFIRM_ONLY` mode because the image from the
   Network Core cannot be read from the Application Core, making it impossible to temporarily save it.
 
-> **Note**
+> [!Note]
 > Read about MCUboot modes [here](https://docs.mcuboot.com/design.html#image-slots).
 
+### Software Update for Internet of Things (SUIT)
+
+Starting from version 1.9, the library supports SUIT (Software Update for Internet of Things) files.
+In this case the selected mode is ignored. The process of upgrading is embedded in the SUIT file.
+
 ### Firmware Upgrade State
 
 `FirmwareUpgradeManager` acts as a simple, mostly linear state machine which is determined by the `Mode`.