Firmware update

There are two aspects of firmware update:

• The integration of firmware update API to your application.
• Preparing and orchestrating the firmware update process, either the full image or delta update.

Integrating firmware update API to application

Firmware update is an in-built feature of Client Lite. If your application requires to have certain control points for the firmware update process, you can pass callbacks to the application to manage the process.

Configuring application

To set up your application to support firmware update, configure the following parameters in your application's json file:

"name": "fota",
    "config": {
        "block-device-type": {
            "help": "Type of block device: Internal flash, custom (supply a block device instance) or external (implement all FOTA block device C APIs)",
            "macro_name": "MBED_CLOUD_CLIENT_FOTA_BLOCK_DEVICE_TYPE",
            "accepted_values": ["FOTA_INTERNAL_FLASH_BD", "FOTA_CUSTOM_BD", "FOTA_EXTERNAL_BD"],
            "value": null
        },
        "storage-start-address": {
            "help": "FW candidate storage start address (physical)",
            "macro_name": "MBED_CLOUD_CLIENT_FOTA_STORAGE_START_ADDR",
            "value": null
        },
        "storage-size": {
            "help": "FW candidate storage size",
            "macro_name": "MBED_CLOUD_CLIENT_FOTA_STORAGE_SIZE",
            "value": null
        }
    }

Here is a reference example of how to configure the firmware update parameters for NRF52840_DK.

The configuration defines that the firmware update candidate will be downloaded and stored into the second bank of internal flash. Here's how the configuration parameter looks in mbed_app.json:

    "fota.block-device-type"                    : "FOTA_INTERNAL_FLASH_BD",
    "fota.storage-start-address"                : "(MBED_CONF_STORAGE_TDB_INTERNAL_INTERNAL_BASE_ADDRESS+MBED_CONF_STORAGE_TDB_INTERNAL_INTERNAL_SIZE)",
    "fota.storage-size"                         : "(512*1024-MBED_CONF_STORAGE_TDB_INTERNAL_INTERNAL_SIZE)"

where

• "fota.block-device-type" defines the supported BlockDevice implementation and "FOTA_INTERNAL_FLASH_BD" is the Mbed-provided FlashIAPBlockDevice implementation.

• "fota.storage-start-address" defines where the firmware candidate storage starts.

• "fota.storage-size" defines the maximum size of the firmware candidate that client can be download and store.

Setting authorization handler

The application can pass a function callback to this API and it will be called during

• Download request.
• Install request.

Use this API call:

static void update_authorize(int32_t request, uint64_t priority)
{
    switch (request)
    {
        case ARM_UCCC_REQUEST_DOWNLOAD:
            printf("Request Download\r\n");
            ARM_UC_Authorize(ARM_UCCC_REQUEST_DOWNLOAD);
            break;
        case ARM_UCCC_REQUEST_INSTALL:
            printf("Request Install\r\n");
            ARM_UC_Authorize(ARM_UCCC_REQUEST_INSTALL);
            break;
        case ARM_UCCC_REQUEST_INVALID:
        default:
            break;
    }
}

pdmc_connect_update_set_authorize_handler(update_authorize);

If you don't set this API, Client Lite downloads the firmware and installs it automatically without any application-level intervention.

Setting error handler

The application can pass a function callback to this API and it will be called to notify the application about any errors during the firmware update process.

Use this API call:

static void update_error(int32_t error)
{
    printf("update_error() error: %" PRIi32, error);
}

pdmc_connect_update_set_error_handler(update_error);

We recommend that you set this API if the application needs to know about any errors occurring during the firmware update process.

Setting update progress

The application can pass a function callback to this API and it will be called to inform the application about the firmware download progress while the new firmware is being downloaded.

Use this API call:

static void update_progress(uint32_t progress, uint32_t total)
{
    printf("update_progress [%d/%d]\n", progress, total);
}

pdmc_connect_update_set_progress_handler(update_error);

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

Preparing firmware update

See the application tutorial for quick example how to do a full image update.

Refer to the full update documentation on the Pelion Device Management documentation site:

• End to end Device Management Update development tutorials for performing update campaigns.
• Creating and using delta images for Update for using delta update.

Note: Code compilation, device management with Pelion and the update processes are identical in the Device Management Client example.