Mistake on this page? Email us

Integrating firmware update in your application

Firmware-over-the-air (FOTA) update is an in-built feature of Client Lite.

If your application does not require an implementation of any special logic, the Client Lite library provides a default implementation of the update callbacks. To enable the default implementation, inject the FOTA_DEFAULT_APP_IFS define into the application build.

For an example implementation of the firmware update callbacks, see the pelion-client-lite repository.

Integrating firmware update callbacks in your application

If you don't want to use the default implementation, your application must implement the callbacks specified in the FOTA application interface specification header file:

  • fota_app_on_download_authorization() - FOTA download authorization callback. The client requires the application to authorize download of the update.

    The client expects the callback to call one of these APIs:

    • fota_app_authorize() - Authorize the FOTA download request.
    • fota_app_reject() - Reject the FOTA request and discard the update. The update will not be re-prompted.
    • fota_app_defer() - Defer the update to a later phase. This aborts the current update attempt, while preserving the update manifest. The device reattempts the update when the device next registers/re-registers to Device Management. Alternatively, you can restart the update by calling fota_app_resume().

    The client expects the callback to return 0 (FOTA_STATUS_SUCCESS) to acknowledge the authorization delivery. On constrained devices, the client expects the application to back up the current state and free resources (RAM), if necessary, before authorizing the download.

  • fota_app_on_install_authorization() - The FOTA update install authorization callback. The client calls this callback after successful candidate download and verification. The client requires the application to authorize installation of the update.

    The client expects the callback to call one of these APIs:

    • fota_app_authorize() - Authorize FOTA to install the update candidate. Reboot or connectivity loss may occur during the candidate installation operation, depending on installer implementation. This phase is considered critical as power loss can potentially brick the device.

    • fota_app_reject() - Reject the FOTA request to install and discard the update. The update will not be re-prompted.

    • fota_app_defer() - Defer the install to a later phase. This marks the candidate as valid but does not perform reboot. The installation will happen upon device reboot.

      Note: After the application defers installation by calling fota_app_defer(), the device has to reboot before installing the candidate image. Calling fota_app_resume() after fota_app_defer() has no effect.

  • fota_app_on_complete() - The FOTA update complete notification callback. The client notifies the application of completion or termination of the update process. The application may have postponed its main activities before authorizing an update. Therefore, the client notifies the application that the application can go back to its normal state.

    Note: This callback is not called if the system reboots as part of update installation.

  • fota_app_on_download_progress() - Notifies the application about the firmware candidate download progress. The client calls this callback whenever the download progresses by approximately five percent. You can use the callback in the application to present the download progress visually.

    We recommend that you set this API during the development phase because it shows the download progress.

This diagram shows the FOTA callback calling sequence:

The red arrows show the application callback sequence in a good-path scenario in which the application authorizes all of the requests by calling fota_app_authorize(). Note that the application callbacks call fota_app_authorize() out of callback context to illustrate that the application can call these APIs from some event after handling ongoing business logic tasks.

Integrating firmware update platform hooks with your application

The FOTA library offers platform hook callbacks that you can use to integrate platform-specific code during the FOTA flow; for example, if Client Lite shares a resource with another component of the system.

By default, FOTA provides an empty implementation for these hooks. You can override these hooks by injecting the FOTA_CUSTOM_PLATFORM macro to the build and implementing all of the callback functions listed in fota/fota_platform.h:

  • fota_platform_init_hook() - Platform init hook, which the client calls when it initializes the FOTA module.

    The client uses fota_platform_init_hook() to register custom components as described in the Implementing component update.

  • fota_platform_start_update_hook() - Platform start update hook, which the client calls when the update begins.

  • fota_platform_finish_update_hook() - Platform finish update hook, which the client calls when the update has finished.

  • fota_platform_abort_update_hook() - Platform start update hook, which the client calls if an update is aborted.

The red arrows show the application callback sequence in a good-path scenario in which the application authorizes all of the requests by calling fota_app_authorize_update()). Note that the application callbacks call fota_app_authorize_update() out of callback context to illustrate that the application can call these APIs from some event after handling ongoing business logic tasks.