Firmware loader entrance
The Firmware loader entrance sample demonstrates how to enter the firmware loader application using MCUboot’s firmware updater mode with boot mode entrance.
The sample shows how to configure an application that can trigger entry into a dedicated firmware loader application for performing firmware updates over Bluetooth® Low Energy using MCUmgr. This approach allows you to have a larger main application while keeping firmware update functionality separate in a dedicated loader application.
Requirements
The sample supports the following development kits:
Hardware platforms |
PCA |
Board name |
|
|---|---|---|---|
PCA10156 |
|
||
PCA10056 |
|
Overview
This sample demonstrates MCUboot’s firmware updater mode, which enables a configuration with three components:
Component |
Description |
|---|---|
MCUboot bootloader |
Handles boot decisions and image management |
Main application |
Your primary application (not intended for firmware updates) |
Firmware loader application |
A dedicated application for loading firmware updates over Bluetooth LE using MCUmgr |
The benefit of this configuration is having a dedicated application for loading firmware updates, which allows the main application to be larger in comparison to symmetric size dual-bank mode updates. This helps when working with devices that have limited flash or RAM.
The sample application itself is a minimal Bluetooth LE peripheral that advertises using the MCUmgr service UUID.
When configured with the GPIO entrance mode, MCUboot can boot into the firmware loader application based on GPIO state at boot time.
The firmware loader application (configured as BLE_MCUMGR) provides MCUmgr over Bluetooth LE transport for performing firmware updates.
The sample uses the boot mode entrance method, in which MCUboot checks the boot mode using the retention subsystem to determine whether to boot the main application or the firmware loader application.
User interface
The following button is used by this sample:
- Button 0:
Press and hold this button while resetting the device to enter firmware loader mode when Testing entering the firmware loader.
Configuration
See Configuring and building for information about how to permanently or temporarily change the configuration.
Additional configuration
Check and configure the following Kconfig options:
Option |
Description |
|---|---|
|
Enables GPIO-based entrance to firmware loader mode. |
|
Allows booting firmware loader when no valid main application is present. |
Enables Bluetooth LE transport for MCUmgr. |
|
Enables packet reassembly for large MCUmgr packets over Bluetooth LE. |
|
Enables OS management group with bootloader information and boot mode support. |
|
Enables reset with boot mode support for entering firmware loader. |
Sysbuild configuration
The sample uses sysbuild to configure MCUboot and the firmware loader image.
The following options are set in sysbuild.conf:
Option |
Description |
|---|---|
Enables MCUboot firmware updater mode. |
|
Enables boot mode entrance method. |
|
Selects the BLE MCUmgr sample as the firmware loader image. |
Building and running
This sample can be found under samples/mcuboot/firmware_loader_entrance 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:
Connect the kit to the computer using a USB cable. The kit is assigned a serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the
nrfutil device listcommand. Alternatively, check your operating system’s device manager or its equivalent.Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.
Build and program the sample to your development kit.
Observe the terminal output.
The sample starts advertising Bluetooth LE with the MCUmgr service UUID. You will see “Advertising successfully started” in the terminal output.
Testing entering the firmware loader
To test entering the firmware loader application (when using GPIO entrance):
Configure the GPIO entrance method using the
CONFIG_BOOT_FIRMWARE_LOADER_ENTRANCE_GPIOKconfig option.Press and hold Button 0.
While holding the button, reset the device.
Note
Simply pressing the button without resetting the device will not enter firmware loader mode. The GPIO must be held during the reset for MCUboot to detect the entrance request.
MCUboot will boot into the firmware loader application instead of the main application. Then, the firmware loader application starts advertising Bluetooth LE and can be used to perform firmware updates using MCUmgr.
Sample output
The following output is logged on the terminal:
[00:00:00.000,000] <inf> firmware_entrance_loader: Bluetooth initialized
[00:00:00.100,000] <inf> firmware_entrance_loader: Advertising successfully started, device name: firmware_loader_entrance
Dependencies
This sample uses the following libraries:
API:
include/zephyr/bluetooth/bluetooth.hinclude/zephyr/bluetooth/conn.hinclude/zephyr/bluetooth/gatt.h
-
include/zephyr/kernel.h
include/zephyr/mgmt/mcumgr/transport/smp_bt.hinclude/zephyr/settings/settings.hinclude/zephyr/logging/log.h