 |
Over The Air (OTA) Bootloader Abstraction Library
|
|
Over The Air (OTA) Bootloader Abstraction Library
|
The OTA Bootloader Abstraction library implements the bootloader-specific storage interface APIs required to handle Over-the-Air (OTA) upgrade images on Infineon connectivity-enabled MCUs. It is designed to work together with the Infineon ota-update library, which downloads OTA upgrade images on PSOC™ 6, CYW20829, CYW89829, XMC7100, XMC7200, CYW955913, and PSOC™ Edge E84 (PSE84) platforms.
An application does not call the bootloader-specific storage interface APIs directly. Instead, during Infineon OTA Agent initialization, the application registers these storage interface APIs as callbacks. The ota-update library then invokes the registered callbacks to store, verify, and activate downloaded upgrade images. The library also provides the build environment (template flashmaps, linker files, and pre/post-build scripts) needed to generate BOOT and UPGRADE images for OTA applications. See the ota-update Reference Manual for more details.
Use this library when building an OTA-capable application with the Infineon ota-update library and you need bootloader-specific storage handling for downloaded upgrade images. It is imported automatically by the ModusToolbox™ MCUBootloader-based and in-built-bootloader-based OTA code examples, and is required whenever an OTA application must store, verify, and activate an upgrade image through MCUBootloader or the CYW955913EVK-01 in-built bootloader.
This library supports the following Infineon device families (see ./RELEASE.md "RELEASE.md" for the exact list of validated kits):
Additional requirements:
This version of the library was validated for compatibility with the following software and tools:
| Software and Tools | Version |
|---|---|
| ModusToolbox™ Software Environment | 3.9 |
| - ModusToolbox™ Device Configurator | 5.90 |
| - ModusToolbox™ Bluetooth Configurator | 3.90 |
| GCC Compiler | 14.2.1 |
| IAR Compiler | 9.50.2 |
| Arm Compiler 6 | 6.22 |
| LLVM Compiler | 22.1.0 |
Start from an Empty ModusToolbox™ application, or from one of the OTA code examples listed under Related Code Examples (for example, mtb-example-ota-mqtt), which import this library and the ota-update library automatically.
Add the required libraries using the ModusToolbox™ Library Manager (available in the ModusToolbox™ for VS Code extension and in the Eclipse IDE), or by creating the corresponding .mtb files in the application's deps folder and running make getlibs.
.mtb contents: ``` https://github.com/Infineon/ota-bootloader-abstraction#latest-v1.X#$$ASSET_REPO$$/ota-bootloader-abstraction/latest-v1.X ```.mtb contents: ``` https://github.com/mcu-tools/mcuboot#v1.9.6-cypress#$$ASSET_REPO$$/mcuboot/v1.9.6-cypress ``**serial-memory** - required for flash operations on the PSOC™ Edge E84 (PSE84) platform..mtbcontents: `` mtb:serial-memory#release-v3.0.0#$$ASSET_REPO$$/serial-memory/release-v3.0.0 ```After adding the .mtb files to the deps folder, run: ``` make getlibs ```
Enable the bootloader storage component that matches your target, and configure the OTA build settings, in the application Makefile:
```
COMPONENTS+=MCUBOOT
COMPONENTS+=CYW955913SDCM2WLIPA ```
For MCUBootloader-based OTA, also set the OTA platform, linker file, Python path, and include the library's pre/post-build makefile:
``` OTA_PLATFORM=<platform_type> OTA_LINKER_FILE=<OTA linker="" file="" path>=""> CY_PYTHON_PATH=<Path to="" python="" module>=""> include ../mtb_shared/ota-bootloader-abstraction/<version>/makefiles/mcuboot/mcuboot_support.mk ```
See ./source/COMPONENT_MCUBOOT/MCUBOOT_OTA_MAKEFILE_INFO_README.md "OTA Application Makefile settings" for the full list of Makefile defines. Detailed, platform-specific enablement steps are documented under Configuration Reference.
Include the OTA storage interface header for your bootloader component in the application source that registers the storage callbacks:
```c #include "cy_ota_storage_api.h" ```
This quick start demonstrates registering the OTA storage interface callbacks and starting the OTA Agent for an MCUBootloader-based OTA application. Follow these steps starting from an Empty application:
Step 1: Build and program MCUBootApp on your target. See ./source/COMPONENT_MCUBOOT/MCUBOOT_APP_README.md "MCUBootApp Usage Instructions".
Step 2: Add the required libraries (see Add Required Libraries) and run make getlibs.
Step 3: Configure the application Makefile (see Configure Makefile), including COMPONENTS+=MCUBOOT, OTA_PLATFORM, OTA_LINKER_FILE, CY_PYTHON_PATH, and the mcuboot_support.mk include.
Step 4: Register the storage interface callbacks and start the OTA Agent (see Sample Code).
Step 5: Build the application. The BOOT and UPGRADE images (.bin) are generated in the configured build directory. Program the BOOT image and use the UPGRADE image for OTA.
Expected Outcome: See Expected Outcome.
Register the bootloader storage interface callbacks in the cy_ota_storage_interface_t structure and pass it when starting the OTA Agent:
```c /* OTA storage interface callbacks */ cy_ota_storage_interface_t ota_interfaces = { .ota_file_open = cy_ota_storage_open, .ota_file_read = cy_ota_storage_read, .ota_file_write = cy_ota_storage_write, .ota_file_close = cy_ota_storage_close, .ota_file_verify = cy_ota_storage_verify, .ota_file_set_boot_pending = cy_ota_storage_set_boot_pending, .ota_file_validate = cy_ota_storage_image_validate, .ota_file_get_app_info = cy_ota_storage_get_app_info };
/* Register OTA storage interface callbacks with the OTA Agent */ cy_ota_agent_start(&ota_test_network_params, &ota_test_agent_params, &ota_interfaces, &ota_context); ```
For the CYW955913EVK-01 in-built bootloader, omit .ota_file_set_boot_pending and, after a successful download, switch to the new image by calling cy_ota_storage_switch_to_new_image().
When the Quick Start example is built and run, you should observe:
.bin) of the OTA application are generated in the configured build directory.CY_PYTHON_PATH points to it. On Windows 10, install the pip requirements as described in Note on Using Windows 10.cy_ota_storage_image_validate() to confirm the update; otherwise MCUBootloader reverts on the next reset.This section provides comprehensive documentation of the bootloader support, flash layouts, build configuration, and platform-specific enablement steps for the library. For the COMPONENT flags and Makefile defines summary, see Configure Makefile.
To add different bootloader support on Infineon connectivity-enabled MCU platforms, ota-update library offloads bootloader specific storage interface APIs using callback mechanism. To handle downloaded OTA upgrade images ota-update library calls registered bootloader-specific storage interface callbacks. The ota-bootloader-abstraction library includes an implementation of bootloader-specific storage interface APIs for various bootloaders. Additionally, it provides the necessary build environment to create BOOT and UPGRADE images for OTA applications.
The OTA storage interface callback APIs structure and the callback API prototypes are defined in the ota-update library. Refer ota-update library API header file for details.
``` typedef struct cy_ota_storage_interface_s { cy_ota_file_open ota_file_open; /**< Creates and open new receive file for the data chunks as they come in. */ cy_ota_file_read ota_file_read; /**< Reads the flash data starting from the given offset. */ cy_ota_file_write ota_file_write; /**< Write a data to the flash at the given offset. */ cy_ota_file_close ota_file_close; /**< Close the underlying receive file in the specified OTA context. */ cy_ota_file_verify ota_file_verify; /**< Authenticate received OTA update file specified in the OTA context. */ cy_ota_file_set_pending ota_file_set_boot_pending; /**< To Mark the image in the inactive slot as pending. */ cy_ota_file_validate ota_file_validate; /**< The application has validated the new OTA image. */ cy_ota_file_get_app_info ota_file_get_app_info; /**< Get Application info like Application version and Application ID. */ } cy_ota_storage_interface_t; ```
| Storage operation callback | Bootloader | API | Remarks |
|---|---|---|---|
| ota_file_open | MCUBootloader | cy_ota_storage_open() | Available in source/COMPONENT_MCUBOOT/cy_ota_storage_api.c |
| ota_file_read | MCUBootloader | cy_ota_storage_read() | Available in source/COMPONENT_MCUBOOT/cy_ota_storage_api.c |
| ota_file_write | MCUBootloader | cy_ota_storage_write() | Available in source/COMPONENT_MCUBOOT/cy_ota_storage_api.c |
| ota_file_close | MCUBootloader | cy_ota_storage_close() | Available in source/COMPONENT_MCUBOOT/cy_ota_storage_api.c |
| ota_file_verify | MCUBootloader | cy_ota_storage_verify() | Available in source/COMPONENT_MCUBOOT/cy_ota_storage_api.c |
| ota_file_set_boot_pending | MCUBootloader | cy_ota_storage_set_boot_pending() | Available in source/COMPONENT_MCUBOOT/cy_ota_storage_api.c |
| ota_file_validate | MCUBootloader | cy_ota_storage_image_validate() | Available in source/COMPONENT_MCUBOOT/cy_ota_storage_api.c |
| ota_file_get_app_info | MCUBootloader | cy_ota_storage_get_app_info() | Available in source/COMPONENT_MCUBOOT/cy_ota_storage_api.c |
| Storage operation callback | Bootloader | API | Remarks |
|---|---|---|---|
| ota_file_open | CYW955913SDCM2WLIPA | cy_ota_storage_open() | Available in source/COMPONENT_CYW955913SDCM2WLIPA/cy_ota_storage_api.c |
| ota_file_read | CYW955913SDCM2WLIPA | cy_ota_storage_read() | Available in source/COMPONENT_CYW955913SDCM2WLIPA/cy_ota_storage_api.c |
| ota_file_write | CYW955913SDCM2WLIPA | cy_ota_storage_write() | Available in source/COMPONENT_CYW955913SDCM2WLIPA/cy_ota_storage_api.c |
| ota_file_close | CYW955913SDCM2WLIPA | cy_ota_storage_close() | Available in source/COMPONENT_CYW955913SDCM2WLIPA/cy_ota_storage_api.c |
| ota_file_verify | CYW955913SDCM2WLIPA | cy_ota_storage_verify() | Available in source/COMPONENT_CYW955913SDCM2WLIPA/cy_ota_storage_api.c |
| ota_file_validate | CYW955913SDCM2WLIPA | cy_ota_storage_image_validate() | Available in source/COMPONENT_CYW955913SDCM2WLIPA/cy_ota_storage_api.c |
| ota_file_get_app_info | CYW955913SDCM2WLIPA | cy_ota_storage_get_app_info() | Available in source/COMPONENT_CYW955913SDCM2WLIPA/cy_ota_storage_api.c |
Note: The current version of the ota-bootloader-abstraction library implements storage interface APIs only for MCUBootloader-based OTA and the CYW955913EVK-01 in-built bootloader-based OTA.
The ota-bootloader-abstraction library provides MCUBootloader-based OTA support on PSOC™ 6, CYW20829, CYW89829, XMC7100, and XMC7200 platforms.
bsps/TARGET_APP_<Target>/config directory and remove design.modus, then copy and paste ./template_linkers/PSE84/<USE-CASE>/<EPC2/EPC4>/design.modus file to bsps/TARGET_APP_<Target>/configNote:
CY_CM33_NS_APP_BOOT_ADDR and CY_CM55_APP_BOOT_ADDR macros.Supported devices:
The ota-update along with ota-bootloader-abstraction library works in concert with MCUBootloader to provide a no-fail solution to updating device software in the field.
MCUBootloader is a secure bootloader application for 32-bit microcontrollers and users should build it outside of the user OTA application. It is programmed separately to the device before flashing the user OTA application and is not updated for the life of the device.
User OTA application will include the ota-update library along with ota-bootloader-abstraction library, which will set the appropriate flags so that MCUBootloader knows when to perform an update of your application. The OTA library will download a new (updated) application, store it in flash, and set flags so that on the next reset, MCUBootloader will see there is an update available.
The basic device boot sequence is as follows:
Note: On secure MCUs such as PSOC™ 64, MCUBootloader is flashed as part of the provisioning step performed by the provisioning tools, and does not need to be built separately. For more information, see the ./source/COMPONENT_MCUBOOT/MCUBOOT_APP_README.md "MCUBootApp Usage Instructions".
Note: The MCUBootloader direct execute-in-place (XIP) functionality is currently supported only on the CYW920829 and CYW989829 platforms, and is compatible exclusively with the GCC-ARM toolchain.
MCUBootApp and the OTA enabled application must use the same flash layout.
The flash is separated into sections also called slots. The current application occupies the Primary (BOOT) Slot. The update application (new version) will be downloaded into the Secondary (UPGRADE) Slot. Besides primary and secondary slots, MCUBootApp has a code section, a section for a "Swap Buffer" and a section for "Status Info".
| Section | Size | Description |
|---|---|---|
| MCUBootApp | 0x00028000 | MCUBootApp code |
| Primary Slot | Varies by flash size | User Application (current) |
| Secondary Slot | Same size as Primary | Update Application (new) |
| Swap Buffer | Varies by flash size | Used by MCUBootApp for SWAP operation |
| Status | Varies by size of Slots | Used by MCUBootApp for update status |
For more information, see the ./source/COMPONENT_MCUBOOT/MCUBOOT_OTA_FLASH_LAYOUT_README.md "OTA Flash Layout Information".
Template flashmaps for the supported targets as of v1.X release. These flashmaps are available in MCUBootloader based OTA Flashmap folder.
| Target | Internal Flash size | OTA_PLATFORM | Flashmaps |
|---|---|---|---|
| CY8CPROTO-062-4343W CY8CKIT-062S2-43012 CY8CPROTO-062-4343W CY8CEVAL-062S2-LAI-4373M2 CY8CEVAL-062S2-MUR-43439M2 CY8CEVAL-062S2-CYW955513SDM2WLIPA | 2M | PSOC_062_2M | Default - psoc62_2m_ext_swap_single.json psoc62_2m_ext_overwrite_single.json psoc62_2m_int_overwrite_single.json psoc62_2m_int_swap_single.json |
| CY8CKIT-062-BLE | 1M | PSOC_062_1M | Default - psoc62_1m_cm0_int_swap_single.json |
| CY8CPROTO-063-BLE CYBLE-416045-EVAL | 1M | PSOC_063_1M | Default - psoc63_1m_cm0_int_swap_single.json |
| CY8CPROTO-062S3-4343W | 512K | PSOC_062_512K | Default - psoc62_512k_xip_swap_single.json psoc62_512k_ext_overwrite_single.json psoc62_512k_ext_swap_single.json |
| CY8CKIT-064B0S2-4343W | 2M | PSOC_064_2M | Default - policy_single_CM0_CM4_smif_swap.json |
| CYW920829M2EVK-02 | 0K | CYW20829 | Default - cyw20829_xip_swap_single.json cyw20829_xip_overwrite_single.json cyw20829_xip_direct.json |
| CYW989829M2EVB-01 | 0K | CYW89829 | Default - cyw89829_xip_swap_single.json cyw89829_xip_overwrite_single.json cyw89829_xip_direct.json |
| KIT_XMC71_EVK_LITE_V1 | 4MB | XMC7100 | Default - xmc7100_int_swap_single.json xmc7100_int_overwrite_single.json |
| KIT_XMC72_EVK KIT_XMC72_EVK_MUR_43439M2 | 8MB | XMC7200 | Default - xmc7200_int_swap_single.json xmc7200_int_overwrite_single.json |
| 2M Internal Flash Maps | Memory Usage |
|---|---|
| psoc62_2m_ext_overwrite_single.json | Internal primary, external secondary |
| psoc62_2m_ext_swap_single.json | Internal primary, external secondary |
| psoc62_2m_int_overwrite_single.json | Internal only (primary and secondary) |
| psoc62_2m_int_swap_single.json | Internal only (primary and secondary) |
| 1M Internal Flash Maps | Memory Usage |
|---|---|
| psoc62_1m_cm0_int_swap_single.json | Internal only (primary and secondary) |
| psoc63_1m_cm0_int_swap_single.json | Internal only (primary and secondary) |
| 512K Internal Flash Maps | Memory Usage |
|---|---|
| psoc62_512k_ext_overwrite_single.json | Internal primary, external secondary |
| psoc62_512k_ext_swap_single.json | Internal primary, external secondary |
| psoc62_512k_xip_swap_single.json | External only (primary and secondary) |
| 0K Internal Flash Maps | Memory Usage |
|---|---|
| cyw20829_xip_overwrite_single.json | External only (primary and secondary) |
| cyw20829_xip_swap_single.json | External only (primary and secondary) |
| cyw20829_xip_direct.json | External only (primary and secondary) |
| cyw89829_xip_overwrite_single.json | External only (primary and secondary) |
| cyw89829_xip_swap_single.json | External only (primary and secondary) |
| cyw89829_xip_direct.json | External only (primary and secondary) |
| 4M Internal Flash Maps | Memory Usage |
|---|---|
| xmc7100_int_swap_single.json | Internal only (primary and secondary) |
| xmc7100_int_overwrite_single.json | Internal only (primary and secondary) |
| 8M Internal Flash Maps | Memory Usage |
|---|---|
| xmc7200_int_swap_single.json | Internal only (primary and secondary) |
| xmc7200_int_overwrite_single.json | Internal only (primary and secondary) |
The MCUBootloader application (MCUBootApp) is a standalone application. It is open source software that is customized in terms of flash map and is built outside of ModusToolbox™. MCUBootApp is programmed/flashed on the device one time, at manufacture (or for development).
MCUBoot itself is not OTA upgradable.
For cloning and building MCUBootApp refer to ./source/COMPONENT_MCUBOOT/MCUBOOT_APP_README.md "MCUBootApp README".
https://github.com/Infineon/edgeprotecttools/blob/master/docs/README_CYW20829.md ``` cysecuretools -t cyw89829 encrypt –input $OTA_APP_SIGNED_BIN –output $OTA_APP_ENCRYPTED_BIN –iv 0x08020000 –enckey ./keys/encrypt_key.bin –nonce $NONCE_FILE ``` *** NOTE : *** When encrypting the OTA application BOOT image, ensure that you use the same encryption key that has been provisioned to the device, as well as the same nonce that was used for encrypting the MCUBootApp.ota-bootloader-abstraction library has below support for CYW955913EVK-01 in-built Bootloader based OTA.
Supported devices:
The ota-update along with ota-bootloader-abstraction library works in concert with CYW955913EVK-01 in-built Bootloader to provide a no-fail solution to updating device software in the field.
An in-built Bootloader is preprogrammed on CYW955913EVK-01 and is not updated for the life of the device.
User OTA application will include the ota-update library along with ota-bootloader-abstraction library, which will set the appropriate flags so that CYW955913EVK-01 in-built bootloader knows when to perform an update of your application. The OTA library will download a new (updated) application, store it in flash, and set flags so that on the next reset, Bootloader will see there is an update available.
The basic device boot sequence is as follows:
Configure OTA storage interface callback APIs in OTA application, And pass the same storage interface while starting OTA agent. ``` /* OTA storage interface callbacks */ cy_ota_storage_interface_t ota_interfaces = { .ota_file_open = cy_ota_storage_open, .ota_file_read = cy_ota_storage_read, .ota_file_write = cy_ota_storage_write, .ota_file_close = cy_ota_storage_close, .ota_file_verify = cy_ota_storage_verify, .ota_file_set_boot_pending = cy_ota_storage_set_boot_pending, .ota_file_validate = cy_ota_storage_image_validate, .ota_file_get_app_info = cy_ota_storage_get_app_info };
/* Register OTA storage interface callbacks with OTA agent */ cy_ota_agent_start(&ota_test_network_params, &ota_test_agent_params, &ota_interfaces, &ota_context);
```
Configure OTA storage interface callback APIs in OTA application, And pass the same storage interface while starting OTA agent. ``` /* OTA storage interface callbacks */ cy_ota_storage_interface_t ota_interfaces = { .ota_file_open = cy_ota_storage_open, .ota_file_read = cy_ota_storage_read, .ota_file_write = cy_ota_storage_write, .ota_file_close = cy_ota_storage_close, .ota_file_verify = cy_ota_storage_verify, .ota_file_validate = cy_ota_storage_image_validate, .ota_file_get_app_info = cy_ota_storage_get_app_info };
/* Register OTA storage interface callbacks with OTA agent */ cy_ota_agent_start(&ota_test_network_params, &ota_test_agent_params, &ota_interfaces, &ota_context);
```
The ota-bootloader-abstraction library disables all debug log messages by default. Do the following to enable log messages:
ENABLE_OTA_BOOTLOADER_ABSTRACTION_LOGS macro to the DEFINES in the code example's makefile. The makefile entry should look as follows: ``` DEFINES+=ENABLE_OTA_BOOTLOADER_ABSTRACTION_LOGS ```cy_log_init() function provided by the cy-log module. cy-log is part of the connectivity-utilities library. See the connectivity-utilities Reference Manual for cy-log details.When using ModusToolbox™, you need to install the pip requirements to the Python in the ModusToolbox™ installation:
``` <ModusToolbox>/tools_3.*/python/python -m pip install -r <ota-bootloader-abstraction>/scripts/mcuboot/imgtool/requirements.txt ```
For the toolchain version information, see ./RELEASE.md "RELEASE.md".
This library uses the board's default configuration. See the kit user guide to ensure the board is configured correctly.
Note: Before using an OTA code example, make sure the board is upgraded to KitProg3. The tool and instructions are available in the Firmware Loader GitHub repository. If you do not upgrade, you may see an error such as "unable to find CMSIS-DAP device" or "KitProg firmware is out of date".
For PSOC™ 6 MCU devices, see How to Design with PSOC 6 MCU - KBA223067 in the Infineon community.
The following table summarizes the library versions and the ModusToolbox™ version each was validated against:
| Library Version | Supported ModusToolbox™ Version | Remarks |
|---|---|---|
| ota-bootloader-abstraction v1.8 | ModusToolbox™ 3.6 | MCUBootloader-based direct-XIP OTA support added for CYW89829. Added encryption support for the PSOC™ Edge E84 (PSE84) platform. edgeprotecttools >= 1.5 required. |
| ota-bootloader-abstraction v1.7 | ModusToolbox™ 3.6 | Encrypted OTA image handling added for CYW955913EVK-01. Added support for the PSOC™ Edge E84 (PSE84) platform and MTB_HAL APIs. |
| ota-bootloader-abstraction v1.6 | ModusToolbox™ 3.5 | MCUBootloader-based direct-XIP OTA support added for CYW20829. |
| ota-bootloader-abstraction v1.5 | ModusToolbox™ 3.3 | XMC7100 (KIT_XMC71_EVK_LITE_V1) platform support added. Image encryption support added for the CYW20829 platform. |
| ota-bootloader-abstraction v1.4 | ModusToolbox™ 3.2 | CY8CEVAL-062S2-CYW955513SDM2WLIPA platform support added. Secure LCS and OTA image encryption added for the CYW920829 platform. cysecuretools v6.1 or greater required. |
| ota-bootloader-abstraction v1.2 | ModusToolbox™ 3.2 | CYW955913EVK-01 platform support added. |
| ota-bootloader-abstraction v1.1 | ModusToolbox™ 3.2 | CYW89829 platform support added. |
| ota-bootloader-abstraction v1.0 | ModusToolbox™ 3.1 | cysecuretools v5.0 or greater required. |
This library is provided under the Infineon software license terms. It is intended to be used together with the Infineon ota-update library and, for MCUBootloader-based OTA, pulls in the mcuboot library (mcu-tools/mcuboot, pinned to v1.9.6-cypress) and, on the PSOC™ Edge E84 (PSE84) platform, the serial-memory library; these dependent and third-party components are governed by their respective license terms. You are responsible for reviewing and accepting all applicable license terms.
$ Copyright 2026-YEAR Infineon Technologies AddOn $