Configuring firmware updates

To set up your application to support firmware update:

1. Add #define MBED_CLOUD_CLIENT_FOTA_ENABLE 1 macro to the mbed_cloud_client_user_config.h file used by the application.

2. Configure the following parameters in your application's json file:

   Note: The configuration must match the configuration used in the bootloader build.

   • "target.header_offset": "0x8000" - FOTA image header offset in internal flash. The header contains image metadata, such as version, digest and size.

     Note: The FOTA image header must reside on erase block boundary as it will be overwritten during the firmware update.

   • "target.app_offset": "0x8200" - Firmware image offset in internal flash. This value is passed to the linker script for relocating the firmware application to the desired offset. This relocation is required for bootloader to work.

     Note: The offset address must be naturally aligned to a power of two, where the alignment value is greater than or equal to (number of exceptions supported x 4), with a minimum alignment of 128 bytes.

   • "fota.block-device-type":"FOTA_INTERNAL_FLASH_BD" - FOTA library BlockDevice type used for storing and reading a firmware candidate. Available options are:

     • FOTA_INTERNAL_FLASH_BD - (Mbed OS environment only) Internal flash BlockDevice to be used for saving the firmware candidate.

     • FOTA_CUSTOM_BD - (Mbed OS environment only) Allows the application to select a custom BlockDevice. The application is expected to implement a BlockDevice getter function mbed::BlockDevice *fota_bd_get_custom_bd().

       An example of using Mbed OS default BlockDevice:

       mbed::BlockDevice *fota_bd_get_custom_bd()
       {
           return mbed::BlockDevice::get_default_instance();
       }
       

     • FOTA_EXTERNAL_BD - Allows the application to implement its own version of a BlockDevice by all functions in the fota_block_device.h header file.

   • "fota.storage-start-address": "0x..." - Address for the candidate storage.

     • If you select FOTA_INTERNAL_FLASH_BD as the FOTA storage type, the address is a physical address in internal flash.
     • In all other cases, the storage address is relative to the BlockDevice start address and can be considered as an offset.

   • "fota.storage-size": 256*1024 - FOTA candidate storage size.

   • "fota.encryption-support": True - (Optional) Enable firmware candidate encryption on storage. AEC-CMM encryption is used to both encrypt and authenticate the candidate.

   • "fota.candidate-block-size": 1024 - (Optional - only relevant when encryption-support=True) Set encryption block size. Bigger block size requires more RAM.

   • "target.header_format": [] (Mbed OS environment only) FOTA image header template specification for Mbed OS post-build script. This instructs the Mbed-OS postbuild to forge the FOTA image header in the format expected by the FOTA library.

     An example:

     "target.header_format": [
       ["magic", "const", "32le", "0x5c0253a3"],
       ["firmwareSize", "size", "32le", ["application"]],
       ["firmwareVersion", "const", "64le", "0x0"],
       ["firmwareDigest", "digest", "SHA256", "application"],
       ["precursorDigest", "digest", "SHA256", "application"]
     ]
     

   • "fota.num-components": x (Optional) Client Lite supports update of components different from the main firmware image; for example, a BLE stack running on a co-processor. To register extra components, define this parameter, where x is the number of components present in the system including the MAIN component of the firmware image.

Example configuration

A reference example of configuring the firmware update parameters in the mbed_app.json file for an NRF52840_DK board:

    "target.header_offset": "0x8000",
    "target.app_offset": "0x8200",
    "target.header_format": [
         ["magic", "const", "32le", "0x5c0253a3"],
         ["firmwareSize", "size", "32le", ["application"]],
         ["firmwareVersion", "const", "64le", "0x0"],
         ["firmwareDigest", "digest", "SHA256", "application"],
         ["precursorDigest", "digest", "SHA256", "application"]
    ],
    "fota.block-device-type": "FOTA_INTERNAL_FLASH_BD",
    "fota.storage-start-address": "(MBED_CONF_STORAGE_TDB_INTERNAL_INTERNAL_BASE_ADDRESS+MBED_CONF_STORAGE_TDB_INTERNAL_INTERNAL_SIZE)",
    "fota.storage-size": "(512*1024-MBED_CONF_STORAGE_TDB_INTERNAL_INTERNAL_SIZE)"

Next steps

• To update a firmware image, you must integrate your application with a bootloader. For more information, see the bootloader documentation.

• Implement the firmware update callbacks in your application

• See the application tutorial for a quick example of a full image update.

• See the full update documentation on the Izuma Device Management documentation site:

  • End-to-end Device Management Update tutorials for performing update campaigns.
  • Creating and using delta images for Update for using delta update.