Integrating your application with Device Management Client to update Linux targets

Although the update flow on embedded devices usually involves replacing a single binary file that is running on the device, the update flow on Linux systems can be more complicated because the Linux system is composed of many files.

To compile Device Management Client on Linux targets, define the TARGET_LIKE_LINUX macro in the mbed_cloud_client_user_config.h application configuration file.

Integrating with the update client callbacks

Update client expects the device application to implement these callbacks:

• fota_app_on_install_candidate

  This callback receives the candidate file name and a parsed update manifest.

  The application can use this callback to call an activation script to update the Linux distribution or replace the currently running process.

  Callback examples:

  • Implementation for replacing a single main file.

    This implementation replaces the binary from which the Device Management Client process is running.

    The fota_app_on_install_candidate implementation calls the fota_app_install_main_app API, which actually overwrites the executable file and relaunches the process.

    Define the MBED_CLOUD_CLIENT_FOTA_LINUX_SINGLE_MAIN_FILE macro to use this single-file update implementation.

  • Yocto Linux example.

    Invokes an activation script that performs an A/B partition swap.

• fota_app_on_main_app_verify_install

  This callback receives the fota_header_info_t candidate header.

  The candidate header includes the vendor_data field, which can store vendor-specific data to help verify installation of the main application.

  You can provide vendor data to the device in the manifest:

  • In the development phase, use the manifest tool manifest-dev-tool create -d option.
  • In the production phase, edit the custom-data-path: field in the config.yaml that you pass in the manifest-tool create manifest tool command.

  Note: For more information about the manifest too, see the manifest tool documentation in PyPi.

  From within this callback, the application logic can verify the installation of the main application.

  The update client expects an implementation of this callback only if you define the FOTA_CUSTOM_MAIN_APP_VERIFY_INSTALL macro.

Configuring the update candidate image location

On Linux systems, Device Management Client saves the update candidate and the current firmware metadata file in the working directory from which the Device Management Client process is running.

To override this behavior, inject these macros to the build:

• MBED_CLOUD_CLIENT_FOTA_LINUX_CANDIDATE_FILENAME - Update candidate file name, as passed to the int fota_app_on_install_candidate() callback.

• MBED_CLOUD_CLIENT_FOTA_LINUX_HEADER_FILENAME - Firmware metadata file in binary format. This file contains the current firmware version as shown in Device Management Portal and other internal details.

  Unauthorized processes cannot write to this file because Device Management Client uses the file to prevent version rollback.

Configuring the update candidate image size

Use the MBED_CLOUD_CLIENT_FOTA_STORAGE_SIZE macro to define the maximum allowed candidate image size in bytes.

Note: For the FOTA download resume feature, which is enabled by default for Linux targets, the actual disk size required for update is 2 * MBED_CLOUD_CLIENT_FOTA_STORAGE_SIZE.