IC: RTL8721Dx RTL8720E RTL8726E RTL8713E RTL8730E RTL8721F

Introduction

The OTA (Over-The-Air) update mechanism allows devices to self-update based on received data through WiFi, SPI, UART, or file systems while image is running normally, enabling timely upgrades to device functionality and performance.

Before using OTA, please refer to the Flash Layout section for details about Flash layout.

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 depends on the image patterns and version numbers in the image header. As shown below, the image header includes an 8-byte image pattern, a 2-byte major version number, and a 2-byte minor version number.

Detailed descriptions of the image image pattern and version numbers are as follows:

Item	Description	OTA Selection Process
Image Pattern	A fixed 8-byte length data BOOT image and APP image each have their own image patterns	Check the validity of the image pattern
Version Number	Combination of major and minor version numbers, calculated as follows: \[\text{Version Number} = (\text{Major Version Number} \ll 16) \, | \, \text{Minor Version Number}\] BOOT image and APP image each have their own version numbers	Compare version numbers

At each boot, the bootloader will check the validity of the image patterns and compare the version numbers to decide whether to boot from OTA1 or OTA2. The consistency of image image patterns and versions ensures a reliable boot process, and each image must verify the following items:

1. Check the validity of the image patterns for OTA1 and OTA2.

   • If only one image pattern is valid, boot from the valid image.

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

2. Compare the version numbers of OTA1 and OTA2.

   • If both OTA1 and OTA2 version numbers are valid and different, the device will boot from the image with the higher version number.

   • If both version numbers are valid and the same, the device will boot from OTA1.

Based on the above booting process, OTA supports the following two methods to switch to new image on the next boot:

Update Version Number (Default)Corrupt Image Pattern

Set a higher version number in the new image, and after OTA completion, the next boot will start from the new image. This method requires modifying and increasing the version number of the new image in each upgrade.

Modify the version number of the new image in the configuration file manifest.json in the project folder {SDK}/amebaxxx_gcc_project.

1. Configure the version number for the BOOT image, with a range from 0 to 32767.

   "boot":
   {
      "IMG_ID": "0",
      "IMG_VER_MAJOR": 1,
      "IMG_VER_MINOR": 1,
      ...
   },
   

2. Configure the version number for the APP image, with a range from 0 to 65535.

   "app":
   {
      "IMG_ID": "1",
      "IMG_VER_MAJOR": 1,
      "IMG_VER_MINOR": 1,
      ...
   },
   

Anti-rollback

The anti-rollback feature is used to prevent rollback to image versions where the major version number is lower than the version number set in OTP. When the anti-rollback 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 will be deemed invalid.

Typically, if the current OTA update addresses security issues of the previous version, the user can set the anti-rollback version number to the version number of this update after completion to prevent rollback to image versions lower than this version.

The anti-rollback process is as follows:

1. Compare the major version numbers obtained from the image headers of OTA1 and OTA2 respectively with the anti-rollback version number in OTP.

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

Users can enable the anti-rollback feature with the following steps:

1. Change the anti-rollback version number in OTP.

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

   • The number of bits 0 in the value in OTP represents the anti-rollback version number. The default value of OTP is FFFF, which indicates the default anti-rollback version number is 0.

   • Since the physical address of OTP can only be written from 1 to 0, the address range supports up to 16 anti-rollback version numbers.

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

   EFUSE rraw 36E 2
   

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

   EFUSE wraw 36E 2 xxxx
   

   Where xxxx is the version number to be set. For example:

   • Example 1: Writing FFFC or FFCF, both have 2 bits set to 0, so the version number in OTP is 2. This means image with major version numbers less than 2 are prohibited from booting.

   • Example 2: Writing FFF0 or 0FFF, both have 4 bits set to 0, so the version number in OTP is 4. This means image with major version numbers less than 4 are prohibited from booting.

2. Enable the anti-rollback feature.

   Read the current value with the following command:

   EFUSE rraw 368 1
   

   Set bit 6 to 0 in the read value before writing back. For instance, if the value read is FF, then write:

   EFUSE wraw 368 1 BF
   

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

If BOOT image and APP image need to use different anti-rollback version numbers, modify the function BOOT_OTA_GetCertRollbackVer() in bootloader\boot_ota_km4.c or bootloader\boot_ota_hp.c to customize a different methodology for obtaining the anti-rollback version number for APP image.

Note

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

• If the anti-rollback feature is needed, it is recommended to enable anti-rollback without setting the version number at the mp stage. Selectively write the anti-rollback version number after OTA.

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

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

BOOT OTA

By default, BOOT OTA is not enabled. Users can enable BOOT OTA through the following steps:

1. Refer to Configuring SDK (menuconfig) and enter the CONFIG OTA OPTION configuration. Check Enable Bootloader OTA, which integrates the bootloader image into ota_all.bin during the compilation process.

2. Plan and modify the slot range for BOOT OTA2 in the Flash Layout, ensuring 4K alignment.

3. Write the start address of the BOOT OTA2 slot to OTP.

   EFUSE wraw 36C 2 IMG_BOOT_OTA2
   

   The formula for calculating the value to write into OTP based on the BOOT OTA2 address is:

   \[\text{Value to write into OTP} = ((\text{IMG_BOOT_OTA2} \gg 12) \& 0xFF) \ll 8 | ((\text{IMG_BOOT_OTA2} \gg 20) \& 0xFF)\]

   For example, if IMG_BOOT_OTA2 is 0x08234000, the command to write to OTP is:

   EFUSE wraw 36C 2 3482
   

   Caution

   • The OTP area cannot be rewritten. Please ensure it is written during the development phase or in batch production in advance.

   • If the BOOT OTA2 address in OTP is 0xFFFF, the BOOT firmware will not be upgraded during OTA. The device will always boot from BOOT OTA1.

