In this exercise, we will modify the previous exercise (DFU over UART) to use DFU over USB instead. We will also cover external flash and custom keys.

We will use the Zephyr CDC ACM drivers to communicate over USB. For more information on this, you can see USB device support.

Exercise steps

1. Open the code base of the exercise by navigating to Create a new application in the nRF Connect for VS Code extension, select Copy a sample, and search for Lesson 9 – Exercise 2. Exercise 2 base code is the Exercise 1 solution with comments renamed.

2. Enable CDC ACM for Serial Recovery.

To enable CDC ACM for Serial Recovery, add CONFIG_BOOT_SERIAL_CDC_ACM to child_image/mcuboot.conf.

CONFIG_BOOT_SERIAL_CDC_ACM=y

3. Increase the partition for the MCUboot bootloader.

The partition for the MCUboot bootloader is not large enough for MCUboot with CDC ACM and USB drivers. This size is 0xC000 by default. To increase this, set CONFIG_PM_PARTITION_SIZE_MCUBOOT to 0x10000 in child_image/mcuboot.conf. Or It is possible to make MCUboot take less space. See for example this samples child_image/mcuboot/prj_release.conf.

CONFIG_PM_PARTITION_SIZE_MCUBOOT=0x10000

4. Configure the application to use CDC ACM for DFU.

Next , we will change the application to use CDC ACM for DFU. The configuration we use here is inspired by the SMP Server sample.

4.1 As you can see. We have an app.overlay file in the application directory. This is one way to set devicetree overlays, but you can use other ways to do the same. In this app.overlay, we will first configure CDC ACM by adding the following:

/* Step 4.1 - Configure CDC ACM */
&zephyr_udc0 {
	cdc_acm_uart0: cdc_acm_uart0 {
		compatible = "zephyr,cdc-acm-uart";
	};
};

4.2 Then we point the uart-mcumgr driver to CDC ACM . by adding the line zephyr,uart-mcumgr = &cdc_acm_uart0; as chosen.

/* Step 4.2 - choose CDC ACM for mcumgr */
/ {
	chosen {
		zephyr,uart-mcumgr = &cdc_acm_uart0;
	};
};

4.3 Next, we will have to add Kconfig options to prj.conf:

# Step 4.3 - Enable USB subsystem
CONFIG_USB_DEVICE_STACK=y
CONFIG_UART_LINE_CTRL=y
CONFIG_USB_DEVICE_INITIALIZE_AT_BOOT=n

4.4 Lastly, USB must be enabled in our source files (main.c). First, include the header file for USB

/* STEP 4.4 - Include header for usb */
#include <zephyr/usb/usb_device.h>

4.5 Enable USB

 /* Step 4.5 - Enable USB */
	if (IS_ENABLED(CONFIG_USB_DEVICE_STACK)) {
		ret = usb_enable(NULL);
		if (ret) {
			return 0;
		}
	}

Testing

5. Build and flash the application to your board.

6. Connect your computer to the nRF USB port on the DK.

In this step, we will assume that the hardware has no Debugger/Interface MCU (IMCU) and we use the nRF USB port as the transport for the firmware images.

Disconnect your board from the regular Debugger USB port and connect to The nRF USB port. The nRF USB port is only available on the nRF5340 DK, nRF52840 DK, nRF52833 DK, and nRF7002 DK since it requires an nRF SoC with a USB peripheral. For a list of which SoCs contain a USB peripheral, check the Nordic product guide.

7. DFU over USB

7.1 The MCUmgr library will run in the background, letting you connect to the USB and do DFU while the application runs.

7.2 We can use mcumgr-cli to communicate with the DK. First, we will add a configuration to mcumgr-cli:

mcumgr conn add testDK type="serial" connstring="COM22,baud=115200,mtu=512"

“testDK” here can be named whatever we want. COM22 should be changed to whatever port the DKs nRF USB is connected to. Please note that the COM port for nRF USB will not be listed in nRF Connect for VS Code. Use Device Manager in Windows or equivalent on Linux/macOS to find the port allocated to nRF USB. A list of supported mcumgr-cli commands can be found here.

7.3 Check the listing of current images on the DK:

mcumgr -c testDK image list

This should return the slots available, as we have seen in the previous exercise.

7.4 Before we try to upload a new firmware image to the DK, we should change something in the code, so we can verify the change. This can, for example, be to change the delay in the blinky code. Then rebuild the code.

7.5 Now we can upload the new image firmware to the DK, using:

mcumgr -c testDK image upload build/zephyr/app_update.bin

Then this should be the result. The upload is done in a separate thread in the background. So the current firmware should be running as normal.

