The OTA Bootloader Abstraction library has implementation for bootloader specific storage interface APIs for handling OTA upgrade images. This library is expected to work only with the Infineon ota-update library which downloads OTA upgrade images on PSoC6, 20829, 89829, XMC7100 and XMC7200 platforms. Application should not directly call the bootloader-specific storage interface APIs. Rather, during Infineon OTA Agent initialization, the application needs to register these bootloader-specific storage interface APIs as callback APIs. See the ota-update library documentation for more details.
Library Version | Supported MTB version | Remarks |
---|---|---|
ota-bootloader-abstraction v1.5.0 | ModusToolbox 3.2 | XMC7100(KIT_XMC71_EVK_LITE_V1) platform support added. Image encryption support added for 20829 platform. |
ota-bootloader-abstraction v1.4.0 | ModusToolbox 3.2 | CY8CEVAL-062S2-CYW955513SDM2WLIPA kit support added. Support for secure LCS and OTA image encryption has been added to the CYW920829 platform. cysecuretools v6.1 or greater is required. |
ota-bootloader-abstraction v1.2.0 | ModusToolbox 3.2 | CYW955913EVK-01 platform support added |
ota-bootloader-abstraction v1.1.0 | ModusToolbox 3.2 | CYW89829 platform support added |
ota-bootloader-abstraction v1.0.0 | ModusToolbox 3.1 | cysecuretools v5.0 or greater is required |
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.
1.1 OTA storage interface callback APIs structure
OTA storage interface callback APIs structure and callback APIs syntax are defined in 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_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;
1.2 OTA storage interface APIs implementation
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_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 ota-bootloader-abstraction library implements only storage interface APIs for MCUBootloader based OTA and CYW955913EVK-01 in-built Bootloader based OTA.
ota-bootloader-abstraction library has below support for MCUBootloader based OTA on PSoC6, 20829, 89829, XMC7100 and XMC7200 platforms.
-
Template flashmaps for PSoC6, 20829, 89829, XMC7100 and XMC7200 platforms.
-
Template linker files for GCC_ARM, ARM, and IAR toolchains.
-
Storage operation callback APIs to handle MCUBootloader based upgrade image.
-
Prebuild and Postbuild scripts for generating and signing MCUBootloader based BOOT and UPGRADE image of an OTA Application.
Supported devices:
- PSoC™ 6 MCU with
- AIROC™ CYW4343W
- CYW43012 Wi-Fi & Bluetooth® combo chip
- CYW920829M2EVK-02 evaluation board.
- CY8CKIT-062-BLE
- CY8CPROTO-063-BLE
- CYBLE-416045-EVAL
- KIT_XMC72_EVK
- KIT_XMC72_EVK_MUR_43439M2
- KIT_XMC71_EVK_LITE_V1
- CYW989829M2EVB-01
- CY8CEVAL-062S2-CYW955513SDM2WLIPA
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:
- ROM boot will start MCUBootloader
- If no update is downloaded, MCUBootloader starts the current application.
- MCUBootloader determines if there is an update in the Secondary Slot
- If there is an update available:
a. MCUBootloader verifies the update.
b. MCUBootloader SWAPs (or OVERWRITEs) the current with the update applications.
c. MCUBootloader starts the new (updated) application.
d. The updated application must call cy_ota_storage_image_validate() to validate the update.
e. For SWAP, if the new application does not call cy_ota_storage_image_validate(), MCUBootloader will REVERT on the next reset.
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 MCUBootloader App Information.
2.1 Flash layout requirements
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, please see OTA Flash Layout Information.
2.2 Target and Flashmap Use
Template flashmaps for the supported targets as of v1.0.0 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 |
CYW989829M2EVB-01 | 0K | CYW89829 | Default - cyw89829_xip_swap_single.json cyw89829_xip_overwrite_single.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) |
cyw89829_xip_overwrite_single.json | External only (primary and secondary) |
cyw89829_xip_swap_single.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) |
2.3 MCUBootApp Cloning and Building
MCUBootloader Application i.e MCUBootApp is a standalone application. It is an open source software taken and 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).
- MCUBootApp runs on the CM0+ CPU and starts any OTA enabled application on CM4 core in case of multicore Psoc6 devices and on CM7 core in case of XMC7100 and XMC7200 devices.
- In case of 20829 and 89829 devices, MCUBootApp runs on CM33 CPU along with the OTA enabled applications.
MCUBoot itself is not OTA upgradable.
For cloning and building MCUBootApp refer to MCUBootApp README.
ota-bootloader-abstraction library has below support for CYW955913EVK-01 in-built Bootloader based OTA.
- Storage operation callback APIs to handle the in-built Bootloader based upgrade image.
Supported devices:
- CYW955913EVK-01.
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:
- ROM boot will start CYW955913EVK-01 in-built Bootloader.
- The in-built Bootloader starts the current application in Active DS.
- If an update is available, the OTA application uses the ota-update and ota-bootloader-abstraction library to download and store it in the Non-Active DS. Subsequently,
a. When the switch image API (cy_ota_storage_switch_to_new_image) is called, the CYW955913EVK-01 in-built Bootloader verifies the update image headers and certificates.
b. Upon finding a valid upgrade image, the CYW955913EVK-01 in-built Bootloader activates the Non-Active DS and designates the active DS as Non-Active DS.
c. Following a reset, the CYW955913EVK-01 in-built Bootloader initiates the application (Upgraded Image) in the Active DS.
-
Before enabling MCUBootloader based OTA in an application, the user must build and program MCUBootApp on the chosen platform(s). Refer to refer to MCUBootApp README.
-
Create an ota-bootloader-abstraction.mtb file to pull ota-bootloader-abstraction library which has storage APIs to handle the MCUBootloader based OTA upgrade files. Place ota-bootloader-abstraction.mtb in the application deps folder. The contents of ota-bootloader-abstraction.mtb should be as follows:
https://github.com/Infineon/ota-bootloader-abstraction#latest-v1.X#$$ASSET_REPO$$/ota-bootloader-abstraction/latest-v1.X
-
After adding ota-bootloader-abstraction.mtb file to the deps folder of your application, Run the command 'make getlibs' to fetch ota-bootloader-abstraction library and its dependencies.
make getlibs
-
Update OTA Application makefile by referring OTA Bootloader Abstraction Makefile Readme.
-
For MCUBootloader based OTA Support, add the following components to the Application makefile.
COMPONENTS+=MCUBOOT
-
Make sure that the Python module is installed on your computer, preferably Python version 3.8. Additionally, Application need to provide the path to the installed Python module by setting CY_PYTHON_PATH in the OTA Application makefile. The pre and post build scripts of the ota-bootloader-abstraction library use this Python module to parse memory configurations.
CY_PYTHON_PATH = <Path to Python module>
-
ota-bootloader-abstraction library has makefile mcuboot_support.mk located in makefiles folder which has necessary pre and post build scripts for generating MCUBootloader based BOOT and UPGRADE images of OTA application.
-
Include mcuboot_support.mk which is located in makefiles folder from OTA Application makefile.
include ../mtb_shared/ota-bootloader-abstraction/<version>/makefiles/mcuboot/mcuboot_support.mk
-
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);
-
OTA storage interface calls Flash operations(Read, Write, erase) to store upgrade images in UPGRADE slot. ota-bootloader-abstraction implements flash operation using mtb-pdl-cat1 library APIs and implementation is available in configs folder. User can use same implementation by copying contents of configs folder to application space or Can implement flash operation APIs defined in cy_ota_flash.h.
-
For Secure platforms like PSoC64, MCUBootloader will get programmed during kit provisioning process. Follow steps in 3.1 before building OTA application.
-
During application build, Required BOOT and UPGRADE images(.bin) of OTA application will get generated in configured build directory.
-
Program the BOOT image and use UPGRADE image (.bin) for OTA.
4.1 Provisioning PSoC64
-
For Secure platforms like PSoC64, MCUBootloader will get programmed during kit provisioning process.
-
Prior to provisioning the PSoC64 kit (CY8CKIT-064B0S2-4343W), User need to create policies and keys for provisioning. To do this, execute the following 'init' command from application root folder.
cysecuretools -t CY8CKIT-064B0S2-4343W init
-
The init command creates the keys, packets, policy, and prebuilt directories in application root folder. These keys and policies are utilized during the provisioning and OTA image signing process.
-
Copy policy policy_single_CM0_CM4_smif_swap.json from configs folder and replace it with the one in policy folder which is generated after executing init command.
-
Please copy the policy_single_CM0_CM4_smif_swap.json file from the configs folder and replace it with the version in the policy folder, which will be generated after running the init command.
-
The public key is programmed during the provisioning for further image verification. The private key is used to sign the image with the user application. Create a private key using below command. The public part of the key will be taken from the private during provisioning.
cysecuretools -t CY8CKIT-064B0S2-4343W -p policy/policy_single_CM0_CM4_swap.json create-keys
-
Provision the kit with policy policy_single_CM0_CM4_smif_swap.json. Refer Provisioning Steps for CY8CKIT-064B0S2-4343W for complete provisionig steps.
-
During provisioning, the MCU bootloader is also loaded and executed from the CM0 core upon reboot.
-
Create an ota-bootloader-abstraction.mtb file to pull ota-bootloader-abstraction library which has storage APIs to handle the MCUBootloader based OTA upgrade files. Place ota-bootloader-abstraction.mtb in the application deps folder. The contents of ota-bootloader-abstraction.mtb should be as follows:
https://github.com/Infineon/ota-bootloader-abstraction#latest-v1.X#$$ASSET_REPO$$/ota-bootloader-abstraction/latest-v1.X
-
After adding ota-bootloader-abstraction.mtb file to the deps folder of your application, Run the command 'make getlibs' to fetch ota-bootloader-abstraction library and its dependencies.
make getlibs
-
Update OTA Application makefile by referring OTA Bootloader Abstraction Makefile Readme.
-
For CYW955913EVK-01 in-built Bootloader based OTA Support, add the following components to the Application makefile.
COMPONENTS+=CYW955913SDCM2WLIPA
-
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);
-
OTA storage interface calls Flash operations(Read, Write, erase) to store upgrade images in Non active DS.
-
Once after succesfully downloading OTA upgrade image, switch to new image by calling cy_ota_storage_switch_to_new_image() which is available in source/COMPONENT_CYW955913SDCM2WLIPA/cy_ota_storage_api.c.
-
During application build, Required BOOT and UPGRADE images(.bin) of OTA application will get generated in configured build directory.
-
Program the BOOT image and use UPGRADE image (.bin) for OTA.
The ota-bootloader-abstraction library disables all debug log messages by default. Do the following to enable log messages:
-
Add the
ENABLE_OTA_BOOTLOADER_ABSTRACTION_LOGS
macro to the DEFINES in the code example's makefile. The makefile entry should look like as follows:DEFINES+=ENABLE_OTA_BOOTLOADER_ABSTRACTION_LOGS
-
Call the
cy_log_init()
function provided by the cy-log module. cy-log is part of the connectivity-utilities library. See connectivity-utilities library API documentation for cy-log details.
When using ModusToolbox, you will need to install the pip requirements to Python in the ModusToolbox installation.
\<ModusToolbox\>/tools_3.*/python/python -m pip install -r \<ota-bootloader-abstraction\>scripts/mcuboot/imgtool/requirements.txt
- GCC
- IAR
- ARM C
For the toolchain version information, please refer to ota-bootloader-abstraction Release.md.
- FreeRTOS
- ThreadX
- PSoC™ 6 Wi-Fi BT Prototyping Kit (CY8CPROTO-062-4343W)
- PSoC™ 62S2 Wi-Fi BT Pioneer Kit (CY8CKIT-062S2-43012)
- PSoC™ 62S3 Wi-Fi BT Prototyping Kit (CY8CPROTO-062S3-4343W)
- PSoC™ 64 Secure Boot Wi-Fi BT Pioneer Kit (CY8CKIT-064B0S2-4343W)
- CY8CEVAL-062S2 Evaluation Kit(CY8CEVAL-062S2-LAI-4373M2, CY8CEVAL-062S2-MUR-43439M2 and CY8CEVAL-062S2-CYW955513SDM2WLIPA)
- PSoC™ 6-BLE Pioneer Kit (CY8CKIT-062-BLE)
- PSoC™ 6 BLE Prototyping Kit (CY8CPROTO-063-BLE)
- EZ-BLE Arduino Evaluation Board (CYBLE-416045-EVAL)
- AIROC™ CYW20829 Bluetooth® LE SoC (CYW920829M2EVK-02)
- XMC7200 Evaluation Kit (KIT_XMC72_EVK)
- XMC7200 Evaluation Kit (KIT_XMC72_EVK_MUR_43439M2)
- XMC7100 Evaluation Kit (KIT_XMC71_EVK_LITE_V1)
- AIROC™ CYW989820M2EVB-01 Evaluation kit(CYW989820M2EVB-01)
- CYW955913EVK-01 Wi-Fi Bluetooth® Prototyping Kit (CYW955913EVK-01)
This example uses the board's default configuration. See the kit user guide to ensure the board is configured correctly.
Note: Before using this code example, make sure that the board is upgraded to KitProg3. The tool and instructions are available in the Firmware Loader GitHub repository. If you do not upgrade, you will see an error like "unable to find CMSIS-DAP device" or "KitProg firmware is out of date".
-
Connectivity utilities API documentation - for cy-log details
-
ModusToolbox Software Environment, Quick Start Guide, Documentation, and Videos
Infineon also provides a wealth of data at www.infineon.com to help you select the right device, and quickly and effectively integrate it into your design.
For PSoC™ 6 MCU devices, see How to Design with PSoC 6 MCU - KBA223067 in the Infineon community.