CAF: Simple Management Protocol module

The simple management protocol module of the Common Application Framework (CAF) allows to perform the device firmware upgrade (DFU) over Bluetooth® LE.

Configuration

To use the module, you must enable the following Kconfig options:

• CONFIG_CAF_BLE_STATE - This module enables CAF: Bluetooth LE state module.

• CONFIG_CAF_BLE_SMP - This option enables simple management protocol module over Bluetooth LE.

• CONFIG_MCUMGR_GRP_IMG - This option enables MCUmgr image 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 MCUmgr notification hook support, which allows this module to listen for a MCUmgr event. For details, see MCUmgr Callbacks in the Zephyr documentation.

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

• CONFIG_MCUMGR_TRANSPORT_BT - This option enables support for the SMP commands over Bluetooth.

• CONFIG_BOOTLOADER_MCUBOOT - This option enables the MCUboot bootloader. The DFU over Simple Management Protocol in Zephyr is supported only with the MCUboot bootloader.

Enabling remote OS management

The simple management protocol module supports registering OS management handlers automatically, which you can enable using the following Kconfig option:

• CONFIG_MCUMGR_GRP_OS - This option enables MCUmgr OS management handlers. Use these handlers to remotely trigger the device reboot after the image transfer is completed. After the reboot, the device starts using the new firmware. One of the applications that support the remote reboot functionality is nRF Connect for Mobile.

Implementation details

The module periodically submits ble_smp_transfer_event during the image upload. The module registers the upload_confirm_cb() callback that is used to submit ble_smp_transfer_event. 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 not processed, the module desists from submitting a subsequent event. After the previously submitted event is processed, the module submits a subsequent event when the upload_confirm_cb() callback is called.

The application user must not perform more than one firmware upgrade at a time. The modification of the data by multiple application modules can result in a broken image that is going to be rejected by the bootloader.

After building your application with the simple management protocol module enabled, the dfu_application.zip archive is generated in the build directory. It contains all the firmware update files that are necessary to perform DFU. For more information about the contents of update archive, see Output build files (image files).

To perform DFU using the nRF Connect Device Manager mobile app, complete the following steps:

1. Generate the DFU package by building your application with the FOTA support over Bluetooth Low Energy. You can find the generated dfu_application.zip archive in the build directory.

   Note

   For each image included in the DFU-generated package, use a higher version number than your currently active firmware. Otherwise, the DFU target may reject the FOTA process due to a downgrade prevention mechanism.

2. Download the dfu_application.zip archive to your device. See Output build files (image files) for more information about the contents of update archive.

   Note

   nRF Connect for Desktop does not currently support the FOTA process.

3. Use the nRF Connect Device Manager mobile app to update your device with the new firmware.

   1. Ensure that you can access the dfu_application.zip archive from your phone or tablet.

   2. In the mobile app, scan and select the device to update.

   3. Switch to the Image tab.

   4. Tap the SELECT FILE button and select the dfu_application.zip archive.

   5. Tap the START button.

      Note

      When performing a FOTA update with the iOS app for samples using random HCI identities, ensure that the Erase application settings option is deselected before starting the procedure. Otherwise, the new image will boot with random IDs, causing communication issues between the app and the device.

   6. Initiate the DFU process of transferring the image to the device:

      • If you are using an Android device, select a mode in the dialog window, and tap the START button.

      • If you are using an iOS device, tap the selected mode in the pop-up window.

      Note

      For samples using random HCI identities, the Test and Confirm mode should not be used.

   7. Wait for the DFU to finish and then verify that the application works properly.

Note

Support for FOTA updates with MCUboot in the direct-xip mode is available since the following versions of the nRF Connect Device Manager mobile app:

• Version 1.8.0 on Android.

• Version 1.4.0 on iOS.

Note

If the CONFIG_MCUMGR_GRP_IMG_REJECT_DIRECT_XIP_MISMATCHED_SLOT Kconfig option is enabled in the application configuration, the device rejects an update image upload for the invalid slot. It is recommended to enable the option if the application uses MCUboot in the direct-xip mode.