6.93 KiB / 42.01 KiB [====================>-------------------------------------------------------------------------------------------------------]  16.50% 3.14 KiB/s 00m11s

7.6 Since we use a dual slot configuration, the uploaded application does not automatically run. To make the application swap into the primary slot, we must tag it with either “test” or “confirm”. Let’s do “test” first. First, we need to get the hash of the image:

mcumgr -c testDK image list

Will return

Images:
 image=0 slot=0
    version: 0.0.0
    bootable: true
    flags: active confirmed
    hash: <OLD_HASH>
 image=0 slot=1
    version: 0.0.0
    bootable: true
    flags: 
    hash: <MEW_HASH>
Split status: N/A (0)

Then we use the <HASH> to tag that slot as test, and reset:

mcumgr -c testDK image test <NEW_HASH>
mcumgr -c testDK reset

The new image will be swapped into the primary slot and the old image to the secondary slot. We can check this with:

mcumgr -c testDK image list

Which should return:

Images:
 image=0 slot=0
    version: 0.0.0
    bootable: true
    flags: active
    hash: <NEW_HASH>
 image=0 slot=1
    version: 0.0.0
    bootable: true
    flags: confirmed
    hash: <OLD_HASH>
Split status: N/A (0)

If we reset the board again, we can, in the same way, see that the image swaps back to the old firmware. This is because we passed test not confirm to mcumgr.

Adding External Flash

8. To increase the flash available for the application, we can add an external flash.

The MCUboot secondary partition can then be placed in the external flash, increasing the available space for the application.

8.1 We can tell the partition manager that we are using an external flash. See External flash memory partitions. Then MCUboot will automatically be partitioned to use external flash for the mcuboot_seconary partition. To do this, set the chosen nordic,pm-ext-flash = &mx25r64; in both app.overlay and child_image/mcuboot.overlay:

/ {
	chosen {
		nordic,pm-ext-flash = &mx25r64;
	};
};

8.2 The QSPI drivers needed for external flash on our development kits are not always automatically added to the MCUboot child image. We will add these to child_image/mcuboot.conf:

CONFIG_NORDIC_QSPI_NOR=y

8.3 We also need to increase the number of sectors used by MCUboot now, as the partitions are larger:

# Step 8.3 - Increase number of sectors
CONFIG_BOOT_MAX_IMG_SECTORS=256

8.4 Connect your computer to the DK debug port again (not nRF USB), and build and flash the new firmware.

8.5 To verify that the partitions have moved, use the Memory Report:

9. Disconnect from the debug port and connect to nRF USB port, you can retest the DFU over USB with External Flash by redoing steps 7.2 – 7.5.

nRF5340 update

The application core of the nRF5340 can be updated, as explained above.

When doing DFU from the application, no extra configurations are needed to update the network core. Another DFU package file must be used for the network core. Instead of app_update.bin, use net_core_app_update.bin.

However, for Serial Recovery, some extra configurations are needed to update the network core. The needed configurations are listed in our docs on Developing with nRF5340 DK: MCUboot’s serial recovery of the networking core image.

Custom key

The more observant readers might have noticed the following warning from the build logs so far:

      ---------------------------------------------------------
      --- WARNING: Using default MCUBoot key, it should not ---
      --- be used for production.                           ---
      ---------------------------------------------------------

When building for MCUboot, a default key is used to ease development. For production, it is extremely important to use your own key instead. If not, anyone could update your device with their code.

9.1 To set our own key, we first need to generate a key. We will use imgtool for this:

python3 <NCS_PATH>/bootloader/mcuboot/scripts/imgtool.py keygen -t ecdsa-p256 -k priv.pem

9.2 To configure our project to use this key, follow docs at MCUboot adding custom signature key file. We can do this in two different ways. Either we can set this key in child_image/mcuboot.conf.

CONFIG_BOOT_SIGNATURE_KEY_FILE="<PATH_TO>/priv.pem"

As you can see, this uses the full path to the project, which is a limitation.
9.3 It is possible to use CMakeLists.txt to set the path relative to the project folder. This is more powerful but also more complex. To do this, set the following in CMakeLists.txt:

set(mcuboot_CONFIG_BOOT_SIGNATURE_KEY_FILE \"${CMAKE_CURRENT_SOURCE_DIR}/priv.pem\")

Here, you can use CMake variables and pathing to choose any folder, as seen relative to your project.
It is up to you if you want to use 9.2 or 9.3 in your project. I suggest that you try both and find out which you like the best.
These steps will not be included in the solution, as they require a generated key.