BOOT OTA Selection Flow

The bootloader in the chip ROM selects which slot to boot from based on the image patterns and version numbers in the bootloader image header, as illustrated in the following flowchart.

APP OTA

Application image supports OTA updates and can boot from either OTA1 or OTA2. APP OTA is enabled by default.

Note

For RTL8726E and RTL8713E, it is also necessary to load the DSP image. For more details about the DSP image, please refer to DSP Image.

APP OTA Selection Flow

The bootloader selects application image based on the image patterns and version numbers of application images, as illustrated in the following flowchart.

OTA Compression Scheme

When the OTA Image Compression feature is enabled, the APP OTA1 slot remains unchanged, while the image in the APP OTA2 slot is compressed, reducing its size and effectively saving Flash space.

The compression algorithm uses LZMA. LZMA stands for Lempel-Ziv-Markov chain Algorithm. It is a lossless data compression algorithm developed by Igor Pavlov, known for its high compression ratio and relatively low decompression memory requirements. The LZMA algorithm is commonly used in 7z format compressed files and is widely applied in 7-Zip software.

Here, we use compression rate to represent compression efficiency. The compression rate is calculated as follows:

\[\text{compression rate (%)} = \left( \frac{\text{compressed image size}}{\text{original image size}} \right) \times 100\]

The compression rate is affected by the content of the image: The more complex the content of the original image, the higher compression rate will be (typically 50% ~ 70%).

The boot process after enabling the OTA compression feature has the following characteristics:

1. The judgment of version numbers and image patterns is consistent with the normal process.

2. Only APP image supports the compression scheme.

3. The compressed image will always be downloaded to the OTA2 slot during the OTA.

4. If a decision is made to boot from the compressed image in OTA2, the BOOT process will decompress it and overwrite the OTA1 slot.

5. Supports power-down protection during both the OTA process and the boot decompression process.

6. The compressed image only needs to be decompressed during the first boot after the download is complete; it will not be decompressed in subsequent boots.

An example is provided as shown in the following figure:

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

2. The compressed image is downloaded into OTA2.

3. On the next boot, the system will select the compressed image, decompress it to OTA1, and then continue booting from OTA1.

Users can enable the OTA compression scheme with the following steps:

1. Refer to Configuring SDK (menuconfig) and enter the CONFIG OTA OPTION configuration. Check Enable Compress APP Image to enable the OTA compression feature.

2. When compiling the project, the APP image is compressed, and a compressed image {SDK}amebaxxx_gcc_projectproject_xxasdkimagexxx_app_compress.bin is generated, along with a compressed ota_all.bin` for OTA use by the user.

3. Flash bootloader image {SDK}\amebaxxx_gcc_project\xxx_bool_all.bin to the BOOT OTA1, and the compressed firmware {SDK}amebaxxx_gcc_projectproject_xxasdkimagexxx_app_compress.bin to the APP OTA2. Verify the decompression process of the compressed image.

Note

• When enabling the OTA compression scheme for the first time, it is necessary to update the BOOT. You need to reflash the BOOT image.

• If the OTA compression scheme is enabled, the size of the APP OTA2 area will be set smaller and will no longer be suitable for storing uncompressed application firmware. Therefore, we recommend using Advanced Usage during mass production.

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.

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 firmware will be generated automatically.

1. The OTA image will include the following contents:

   • OTA image header

   • BOOT image (refer to BOOT OTA)

   • APP image or compressed APP image

   • VFS2 image (refer to VFS within APP Firmware)

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

Updating via Wireless Network

This section introduces the design principles and usage of OTA via wireless network server. It has well-transportability to porting to users’ OTA applications which is upgraded from users’ server.

The OTA from network server shows how the device upgrades the image from a network download server. The network download server sends the image to the device based on the network socket, as the following figure illustrates.

Note

Make sure both the device and the PC are connecting to the same local network.

OTA Example

Follow these steps to run the OTA example to upgrade from HTTP server.

Upgrade Method of Corrupt Image PatternUpgrade Method of Update Version Number

1. Modify as described in Corrupt Image Pattern.

2. Edit example_ota.c.

   1. Edit the host according to the server IP address.

      #define PORT   8082
      static const char *host = "192.168.31.193";   //"m-apps.oss-cn-shenzhen.aliyuncs.com"
      static const char *resource = "ota_all.bin"; //"051103061600.bin"
      

   2. Edit the OTA type to OTA_HTTP.

      ret = ota_update_init(ctx, (char *)host, PORT, (char *)resource, OTA_HTTP);
      

3. Rebuild the project with the command ./build.py -a ota and download the images to the device.

4. Rebuild the project with the command ./build.py and copy ota_all.bin into DownloadServer(HTTP).

5. Edit http_server.py.

   server_ip = '192.168.31.193'
   server_port = 8082
   

6. Execute the script by command python http_server.py to start the download server program.

7. Reset the device and connect to the HTTP server.

8. After image download is complete, the device will reset automatically and boot from the new image.