IC: RTL8721Dx RTL8720E RTL8726E RTL8730E

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 firmware 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

Two image slots (OTA1 and OTA2) are configured in Flash layout for redundant storage and version control, as shown in the figure below. The boot system selects between these slots based on validation criteria.

Image Pattern and Version Number

Boot selection between OTA1/OTA2 primarily depends on the image pattern and version number in Certificate and Manifest. As shown below, both the Certificate and Manifest contain an 8-byte image pattern, a 2-byte major version number, and a 2-byte minor version number..

The image pattern is data with a fixed length of 8 bytes. The OTA selection process checks the validity of the image pattern. The bootloader and application have different image pattern, with the bootloader checking the image pattern in the Manifest, and the application checking the image pattern in the Certificate.

The version number is a 4-byte combination of the major version and the minor version. The version number is calculated as follows:

\[\text{Version number} = (\text{Major version} \ll 16) \, | \, \text{Minor version}\]

The OTA selection process compares the size of the version numbers. The bootloader and application can have different version numbers, with the bootloader checking the version number in the Manifest, and the application checking the version number in the Certificate.

On the next boot after an OTA upgrade, the bootloader checks the validity of the image pattern and compares the version numbers to decide whether to boot from OTA1 or OTA2. Consistency between image pattern and versions ensures reliable boot. Each firmware must check the following items:

1. Check the validity of the image pattern for both OTA1 and OTA2.

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

   • If both image patterns are invalid, boot fail.

2. Compare the version number of OTA1 and OTA2.

   • If both OTA1 and OTA2 are valid and with different version numbers, the device will boot from the firmware with a bigger version.

   • If both OTA1 and OTA2 are valid but with the same version number, the device will boot from OTA1.

   

   OTA selection diagram

To switch to the new firmware on the next boot after an upgrade, OTA supports the following two methods:

Depends on Version NumberDepends on Image Pattern

Set a higher version number in the new firmware’s Manifest: The next boot will use the new firmware. This requires modifying the new firmware’s version number during each upgrade.

Modify the version number in the project’s manifest.json file:

1. Configure the version number for the bootloader. The version number range is from 0 to 32767:

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

2. Configure the version number for the application. The version number range is from 0 to 65535:

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

Users can choose either Depends on Version Number or Depends on Version Number depending on their needs.

Anti-rollback

Anti-rollback is the function to prevent version rollback attack. When the anti-rollback is enabled, the version number in certificate or manifest must not be smaller than the anti-rollback version in OTP. Otherwise, this image will be regarded as invalid and the chip will not boot from invalid image. Normally, if OTA update is security-related, user can program a bigger anti-rollback version number in OTP and update image with a bigger major version at the same time to prevent rollback attack.

The anti-rollback flow is shown below. Once the anti-rollback is enabled, the device will compare the major version numbers abtained from OTA1 and OTA2 images respectively with the anti-rollback version number in OTP. If the major version number of the image is smaller than the anti-rollback version number, this image will be regarded as invalid.

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

1. Change the anti-rollback version number for the bootloader. By default, all firmwares use the same anti-rollback version in the OTP as a threshold to prevent rollback attacks.

   Name	OTP Address	Length	Description
   Bootloader Version	Physical Address 0x36E~0x36F	16 bits	Anti-rollback version for the bootloader

   The default value for the bootloader’s anti-rollback version is 0. Users can alter the number of 0 bits to increase the bootloader version.

   For example, to set the bootloader anti-rollback version to 1, use the following command:

   EFUSE wraw 36E 2 FFFE
   

2. Write into the OTP to enable anti-rollback with the following command:

   EFUSE wraw 368 1 BF
   

Note

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

• If the bootloader and application do not use the same anti-rollback version, modify BOOT_OTA_GetCertRollbackVer() in bootloaderboot_ota_km4.c or bootloaderboot_ota_hp.c and define another anti-rollback version for the application in the OTP.

Bootloader

OTA Image

The KM4 bootloader image (km4_boot_all.bin) can be updated via OTA and is capable of booting from either OTA1 or OTA2. The layout of KM4 bootloader image is illustrated below.

To enable bootloader upgrade via OTA, follow these steps:

1. Enter CONFIG OTA OPTION via Configuring SDK (menuconfig), and select Enable Bootloader OTA, integrating the bootloader firmware into ota_all.bin.

