search

Infineon / ota-update

Other
4 stars 0 forks source link

readme

Over-the-Air (OTA) Update Middleware Library

The OTA library provides support for downloading Over-The-Air update of the application code running on an Infineon device. Supported devices:

For devices with both Wi-Fi and Bluetooth® Interfaces, the device can use Wi-Fi or Bluetooth® Interfaces.

For WiFi and Ethernet, the OTA library utilizes MQTT or HTTP and TLS to securely connect to an MQTT Broker/HTTP server to download the user application.

For Bluetooth®, the OTA library works with an intermediate peer application on a laptop (or phone) to push the image to the device.

To handle the downloaded upgrade image, the user must implement storage API callbacks based on the chosen bootloader.

NOTE: The library 'ota-bootloader-abstraction' includes storage API callbacks implementation that handles MCUBootloader based images and in-built bootloader based (CYW955913SDCM2WLIPA platform) images. To use these storage API callbacks implementation, user must register these callbacks during OTA agent initialization.

Library Versions

Library Version Supported MTB version Remarks
ota-update v4.3.0 ModusToolbox 3.2 cysecuretools v5.1 or greater is required
ota-update v4.2.0 ModusToolbox 3.2 cysecuretools v5.1 or greater is required
ota-update v4.1.0 ModusToolbox 3.2 cysecuretools v5.1 or greater is required
ota-update v4.0.0 ModusToolbox 3.1 cysecuretools v5.0 or greater is required
ota-update v3.0.1 ModusToolbox 3.1 cysecuretools v4.2 or greater is required
ota-update v3.0.0 ModusToolbox 3.0 cysecuretools v4.2 or greater is required
ota-update v2.0.0 ModusToolbox 3.0 NOT backwards compatible with ModusToolbox 2.4
ota-update v1.0.0 ModusToolbox 2.4 Replaces anycloud-ota (all versions)
anycloud-ota NA Depricated

1. Enabling OTA in an Application

On a virgin device, main application(BOOT image) is programmed / flashed to the device first time. Subsequent versions of the application (so called updates) are downloaded using OTA.

On some devices such as PSoC™ 64 kits, there will be multiple images such as main application and the TFM images that are OTA updatable. This OTA solution allows using TAR format package for updating a single, or multiple images.

The ModusToolbox OTA code examples import the ota-update library automatically.

2. Push Model Updates

Bluetooth® updates use a "Push" model. On reset / boot, the device advertises that it can handle an update, and a Host (laptop, phone, etc.) is used to connect and "Push" the update to the device.

3. Pull Model Updates

WiFi and Ethernet based protocols(MQTT/HTTP) use a "Pull" model. There are two "Update Flows" that a user can designate. HTTP and MQTT transports can be used for this type of update.

4.1. Direct Flow
With "Direct" flow approach, device downloads a known file from the server/broker.

  1. HTTP: The device connects to the known HTTP Server and downloads the OTA update image using HTTP GET requests, asking for a range of data sequentially until all data is transferred.

  2. MQTT: The device connects to the known MQTT Broker topic and publishes a "Request Download" message with a "Unique Topic Name" to the Publisher. The Publisher python application then splits the OTA update image into chunks and publishes them on the unique topic.

4.2. Job Flow
With a "Job" flow approach, the device downloads a JSON formatted job document that provides information about where the update file is, its version, and other information concerning the update.

  1. The device connects to the server/broker to obtain the Job document.

    • HTTP: The device connects to the known HTTP server and uses an HTTP GET request to obtain the Job document.
    • MQTT: The device subscribes to the known MQTT Broker topic and publishes a request for the Job document.

  2. The device uses the Job document to determine if the OTA update image is an appropriate update.

  3. The device connects to the data server/broker and downloads the OTA image.

    • HTTP: The image is downloaded using HTTP GET requests, asking for a range of data sequentially until all data is transferred.
    • MQTT: The device sends a "Request Download" message with the "Unique Topic Name" on the known topic. The puthon Publisher application then splits the OTA image into chunks and publishes them on the unique topic.

4. Quick start

Once the application starts the OTA agent, the OTA agent will contact the MQTT Broker/HTTP server at the defined intervals to check whether an update is available. If available, the update will be downloaded. If the reset_after_complete flag was set in the agent parameters, the OTA Agent will automatically reset the device. On the next system reset, Bootloader will perform the update.

5. Bootloader Support

