Device Firmware Upgrade MCUmgr module

The Device Firmware Upgrade MCUmgr module is responsible for performing a Device Firmware Upgrade (DFU) over Simple Management Protocol (SMP).

If you enable the Bluetooth LE as transport, you can perform DFU using, for example, the nRF Connect Device Manager application. See the Image transfer over SMP section for more details.

Note

The Device Firmware Upgrade MCUmgr module implementation is currently marked as experimental because it uses internal MCUmgr API.

Module events

Source Module	Input Event	This Module	Output Event	Sink Module
Source modules for module_state_event	module_state_event	dfu_mcumgr
Device Firmware Upgrade MCUmgr module	ble_smp_transfer_event
Simple Management Protocol module
			ble_smp_transfer_event	Bluetooth LE latency module
				Device Firmware Upgrade MCUmgr module
				Simple Management Protocol module

Note

See the Overview: Firmware architecture for more information about the event-based communication in the nRF Desktop application and about how to read this table.

Configuration

To enable the module, set the CONFIG_DESKTOP_DFU_MCUMGR_ENABLE Kconfig option.

The module selects the following configurations:

• CONFIG_MCUMGR - This option enables the MCUmgr support, which is required for the DFU process. For details, see MCUmgr in the Zephyr documentation.

• MCUmgr groups:

  • CONFIG_MCUMGR_GRP_IMG - This option enables the MCUmgr image management handlers, which are required for the DFU process. For details, see Device Management in the Zephyr documentation.

  • CONFIG_MCUMGR_GRP_OS - This option enables the MCUmgr OS management handlers, which are required for the DFU process. For details, see Device Management in the Zephyr documentation.

• CONFIG_MCUMGR_MGMT_NOTIFICATION_HOOKS - This option enables the MCUmgr notification hook support, which allows the module to listen for an MCUmgr event. For details, see MCUmgr Callbacks in the Zephyr documentation.

  MCUmgr notifications hooks:

  • CONFIG_MCUMGR_GRP_IMG_UPLOAD_CHECK_HOOK - This option enables the MCUmgr upload check hook, which sends image upload requests to the registered callbacks.

  • CONFIG_MCUMGR_GRP_IMG_STATUS_HOOKS - This option enables the MCUmgr image status hooks, which report the DFU status to the registered callbacks.

  • CONFIG_MCUMGR_GRP_OS_RESET_HOOK - This option enables the MCUmgr OS reset hook, which sends reset requests to the registered callbacks.

• MCUmgr dependencies:

  • CONFIG_NET_BUF

  • CONFIG_ZCBOR

  • CONFIG_CRC

  • CONFIG_IMG_MANAGER

  • CONFIG_STREAM_FLASH

  • CONFIG_FLASH_MAP

  • CONFIG_FLASH

To use the module, you must also enable the CONFIG_BOOTLOADER_MCUBOOT Kconfig option. The DFU over Simple Management Protocol in Zephyr is supported only with the MCUboot bootloader.

By default, the MCUmgr DFU module confirms the image using the boot_write_img_confirmed() function during the system boot. If the CONFIG_DESKTOP_DFU_MCUMGR_MCUBOOT_DIRECT_XIP option is enabled, the MCUmgr DFU module assumes that the bootloader simply boots the image with a higher version and does not confirm the newly updated image after a successful boot. Make sure that CONFIG_DESKTOP_DFU_MCUMGR_MCUBOOT_DIRECT_XIP Kconfig option is enabled if devices use the MCUboot bootloader in direct-xip mode. The option is enabled by default if CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP is enabled.

You must also enable the preferred transport for the MCUmgr’s SMP protocol (for example, the CONFIG_MCUMGR_TRANSPORT_BT Kconfig option). With the CONFIG_MCUMGR_TRANSPORT_BT Kconfig option enabled, the module enables the CONFIG_CAF_BLE_SMP_TRANSFER_EVENTS event. The event can be used to lower Bluetooth connection latency during the DFU process.

The DFU module leverages the DFU lock utility to synchronize flash access with other DFU methods (for example, the Device Firmware Upgrade module). Set the CONFIG_DESKTOP_DFU_LOCK Kconfig option to enable this feature. Make sure that the DFU lock utility is enabled if your nRF Desktop application configuration uses multiple DFU transports.

You cannot use this module with the CAF: Simple Management Protocol module. In other words, you cannot simultaneously enable the CONFIG_DESKTOP_DFU_MCUMGR_ENABLE option and the CONFIG_CAF_BLE_SMP Kconfig option.

Implementation details

The module uses MCUmgr’s image notification callbacks for the following purposes:

• To periodically submit a ble_smp_transfer_event while image upload over Bluetooth LE is in progress. The module registers itself as the final subscriber of the event to track the number of submitted events. If a ble_smp_transfer_event was already submitted, but was not yet processed, the module desists from submitting subsequent events.

• To reject image upload or system reboot request if DFU lock utility is already taken by another DFU transport.

The DFU MCUmgr implementation uses the DFU lock utility. On each DFU attempt, the module attempts to claim ownership over the DFU flash using the DFU lock utility API. It holds the DFU owner status until the DFU process is completed or timed out. The module assumes that DFU is timed out if the registered MCUmgr notification hooks are not called for 5 seconds. If the module is not the current DFU owner, it rejects the DFU commands that either write to the DFU flash or reboot the device. The module also resets the MCUmgr DFU progress once the lock is claimed by a different owner.