2. Write the bootloader’s OTA2 address into the OTP. Use the IMG_BOOT_OTA2 setting in Flash_Layout as a reference, as explained in User Configuration.

   EFUSE wraw 36C 2 IMG_BOOT_OTA2
   

   For example, if IMG_BOOT_OTA2 is 0x08200000, the command to write into the OTP would be:

   EFUSE wraw 36C 2 0082
   

   Note

   • The bootloader OTA2 address is the value in OTP address 0x36C shifted left by 12 bits, or the value at OTP address 0x36C multiplied by 4K.

   • If the default address for bootloader OTA2 is 0xFFFFFFFF, the bootloader will not be upgraded during OTA, and the device will always boot from bootloader OTA1.

OTA Selection Flow

The ROM bootloader selects OTA image based on the image version number in the KM4 bootloader’s Manifest.

Application

OTA Image

RTL8721DxRTL8726ERTL8720ERTL8730E

The application image (km0_km4_app.bin) comprises KM0, KM4 non-secure and KM4 secure application images. This image can be updated via OTA and is capable of booting from either OTA1 or OTA2. The layout of the application image is illustrated below.

OTA Selection Flow

The KM4 bootloader selects application image based on the version number in the application’s Certificate, as depicted below.

OTA Compressed Image

When OTA Image Compression is enabled, the OTA image will be compressed and image size will be reduced, which can save the flash space effectively.

The OTA Image Compression only compresses the APP image which named with suffix of app.bin. After compression finishes, the compressed APP image will be generated in directory image, which named with suffix of app_compress.bin. And at the same time, the compressed APP image will be integrated into ota_all.bin.

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 computed as follows:

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

The compression rate depends on the image content. Usually, the compression rate is in the range of 60 to 70 percent. The more complex of the original image content, the higher compression rate will be.

Once the compressed APP image is download into one OTA slot, the system will always select the compressed image first. The compressed image will be decompressed into another OTA slot, and then the system will boot from this slot. This means there is always only one valid APP image between the two slots. For example, if the board is currently booting from OTA1 and running the OTA application, the compressed image will be downloaded into OTA2. On the next boot, the system will select the compressed image, decompress it into OTA1, and then continue to boot from OTA1.

Users can generate OTA compressed image by the following steps:

1. Enter CONFIG OTA OPTION via Configuring SDK (menuconfig), and check Enable Compress APP Image to enable firmware compression.

2. Compile the project; the ota_all.bin containing the compressed application firmware will be generated in {SDK}amebadxxx_gcc_project.

Building OTA Image

Modifying Configurations

1. Select the method for booting new firmware as discussed in Image Pattern and Version Number.

2. Adjust the bootloader’s anti-rollback version number and enable anti-rollback if necessary, as outlined in Anti-Rollback.

3. If upgrading the bootloader is needed, follow the steps outlined in Bootloader.

4. If OTA compression is needed, follow the steps outlined in OTA Compressed Image.

Generating OTA Image Automatically

RTL8721DxRTL8726ERTL8720ERTL8730E

The OTA image will be generated automatically when building the project.

1. The km0_km4_app.bin is comprised in ota_all.bin by default.

2. Rebuild the project. The OTA image file (ota_all.bin) will be generated under {SDK}\amebadplus_gcc_project.

OTA Firmware Format

The ota_all.bin format is illustrated below.

Firmware format

OTA header

Items	Address offset	Size	Description
Version	0x00	4 bytes	Version of OTA Header, default is 0xFFFFFFFF.
Header Number	0x04	4 bytes	Number of OTA Header. Value can be 1, 2.
Signature	0x08	4 bytes	OTA signature is string. Value is OTA.
Header Length	0x0C	4 bytes	Length of OTA header. Value is 0x18 * Header Number.
Checksum	0x10	4 bytes	Checksum of upgrade image.
Image Length	0x14	4 bytes	Size of upgrade image.
Offset	0x18	4 bytes	Start position of upgrade image in current image.
Image ID	0x1C	4 bytes	Image ID of upgrade image: OTA_IMGID_BOOT: 0x0 OTA_IMGID_APP: 0x1

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:

1. If Depends on Image Pattern was chosen in Modifying Configurations, make the modifications described Depends on Image Pattern, otherwise skip this step.

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. If Depends on Version Number was chosen in Modifying Configurations, make the modifications described in Depends on Version Number, otherwise skip this step.

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

6. Edit http_server.py.

   server_ip = '192.168.31.193'
   server_port = 8082
   

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

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

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

User Configuration

Refer to the section Flash Layout for Flash layout. Modify the Flash layout if necessary, users should plan the Flash layout in advance and allocate sufficient space.