Starting from the 4.0 version of the ota-update library, the library is now fully separated from the MCUBootloader. This means that it can function independently and work with any bootloader, as long as the required OTA update handling storage APIs are implemented and registered with OTA agent by the user.

5.1 MCUBootloader Support

MCUBootloader is a secure bootloader for 32-bits 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.

To support MCUBootloader based OTA using ota-update library, User can implement his own storage operation callbacks to handle upgrade image or can make use of ota-bootloader-abstraction library.

ota-bootloader-abstraction library has below support.

Refer ota-bootloader-abstraction library Readme for enabling MCUBootloader support.

5.2 CYW955913EVK-01 in-built bootloader Support

An in-built bootloader is programmed in ROM section of CYW955913EVK-01.

To support OTA using ota-update library on CYW955913EVK-01 kit, user can implement his own storage operation callbacks to handle upgrade image or can make use of ota-bootloader-abstraction library.

ota-bootloader-abstraction library has below support for in-built bootloader based platforms like CYW955913EVK-01.

Refer ota-bootloader-abstraction library Readme for enabling in-built CYW955913EVK-01 bootloader support.

5.3 Other bootloader Support

6. Example Update Sequence Using BLE (PUSH Model)

7. Example Job Flow Update Sequence Using HTTP

  1. The device connects to the HTTP server and uses the HTTP GET request to obtain the Job document (for example: ota_update.json).

  2. The device determines whether the OTA update image version is newer than the currently executing application, and the board name is the same, etc.

    • If the OTA update image is accessible through an MQTT Broker, the device creates and subscribes to a unique topic name and sends a "Request Download" message with the "Unique Topic Name" to the Publisher on the known topic OTAUpdate/CY8CPROTO_062_4343W/notify_publisher. The Publisher then splits the OTA update image into chunks and publishes them on the unique topic.

    • If the OTA update image is accessible on an HTTP Server, the device connects to the HTTP Server and downloads the OTA update image using an HTTP GET request, asking for a range of data sequentially until all data is transferred.

For Job document information, please see Job Document section below.

8. Example Job Flow Update Sequence Using MQTT

  1. The Publisher Python script (ota-update/scripts/WiFi_Ethernet/publisher.py) subscribes to a known topic (for example: OTAUpdate/CY8CPROTO_062_4343W/publish_notify) on the specified MQTT Broker.

  2. The device publishes the message "Update Availability" to the known topic. The message includes information about the device (manufacturer, product, serial number, application version, etc.), and a "Unique Topic Name" for the Publisher to send messages to the device.

  3. The Publisher receives the "Update Availability" message and publishes the appropriate Job document on the "Unique Topic Name". The Publisher can make a decision if there is an appropriate update available for the device. The Publisher sends an "Update Available" (or "No Update Available") message, which repeats the device-specific information.

  4. The device receives the Job document and connects to the Broker/server given in the Job document to obtain the OTA update image.

    • If the OTA update image is located on an MQTT Broker, the device connects and sends a "Request Update" message to the Publisher, which includes the device information again. The Publisher then splits the OTA update image into 4-kB chunks, adds a header to each chunk, and sends it to the device on the "Unique Topic Name".

    • If the OTA update image is located on an HTTP server, the device will connect to the HTTP server and download the OTA update image using an HTTP GET request, for a range of data sequentially until all data is transferred.

For Job document information, please see Job Document section below.

9. The Pull Model Job Document

The Job document is a JSON-formatted file that contains fields used to communicate between the Publisher script and the OTA Agent running on the device.

