Implementing combined update

The FOTA client lets you group together multiple images on the device as requiring a simultaneous, combined update.

Note: The combined update feature is currently available for Linux devices only.

This capability is useful when images have a strong dependency on each other, and updating one image without updating the other might cause the device to stop functioning.

For example, an update of the operating system might require an update of the bootloader. Although the images may be located in different storages, which means they cannot be installed as one monolithic image, you want to update the images together, or roll back the entire update if one image is updated successfully but the update of the other image fails.

To enable a combined update on a device, you must register a device component that consists of the relevant subcomponents that need to be updated together.

Use the manifest tool to prepare a combined package, which includes the images to be updated on the device in the combined update, to deliver to the device, along with the campaign manifest, as part of the update campaign.

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

Combined update flow

Before running the update campaign:

1. Register the component and its subcomponents in the client, as described in this document.
2. Connect the device to Device Management.

To run the update campaign:

3. Prepare a combined package using the manifest tool.
4. Upload the combined package 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.

Note: These steps are detailed in Running update campaigns.

The update process

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 combined package.

The client saves the combined package into storage that is accessible to the subcomponent installers.

The subcomponent installers install the subcomponent and report the installation status to the client.

Device Management records a successful combined update if and only if the device confirms that all of the images in the combined package are installed and validated.

Device Management reports a new updated version of the component to Device Management Portal.

Example:

Component A consists of subcomponents A1 and A2.

Component A version 1.1 contains:

• Subcomponent A1 version 2.1.
• Subcomponent A2 version 3.1.

The combined package of component A version 1.2 contains:

• Subcomponent A1 version 2.2.
• Subcomponent A2 version 4.0.

After a successful update, Device Management reports that component A is at version 1.2.

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 combined update and registering subcomponents in the client

1. Define the number of subcomponents that can be updated simultaneously as part of a combined update by adding the FOTA_MAX_NUM_OF_SUB_COMPONENTS=x macro to your build configuration file, where x is the maximum number of subcomponents per component.

2. Register your component, as described in Defining component update and registering a component in the client

   Note: You do not have to register your device's MAIN component using the fota_component_add() API. Therefore, if you implement a combined update on the device's MAIN component, skip this step and use MAIN as the component name when registering subcomponents using the fota_sub_component_add API.

3. Register your subcomponent:

   1. Set the MBED_CLOUD_CLIENT_FOTA_SUB_COMPONENT_SUPPORT macro to 1 to enable combined update.

   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_sub_comp_info_t subcomponent descriptor structure (defined in fota_sub_component.h), supplying:

        • install_cb - A callback function that installs the new subcomponent firmware image.

        • install_order - Installation order of the subcomponent, relative to other subcomponents.

        • verify_cb - A callback function that verifies the installation of the new subcomponent firmware image.

        • verify_order - Verification order of the subcomponent, relative to other subcomponents.

        • rollback_cb - A callback function that rolls back the installation of the new image. The client calls the rollback callback when the combined update process fails.

          It is the callback’s responsibility to handle the rollback correctly, regardless of the state at which installation fails. In other words, the callback is expected to perform the correct action regardless of whether the installation was performed fully, partially or not at all.

        • rollback_order - Rollback order of the subcomponent, relative to other subcomponents.

        • finalize_cb - A callback function that performs finalization after the combined update succeeds or fails.

        • finalize_order - Finalize order of the subcomponent, relative to other subcomponents.

      • Register your sub-component by calling the fota_sub_component_add() API, supplying the component name, the subcomponent name, and the structure.

      The fota_platform.h file includes additional platform hooks, which you can implement as empty functions if you do not need them. For a subcomponent registration example, please see the fota_platform_hooks_impl.cpp file in the mbed-cloud-client-example repository.