Implementing component update

The FOTA library supports update of components different from the main firmware image, such as wireless connectivity modules, embedded sensors, or different partitions or packages in Linux-based devices; for example, a BLE stack running on a co-processor.

This document describes the high-level component update flow and explains the steps required to set up component update on the device.

Component update flow

Before running a component update campaign, you must:

1. Define and register the component in the client, as described in this document.
2. Connect the device to Device Management.
3. Prepare the updated component image.

To run the update campaign, you must, as described in Running update campaigns:

4. Upload the component image to Device Management.
5. Create a manifest with the information the device needs to validate and download the firmware update.
6. Upload the manifest to Device Management.
7. Configure and initiate the update campaign.

As part of the update process Device Management sends the manifest to the device.

The client verifies that the firmware version in the manifest is higher than the existing version of the component. The client then downloads the component candidate image, saves the image into storage that is accessible to the component installer, and calls the component installation callback.

The component installer is responsible for installing the image and reporting the installation status to the client.

Device Management records successful update of the component and marks the update of the device as completed.

Note: Device Management Portal displays the names and version numbers of registered components when the device connects. You can use component names and versions to filter devices when creating an update campaign.

Component update flow diagram

Defining component update and registering a component in the client

1. Define the number of components present on the device by adding the FOTA_NUM_COMPONENTS=x macro to your build configuration file.

   • Where x is the number of components on the device, including the device's MAIN component.

   • For Mbed OS, add this line to your mbed_app.json file:

     "fota.num-components": x
     

2. Register your component:

   1. Enable the FOTA_CUSTOM_PLATFORM macro.

   2. Implement the fota_platform_init_hook() hook (see fota_platform.h), which the client calls when it initializes the FOTA module.

      In the fota_platform_init_hook() hook:

      • Fill in the fota_component_desc_info_t component descriptor structure (defined in fota_component.h), supplying two callbacks:

        • component_install_cb - FOTA client calls this callback function to install the candidate image. Different prototypes for Linux and non-Linux devices.
        • component_verify_cb - A callback function that verifies the installation of the new image.

      • Register your component by calling the fota_component_add() API, supplying the component name and the factory version of the component.

      The fota_platform.h file includes additional platform hooks, which you can implement as empty functions if you do not need them.

      For a component registration example, please see the fota_platform_hooks_impl.cpp file in the mbed-cloud-client-example repository.