DFU Multi-image

The DFU Multi-image sample demonstrates the use of the Device Firmware Update (DFU) multi-image functionality in the nRF Connect SDK. Currently, it only supports DFU targets for MCUboot as its backend.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target
nRF54H20 DK	PCA10175	nrf54h20dk	nrf54h20dk/nrf54h20/cpuapp
nRF5340 DK	PCA10095	nrf5340dk	nrf5340dk/nrf5340/cpuapp

Overview

The sample does not include a transport layer for uploading a new image. Instead, a partition labeled dfu_multi_image_helper is reserved in the board overlays.

Note

You must manually upload an image to this partition using nrfutil device command.

Once the image has been uploaded, you can use the shell commands from the dfu_multi_image group provided by this sample to test DFU multi image operations.

User interface

The sample’s interface is implemented using shell commands, which are accessible through the serial port.

Building and running

This sample can be found under samples/dfu/dfu_multi_image in the nRF Connect SDK folder structure.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Testing

After programming the sample to your development kit, complete the following steps to test it:

1. Connect to the kit that runs this sample with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.

2. Reset the development kit.

3. Observe the following message on the terminal of the application core:

   Starting dfu_multi_image sample, build time: <BUILD TIME>
   

   And the following message on the terminal of the network core:

   Network core build time: <BUILD_TIME>
   

   <BUILD TIME> indicates the build time. It will be used later to verify the update.

4. Build a second version of the sample. For simplicity, it is assumed to be built in the build_v2 directory.

5. Use the arm-zephyr-eabi-objcopy command to link the contents of the dfu_multi_image.bin file to the appropriate address:

   arm-zephyr-eabi-objcopy -I binary -O ihex --change-address <DFU_MULTI_IMAGE_HELPER_ADDRESS> build_v2/dfu_multi_image.bin package_v2.hex
   

   Replace <DFU_MULTI_IMAGE_HELPER_ADDRESS> with the address of the dfu_multi_image_helper partition. Specifically, the address values are the following:

   Development kit	Address
   nRF5340 DK	0xb8000
   nRF54H20 DK	0xe134000

6. Upload the second version of the images to the device using nrfutil device:

   nrfutil device program --firmware package_v2.hex  --options chip_erase_mode=ERASE_NONE
   

7. Reset the development kit.

8. Perform the update using one of the following methods:

   • Single-step update, running the following command:

     dfu_multi_image full_update <package_size>
     

     <package_size> is the size, in bytes, of the file build_v2/dfu_multi_image.bin.

   • Step-by-step update:

     1. Write the image either at once or in chunks:

        • To write the entire image at once, run the following command:

          dfu_multi_image write 0 0 <package_size>
          

          <package_size> is the size, in bytes, of the file build_v2/dfu_multi_image.bin.

        • To write the image in chunks, run the following commands as many times as there are chunks:

          dfu_multi_image write <read_offset> <write_offset> <chunk_size>
          

          The <read_offset> is the offset in the dfu_multi_image_helper partition from which a chunk of data is read. The <write_offset> is the offset to pass to the DFU multi-image library, representing the offset in the package. This is useful when skipping some of the images. See the documentation of the dfu_multi_image_write function in the dfu_multi_image.h file for more details.

     2. If the write commands for all chunks complete without errors, finish writing with dfu_multi_image done success command.

     3. Schedule the update for the next reboot using dfu_multi_image schedule_update command.

     4. Reboot the device.

9. After the update completes, observe the following message on the terminal of the application core:

   Starting dfu_multi_image sample, build time: <BUILD TIME>
   

   Observe the following message on the terminal of the network core:

   Network core build time: <BUILD_TIME>
   

   The build time should reflect the new version in both cases.

10. To make the update permanent, use the dfu_multi_image mcuboot_confirm <image_number> command. This step is optional and not applicable to the nRF5340 DK. <image_number> is 0 for the application core and 1 for the network core. Without this step, any image that is not confirmed will revert to the previous image on the next reboot.

Dependencies

This sample uses the following nRF Connect SDK libraries:

• DFU target

• DFU multi-image

• MCUboot