Single-slot DFU with MCUboot

The Single-slot DFU with MCUboot sample demonstrates how to maximize the available space for the application using MCUboot. You can do this by using the firmware loader mode (single-slot layout) in MCUboot. Both MCUboot and the firmware loader images are configured to achieve minimal size, leaving more space available for the application.

Requirements

The sample supports the following development kit:

Hardware platforms

PCA

Board name

Board target

nRF7120 DK

nrf7120dk

nrf7120dk/nrf7120/cpuapp

nRF54LS05 DK

PCA10214

nrf54ls05dk

nrf54ls05dk/nrf54ls05b/cpuapp nrf54ls05dk/nrf54ls05a/cpuapp

nRF54LM20 Dongle

PCA10208

nrf54lm20dongle

nrf54lm20dongle/nrf54lm20b/cpuapp

nRF54LM20 DK

PCA10184

nrf54lm20dk

nrf54lm20dk/nrf54lm20b/cpuapp nrf54lm20dk/nrf54lm20a/cpuapp

nRF54L15 DK

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l15/cpuapp

nRF54H20 DK

PCA10175

nrf54h20dk

nrf54h20dk/nrf54h20/cpuapp

nRF52840 DK

PCA10056

nrf52840dk

nrf52840dk/nrf52840

Overview

This sample contains a simple main application with no firmware update capabilities. The firmware loader image is used to perform the DFU over Bluetooth® Low Energy or USB CDC ACM serial. See Using MCUboot in firmware loader mode and Minimal USB virtual serial port SMP firmware loader for more details.

This sample employs one of alternatives: * The Minimal Bluetooth LE SMP firmware loader firmware loader image, which uses the Simple Management Protocol (SMP) over Bluetooth LE. * The Minimal USB virtual serial port SMP firmware loader firmware loader image, which uses the USB CDC ACM serial.

This sample can employ the buttonless DFU feature when the application can enter firmware loader mode without the need to hold a button during reset. This is achieved by enabling the SMP MCUmgr group reset command with the boot mode parameter, which must be set to 1 to enter firmware loader mode.

Entering the firmware loader

The sample demonstrates the following methods of entering the firmware loader image:

Firmware loader entrance methods

Method

Build variant

Description

GPIO

Default

MCUboot reads the state of Button 0 at boot time, as enabled by the CONFIG_BOOT_FIRMWARE_LOADER_ENTRANCE_GPIO Kconfig option.

Buttonless over Bluetooth LE

ble_enter

The main application exposes an SMP server over Bluetooth LE and requests the firmware loader through the MCUmgr reset command with the boot mode parameter.

Buttonless over USB

usb_enter

The main application exposes an SMP server over USB CDC ACM serial and requests the firmware loader through the MCUmgr reset command with the boot mode parameter.

The buttonless variants build with the SB_CONFIG_MCUBOOT_MODE_FIRMWARE_UPDATER_BOOT_MODE_ENTRANCE sysbuild option, which makes MCUboot read the requested boot mode from the retention subsystem instead of a GPIO.

Note

Pressing Button 0 without resetting the device does not enter the firmware loader mode. The button must be held during the reset for MCUboot to detect the entrance request.

Building and running

By default, the sample builds with the Minimal Bluetooth LE SMP firmware loader firmware loader image. To build the sample with the Minimal Bluetooth LE SMP firmware loader firmware loader image and Bluetooth LE buttonless DFU support, append FILE_SUFFIX=ble_enter to the build command. To build with the Minimal USB virtual serial port SMP firmware loader firmware loader image, append FILE_SUFFIX=usb to the build command. To build the sample for the nRF54LM20 DK with the Minimal USB virtual serial port SMP firmware loader firmware loader image and USB buttonless DFU support, append FILE_SUFFIX=usb_enter to the build command. To build the sample for the nrf54lm20dk/nrf54lm20a/cpuapp target with the Minimal USB virtual serial port SMP firmware loader firmware loader image and USB buttonless DFU support, append FILE_SUFFIX=usb_enter_dongle to the build command.

This sample can be found under samples/dfu/single_slot 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, perform the following steps:

  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 and observe the output on the terminal:

    Starting single_slot sample
build time: <BUILD TIME>

  3. Build a second version of the sample.

  4. Enter the firmware loader mode by holding the Button 0 on your development kit while you reset the device, or by sending the reset command with the boot-mode parameter set to 1 through MCUmgr. When built with FILE_SUFFIX=ble_enter, use the nRF Connect Device Manager or nRF Connect for Mobile mobile app to send the reset command.

    1. Bluetooth firmware loader:

      Open the nRF Connect Device Manager or nRF Connect for Mobile mobile app to perform DFU over Bluetooth LE.

      • When built with FILE_SUFFIX=ble_enter, the application advertises as single_slot until firmware loader mode is entered.

      • After entering firmware loader mode, the firmware loader advertises using the name written to Settings by the mobile app, or as FW loader if firmware loader mode was entered by pressing Button 0.

      • The firmware loader accepts MCUmgr image upload.

      • Send the generated update package for the second version of the sample. See Testing steps for details on how to use the mobile app to perform the DFU.

      Note

      When using FILE_SUFFIX=ble_enter, the mobile app writes a unique firmware loader advertising name before reset so the client can reconnect to the same device by name.

    2. USB CDC ACM serial firmware loader:

      Use nrfutil mcu-manager serial command to perform DFU over serial port.

      • Send the generated update package for the second version of the sample.

  5. Verify that the printed build time corresponds to the new version once the update is complete and the device reboots into the main application.

Dependencies

This sample uses the following nRF Connect SDK components: