OTA Guide

Introduction

OTA (Over-the-Air) upgrade mechanism allows devices to receive new image via Wi-Fi, SPI, UART, or file systems while the current image is running, save it to the corresponding image partition in Flash, and run the new image after reboot. This is used for scenarios such as bug fixes, new feature releases, and performance optimizations.

Before using OTA, please refer to the Flash Layout section for more details on Flash partitioning.

Image Slot

In the Flash Layout , both bootloader and application image have two slots (OTA1 and OTA2) for redundant storage and version control.

Users should configure the size of these slots based on the actual image size and reasonable reserved space.

Note

The bootloader OTA is disabled by default. To enable it, please refer to BOOT OTA.

Image Pattern and Version Number

The boot selection between OTA1/OTA2 primarily relies on the image header’s image pattern and version number. As shown in the figure below, the image header contains an 8-byte image pattern, a 2-byte major version number, and a 2-byte minor version number.

../_images/major_and_minor_version.svg

The detailed descriptions of the image pattern and version number are as follows:

Item

Description

OTA Selection Flow

Image Pattern

  • Fixed 8-byte data

  • BOOT and APP image each have their own image pattern

Check image pattern validity

Version Number

  • Composed of major and minor version numbers, calculated as:

    Version = Major Version << 16 | Minor Version

  • BOOT and APP image each have their own version number

Compare version numbers

On each system boot, the Bootloader checks the image pattern validity and compares version numbers to determine whether to boot from OTA1 or OTA2. The consistency check of image tags and version numbers ensures the reliability of the boot process, as detailed below:

  1. Check the image pattern validity of OTA1 and OTA2 partitions:

    • If only one image pattern is valid, boot from that valid image;

    • If both image tags are invalid, the boot fails.

  2. Compare the version numbers of OTA1 and OTA2 partitions:

    • If both image version numbers are valid and different, boot from the image with the higher version number;

    • If both image version numbers are valid and identical, default to booting from OTA1.

../_images/ota_select_diagram.svg

Image Switch Strategy

Based on the above boot process in Image Pattern and Version Number, OTA supports the following two image switching strategies for switching to a new image on the next boot:

Note

For switching strategy configuration, refer to Configuration (menuconfig) and navigate to CONFIG OTA OPTION > OTA Image Switch Strategy to select the strategy.

Version Number Based (Default):

Set a higher version number in the new image. After OTA upgrade completion, the device will automatically boot from the new image on the next boot. This strategy is suitable for scenarios requiring version control.

Configuration Steps:

  1. Select the switching strategy in menuconfig:

       CONFIG OTA OPTION  --->
          [*] OTA Image Switch Strategy
             Select Strategy (Version Number Based)  --->
                   (X) Version Number Based
                   ( ) Valid Header Based
    
  2. Modify the new image version number in the configuration file manifest.json5 of your target IC:

    RTL8721Dx:

    github source code

    1. BOOT image version configuration (valid range: 0 ~ 32767)

      "image1":
      {
         "img_id": 0,
         "img_ver_major": 1,
         "img_ver_minor": 1,
         ...
      },
      
    2. APP image version configuration (valid range: 0 ~ 65535)

      "image2":
      {
         "img_id": 1,
         "img_ver_major": 1,
         "img_ver_minor": 1,
         ...
      },
      

Tip

Increment the version number during each OTA upgrade to ensure the new image version is higher than the currently running image.

Comparison of Two Switching Strategies

Feature

Version Number Based

Valid Header Based

Version Number Requirement

Requires incrementing version number

No version number modification needed

Configuration Complexity

Medium (requires version maintenance)

Simple (no additional configuration needed)

Old Image Status

Preserved intact

Pattern corrupted

BOOT OTA Support

All ICs supported

Partially supported (see the note below for unsupported ICs)

APP OTA Support

All ICs supported

All ICs supported

BOOT OTA does not support Valid Header Based switching on the following ICs:

RTL8720E:

Not supported.

Anti-rollback

The anti-rollback feature prevents the device from rolling back to an image whose major version number is lower than the anti-rollback version number in OTP. When the feature is enabled, the major version number in the image header cannot be less than the anti-rollback version number set in OTP; otherwise, the image is considered invalid.

Typically, if an OTA upgrade fixes a security issue in an earlier version, you can set the anti-rollback version number to the major version number of the upgraded image after the upgrade completes, to prevent the device from rolling back to the vulnerable earlier version.

The anti-rollback process is as follows:

  1. Read the major version numbers from the image headers of OTA1 and OTA2, and compare each with the anti-rollback version number in OTP.

  2. If an image’s major version number is less than the anti-rollback version number, the image is invalid.

../_images/anti_rollback_flow.svg
RTL8721Dx:

OTP Configuration:

The anti-rollback version number is stored in the OTP (One-Time Programmable) area of the chip:

  • The physical address range for OTP is 0x36E ~ 0x36F.

  • The number of 0 bits in the OTP value is the anti-rollback version number. The default OTP value is all F, which corresponds to an anti-rollback version number of 0.

  • OTP bits can only be written from 1 to 0, and this address range has 16 bits in total, so at most 16 anti-rollback version numbers are supported (version number range: 1 ~ 16).

Enabling Anti-Rollback:

Enabling the anti-rollback feature requires the following 2 steps:

  1. Set the anti-rollback version number in OTP:

    Read the current anti-rollback version number with the following command:

    AT+OTP=RRAW,36E,2
    

    Write the anti-rollback version number with the following command:

    AT+OTP=WRAW,36E,2,<Value_OTP>
    

    Where <Value_OTP> is the OTP value corresponding to the target version number. Calculation examples:

    • Example 1: Writing either FFFC or FFCF

      • Both values have 2 bits that are 0

      • The anti-rollback major version number in OTP is 2

      • Images with a version number less than (2 << 16) are prohibited from booting

    • Example 2: Writing either FFF0 or 0FFF

      • Both values have 4 bits that are 0

      • The anti-rollback major version number in OTP is 4

      • Images with a version number less than (4 << 16) are prohibited from booting

  2. Enable the anti-rollback feature:

    Read the current value with the following command:

    AT+OTP=RRAW,368,1
    

    Set bit 6 of the value read to 0 and write it back. For example, if the value read is FF, write BF:

    AT+OTP=WRAW,368,1,BF
    

By default, the BOOT image and the APP image share the same anti-rollback version number, which is read from OTP.

To use different anti-rollback version numbers for the BOOT image and the APP image, modify the function BOOT_OTA_GetCertRollbackVer() in bootloader\boot_ota_km4.c or bootloader\boot_ota_hp.c to customize how the anti-rollback version number is obtained for the APP image.

Important

  • OTP is one-time programmable memory: once a bit is written from 1 to 0, it cannot be restored.

  • Once the anti-rollback feature is enabled, it cannot be disabled. Operate with caution.

  • After enabling the anti-rollback feature, the anti-rollback version number must be modified for the feature to take effect.

  • It is recommended to enable anti-rollback without setting a version number at the mass production stage, and write the version number only after the OTA upgrade completes.

  • To modify the anti-rollback version number in the application, refer to the interfaces in OTP API Reference and implement it in code.

BOOT OTA

BOOT OTA Enablement Steps

The BOOT OTA feature is disabled by default. To enable it, complete the following 3 steps in order. Steps 1 and 2 involve the Flash layout and the device OTP configuration, while step 3 only affects the build output and does not require any code changes:

  1. Confirm the BOOT OTA2 partition (modify only if needed):

    The SDK already provides a default BOOT OTA2 partition in Flash Layout . If the default partition meets your needs, use it as is; otherwise, modify the partition range and ensure 4K address alignment.

  2. Write the start address of the BOOT OTA2 partition confirmed in step 1 to OTP :

    RTL8721Dx:
    AT+OTP=WRAW,36C,2,<Value_OTP>
    

    Value_OTP is calculated from the BOOT OTA2 start address using the following formula:

    Value_OTP = (IMG_BOOT_OTA2 >> 12 & 0xFF) << 8 | (IMG_BOOT_OTA2 >> 20 & 0xFF)
    

    For example, when IMG_BOOT_OTA2 is 0x08234000, Value_OTP is 3482, and the corresponding command is:

    AT+OTP=WRAW,36C,2,3482
    
  3. Enable the BOOT OTA packaging option:

    Refer to Configuration (menuconfig) , navigate to CONFIG OTA OPTION, and enable Enable Bootloader OTA. This option only integrates the BOOT Image into ota_all.bin at build time for OTA upgrades and does not change the code.

       CONFIG OTA OPTION  --->
          [*] Enable Bootloader OTA
    

Important

  • OTP writes are irreversible: once written, the BOOT OTA2 address takes effect permanently and cannot be modified, so verify the address before writing.

  • If the BOOT OTA2 address in OTP is 0xFFFF (unconfigured), then:

    • OTA upgrade will skip BOOT Image updates;

    • The device will always boot from BOOT OTA1.

  • It is strongly recommended to complete the OTP configuration of the BOOT OTA2 address and enable the BOOT OTA packaging option before mass production.

BOOT OTA Selection Flow

The bootloader in the chip’s ROM selects which partition to boot from based on the image pattern and version number in the BOOT image header, as shown in the flowchart below.

../_images/km4_bootloader_ota_select_flow.svg

APP OTA

APP OTA Enablement Steps

The application image supports OTA upgrades and can boot from either the OTA1 or OTA2 partition. APP OTA is enabled by default and requires no additional configuration.

RTL8726E:

This chip has a DSP, and the DSP image must be merged into the application image so that it can be upgraded together with the application image through OTA. For how to package and boot it, refer to DSP Build .

APP OTA Selection Flow

At startup, the BOOT image selects whether to boot the application image from OTA1 or OTA2 based on the image pattern and version number of each application image. For the meaning of the pattern and version number, refer to Image Pattern and Version Number. The selection flow is shown in the flowchart below.

../_images/application_image_ota_select_flow.svg

OTA Compression Scheme

When OTA image compression is enabled, the APP OTA1 partition remains unchanged, while the image in the APP OTA2 partition is stored in compressed form, reducing image size and saving Flash storage space.

The compression algorithm is LZMA (Lempel-Ziv-Markov chain algorithm). It is a lossless data compression algorithm with a high compression ratio and relatively low decompression memory requirements, and is widely used in the .7z file format and 7-Zip software.

Compression effectiveness is measured by the compression ratio, which is calculated as follows:

Compression Ratio(%) = Compressed Image Size / Original Image Size × 100

The compression ratio is affected by image content: the more complex the original image content, the higher the compression ratio (that is, the weaker the compression effect), typically 50% ~ 70%.

With OTA compression enabled, the boot process has the following characteristics:

  1. Image pattern and version number validation follow the same procedure as the standard flow.

  2. Only the APP image supports compression.

  3. The compressed image is always downloaded to the OTA2 region during OTA.

  4. If the system needs to boot from the compressed image in OTA2, BOOT first decompresses the image and overwrites the OTA1 region, then boots from OTA1.

  5. Power-loss protection is supported both during the OTA download and during decompression at boot.

  6. The compressed image is decompressed only once, at the first boot after download completion; subsequent boots do not require decompression.

The boot selection flow is shown in the figure below:

../_images/compress_image_ota_select_flow.svg

The following example illustrates how compressed OTA works:

  1. The device boots from OTA1 and runs the OTA application.

  2. Compressed image is downloaded to OTA2.

  3. On the next boot, the system selects the compressed image, decompresses it to OTA1, and then boots from OTA1.

The diagram is as follows:

../_images/compress_ota_select_diagram.svg

Enabling OTA compression requires the following 2 steps:

  1. Enable the OTA compression option:

    Refer to Configuration (menuconfig) , navigate to CONFIG OTA OPTION, and enable Enable Compress APP image.

       CONFIG OTA OPTION  --->
          [*] Enable Compress APP image
    
  2. Build to generate the compressed image:

    During compilation, the APP image is compressed and the following files are generated:

    • Compressed image: {SDK}\build_<soc>\build\project_xx\image\xxx_app_compress.bin

    • ota_all.bin containing the compressed image, used for OTA.

After enabling, you can verify the decompression process by programming the compressed image:

  1. Program the following files to the corresponding regions:

    • {SDK}\build_<soc>\boot.bin: program to the BOOT OTA1 region.

    • {SDK}\build_<soc>\build\project_xx\image\xxx_app_compress.bin: program to the APP OTA2 region.

  2. Reset the device. The system selects the compressed image in OTA2, decompresses it to OTA1, and boots from OTA1, which verifies the decompression process of the compressed image.

Important

  • Decompression is performed by the BOOT image, so the BOOT image must be updated and re-programmed when OTA compression is enabled for the first time.

  • It is recommended to enable OTA compression before mass production.

RTL8735C:
  • The BOOT image is {SDK}\build_RTL8735C\amebapro3_boot.bin, and the compressed image is {SDK}\build_RTL8735C\build\project_np\image\amebapro3_app_compress.bin.

  • The compressed content includes the AP FIP image that is appended to the application image.

  • The BOOT image decompresses only when booting from NOR Flash.

OTA Image

OTA Image Format

The ota_all.bin format is illustrated below. The OTA image header is divided into a main header and multiple sub-headers. The main header includes the version number and the number of sub-headers. Each sub-header contains specific information about an individual upgrade image. When an additional upgrade image is included, a corresponding sub-header is appended.

../_images/firmware_format.svg
OTA Image Header

Items

Address offset

Size

Description

Version

0x00

4 bytes

Version of OTA Image Header, default is 0xFFFFFFFF.

Header Number

0x04

4 bytes

Number of OTA image sub-headers, value is 1 or 2.

Signature

0x08

4 bytes

Signature of OTA image sub-header, value is OTA.

Header Length

0x0C

4 bytes

Length of OTA image sub-header, value is 0x18.

Checksum

0x10

4 bytes

Checksum of the corresponding upgrade image.

Image Length

0x14

4 bytes

Size of the corresponding upgrade image.

Offset

0x18

4 bytes

Offset of the corresponding upgrade image in current OTA image.

Image ID

0x1C

4 bytes

Image ID of the corresponding upgrade image:

  • OTA_IMGID_BOOT: 0x0

  • OTA_IMGID_APP: 0x1

Modifying Configurations

  1. Refer to Image Pattern and Version Number to adjust the version number or switch the scheme.

  2. Adjust the anti-rollback version number and enable anti-rollback if necessary. please refer to the enabling steps in Anti-Rollback.

  3. If upgrading the bootloader is needed, please refer to the enabling steps in BOOT OTA.

  4. If OTA compression is needed, please refer to the enabling steps in OTA Compression Scheme.

Generating OTA Image Automatically

During project compilation, the OTA image will be generated automatically.

  1. The OTA image will include the following contents:

  2. Build the project. The OTA image ( ota_all.bin ) will be generated in the {SDK}\build_<soc> directory.

OTA Example

This section provides various image OTA upgrade examples covering different transport protocols and data sources:

Example

Description

ota_http

HTTP Upgrade: Download and upgrade image from a remote server via HTTP protocol.

ota_https

HTTPS Secure Upgrade: Securely download and upgrade image via HTTPS protocol with SSL/TLS encryption support.

ota_user

User-Defined Upgrade: Support custom data sources such as SPI, UART, etc..

ota_vfs

Virtual File System Upgrade: Read and upgrade image from virtual file systems (SD card, Flash, etc.).