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:
- Define and register the component in the client, as described in this document.
- Connect the device to Device Management.
- Prepare the updated component image.
To run the update campaign, you must, as described in Running update campaigns:
- Upload the component image to Device Management.
- Create a manifest with the information the device needs to validate and download the firmware update.
- Upload the manifest to Device Management.
- 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 campaigns.
Component update flow diagram
Defining component update and registering a component in the client
Define the number of components present on the device by adding the
FOTA_NUM_COMPONENTS=xmacro to your build configuration file.
xis the number of components in the device, including the
MAINcomponent of the firmware image.
For Mbed OS, add this line to your
Register your component:
fota_platform_init_hook()hook (see fota_platform.h), which the client calls when it initializes the FOTA module.
Fill in the
fota_component_desc_info_tcomponent descriptor structure (defined in fota_component.h), supplying two callbacks:
candidate_iterate_cb- In non-Linux devices, the FOTA client calls this callback function to install the candidate image.
component_verify_install_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.
fota_platform.hfile 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.cfile in the
For Linux devices only, implement the
fota_app_on_install_candidate()API (defined in fota_app_ifs.h), which installs the component.
This replaces the
candidate_iterate_cbcallback, which the FOTA client calls for non-Linux devices.