Manufacturer:   Manufacturer Name.
ManufacturerId: Manufacturer Identifier
Product:        Product Name.
SerialNumber:   The Devices unique Serial Number
Version:        Application version Major.Minor.Build (ex: "12.15.0")
Board:          Name of board used for the product. (ex: "CY8CPROTO_062_4343W")
Connection:     The type of Connection to access the OTA Image. ("MQTT", "HTTP", "HTTPS")
Port:           Port number for accessing the OTA Image. (ex: `MQTT:1883`, HTTP:80`)

Additional fields for HTTP Transport Type:

Server:         Server URL (ex: "http://ota_images.my_server.com")
File:           Name of the OTA Image file (ex: "<product>_<board>_v5.6.0.bin")
Offset:         Offset in bytes for the start of data to transfer.
Size:           The size of the chunk of data to send, in bytes.

The following is an example Job document for an OTA update image that is available on an HTTP server:

{
  "Manufacturer":"Express Widgits Corporation",
  "ManufacturerId":"EWCO",
  "Product":"Easy Widgit",
  "SerialNumber":"ABC213450001",
  "Version":"1.76.0",
  "Board":"CY8CPROTO_062_4343W",
  "Connection":"HTTP",
  "Server":"<server_URL>",
  "Port":"80",
  "File":"/<OTA_image_file_name>"
}

Additional fields for MQTT Transport Type:

Broker:          MQTT Broker to access the OTA update image (for example: `mqtt.my_broker.com`)
UniqueTopicName: The "replace" value is just a placeholder. It is replaced with the Unique Topic Name for the OTA data transfer.

The following is an example Job document for an OTA update image that is available on an MQTT Broker:

{
  "Manufacturer":"Express Widgits Corporation",
  "ManufacturerId":"EWCO",
  "Product":"Easy Widgit",
  "SerialNumber":"ABC213450001",
  "Version":"1.2.28",
  "Board":"CY8CPROTO_062_4343W",
  "Connection":"MQTT",
  "Broker":"mqtt.widgitcorp.com",
  "Port":"1883",
  "UniqueTopicName":"replace"
}

10. Setting Up the Supplied Publisher Python Script for MQTT Updates

The ota-update/WiFi_Ethernet/scripts/publisher.py script contains several configurable values. Ensure that the parameters in the script match the application values. In addition, check the example application you are using for any special needs.

The Publisher and Subscriber scripts need the 'paho-mqtt' Python module, version 1.6.1.

pip install paho-mqtt==1.6.1

NOTE:The Publisher and Subscriber scripts are only compatible with paho-mqtt version 1.6.1.

Using the publisher script to test MQTT updates:

cd mtb_shared/ota-update/scripts/WiFi_Ethernet
python publisher.py [tls] [-l] [-f <filepath>] [-b <broker>] [-k <kit>] [-c <company_topic>]

Usage:

11. Using the Subscriber Python Script for testing MQTT Updates

The subscriber.py script is provided as a verification script that acts the same as a device. It can be used to verify that the Publisher is working as expected. Ensure that the BROKER_ADDRESS matches the Broker used in publisher.py.

Using the publisher script for verifying the Broker connection:

cd ota-update/scripts/WiFi_Ethernet
python subscriber.py [tls] [-l] [-b broker] [-k kit] [-f filepath] [-c <chunk_size>] [-e <company_topic>]

Usage:

12. Note on Using Windows 10

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-update-library\>scripts/requirements.txt

13. Supported Toolchains

For the toolchain version information, please refer to OTA Release.md.

14. Supported OS

15. Supported Kits

16. Hardware Setup

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".

17. Software Setup

  1. Install a terminal emulator if you don't have one. Instructions in this document use Tera Term.

  2. Python Interpreter. The supplied publisher.py script is tested with Python 3.8.1.

18. Enabling Debug Output

The 'ota-update' library disables all debug log messages by default. Do the following to enable log messages:

  1. Add the ENABLE_OTA_LOGS macro to the DEFINES in the code example's Makefile. The Makefile entry should look like as follows:

    DEFINES+=ENABLE_OTA_LOGS

  2. 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.

19. Prepare for Building Your OTA Application

Copy OTA's cy_ota_config.h to your application's top-level directory, and adjust for your application needs.

   cp \<ota-update-library\>/configs/cy_ota_config.h <application dir>

Also, a reminder to look at configuration files for other libraries.

20. Limitations

  1. If not using a Job document with MQTT, and the device is not subscribed to the topic on the MQTT Broker when the Publisher sends the update, it will miss the update.

    As the workaround, use a Job document, which has information about where the OTA update image is located.

  2. Ensure that you have a reliable network connection before starting an OTA update. If your network connection is poor, OTA update may fail due to lost packets or a lost connection.

  3. Ensure that you have a fully charged device before starting an OTA update. If your device's battery is low, OTA may fail.

  4. When using the ARM compiler with the CYW20829 or BLE platforms, ensure that MBEDTLS_ENTROPY_HARDWARE_ALT is not defined in mbedtls_user_config.h. When MBEDTLS_ENTROPY_HARDWARE_ALT is defined it is possible to encounter an unresolved symbol error during the link phase when using the ARM compiler.

21. Additional Information

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.