Over-the-air (OTA) updates of external MCUs with Zephyr

This guide explains how to set up the Spotflow device module to perform over-the-air (OTA) updates of external MCUs connected to your Zephyr device. If you want to automatically update the firmware that runs the module itself (the main firmware), see Over-the-air (OTA) updates with Zephyr. To support both scenarios in one application, see the notes below.

manifest:
    projects:
    - name: spotflow
        revision: main
        path: modules/lib/spotflow
        url: https://github.com/spotflow-io/device-sdk

west update

CONFIG_SPOTFLOW=y
CONFIG_SPOTFLOW_DEVICE_ID="zephyr-device-001"
CONFIG_SPOTFLOW_INGEST_KEY="{your-ingest-key}"

CONFIG_SPOTFLOW_OTA=y

# Automatic main firmware handling is not needed when updating only external MCUs
CONFIG_SPOTFLOW_OTA_AUTO_HANDLE_MAIN_FIRMWARE=n

# Persistent storage for OTA attempt state and results
CONFIG_NVS=y
CONFIG_SETTINGS_NVS=y

#include <spotflow/ota.h>

static SPOTFLOW_DEFINE_DOWNLOADER(external_mcu_downloader);

static void write_external_mcu_block(const struct spotflow_artifact_block *block,
                                     struct spotflow_downloader *downloader,
                                     void *ctx)
{
    /* Write block->data to the external MCU. */
}

enum spotflow_ota_result
spotflow_on_handle_firmware_update(const struct spotflow_firmware_info *info)
{
    int ret = spotflow_download_artifact(&external_mcu_downloader,
                                         info->download_request,
                                         write_external_mcu_block,
                                         NULL);
    if (ret < 0) {
        return SPOTFLOW_OTA_RESULT_FAILED;
    }

    /* Verify and activate the firmware on the external MCU. */
    return SPOTFLOW_OTA_RESULT_SUCCEEDED;
}

Advanced: Handle cancellation

When a device is currently processing an update attempt and you stop the deployment or supersede it with a new one, the cloud sends a cancellation request to the device. To prevent half-finished updates, the Spotflow device module considers the cancellation actionable only if no firmware update has already reported its result.

When the module receives an actionable cancellation, it calls spotflow_on_update_canceled(). Your handler can use it to stop ongoing work, for example by canceling the download started by spotflow_on_handle_firmware_update():

void spotflow_on_update_canceled(void)
{
    spotflow_cancel_download(&external_mcu_downloader);
}

Because spotflow_on_update_canceled() runs on the system workqueue, do not perform blocking work in it.

You can also poll for actionable cancellation using spotflow_is_update_canceled(). Report successful cancellation by returning SPOTFLOW_OTA_RESULT_CANCELED from spotflow_on_handle_firmware_update():

enum spotflow_ota_result
spotflow_on_handle_firmware_update(const struct spotflow_firmware_info *info)
{
    int ret = spotflow_download_artifact(&external_mcu_downloader,
                                         info->download_request,
                                         write_external_mcu_block,
                                         NULL);

    if (spotflow_is_update_canceled()) {
        return SPOTFLOW_OTA_RESULT_CANCELED;
    }

    if (ret < 0) {
        return SPOTFLOW_OTA_RESULT_FAILED;
    }

    /* Verify and activate the firmware on the external MCU. */
    return SPOTFLOW_OTA_RESULT_SUCCEEDED;
}

Advanced: Combine automatic and manual handling of OTA updates

You can combine both automatic and manual handling of OTA updates in one application. Keep CONFIG_SPOTFLOW_OTA_AUTO_HANDLE_MAIN_FIRMWARE=y to let the SDK update the main firmware automatically, and still implement spotflow_on_handle_firmware_update() for external MCUs.

The Spotflow device module processes firmware updates in the order specified when you create the deployment. If any firmware update fails, the module cancels the remaining firmware updates in the attempt.

How device module works

See How device module works in the main Zephyr OTA update guide for the details of attempt processing, persistence, threading, security, and configuration.

Reference repository materials

• Public API: spotflow/ota.h, spotflow/downloader.h
• OTA sample
• OTA Kconfig options

Learn more