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.
The detailed descriptions of the image pattern and version number are as follows:
Item |
Description |
OTA Selection Flow |
|---|---|---|
Image Pattern |
|
Check image pattern validity |
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:
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.
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.
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 to select the strategy.
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:
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
Modify the new image version number in the configuration file
manifest.json5of your target IC:RTL8721Dx:github source code
RTL8720E:github source code
RTL8710E:github source code
RTL8726E:github source code
RTL8713E:github source code
RTL8730E:github source code
RTL8721F:github source code
RTL8720F:github source code
RTL8735C:github source code
BOOT image version configuration (valid range: 0 ~ 32767)
"image1": { "img_id": 0, "img_ver_major": 1, "img_ver_minor": 1, ... },
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.
This strategy does not require modifying the new image’s version number. Instead, after OTA upgrade completion, the old image’s pattern is corrupted to invalidate it, forcing the Bootloader to use the newly upgraded image. This strategy actively invalidates the old image and is suitable for long-term testing or scenarios without version control requirements.
Configuration Steps:
Select the switching strategy in menuconfig:
CONFIG OTA OPTION --->
[*] OTA Image Switch Strategy
Select Strategy (Version Number Based) --->
( ) Version Number Based
(X) Valid Header Based
Warning
This strategy corrupts the old image’s header information, rendering it unbootable. If the new image has issues, image re-flashing is required.
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:
Not supported.
Not supported.
Not supported.
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:
Read the major version numbers from the image headers of OTA1 and OTA2, and compare each with the anti-rollback version number in OTP.
If an image’s major version number is less than the anti-rollback version number, the image is invalid.
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
0bits 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:
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
FFFCorFFCFBoth 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
FFF0or0FFFBoth 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
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
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
0bits 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:
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
FFFCorFFCFBoth 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
FFF0or0FFFBoth 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
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
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
0bits 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:
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
FFFCorFFCFBoth 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
FFF0or0FFFBoth 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
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
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
0bits 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:
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
FFFCorFFCFBoth 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
FFF0or0FFFBoth 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
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
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
0bits 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:
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
FFFCorFFCFBoth 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
FFF0or0FFFBoth 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
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
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
0bits 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:
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
FFFCorFFCFBoth 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
FFF0or0FFFBoth 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
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
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 0x378 ~ 0x37F.
The number of
0bits 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 64 bits in total, so at most 64 anti-rollback version numbers are supported (version number range: 1 ~ 64).
Enabling Anti-Rollback:
Enabling the anti-rollback feature requires the following 2 steps:
Set the anti-rollback version number in OTP:
Read the current anti-rollback version number with the following command:
AT+OTP=RRAW,378,8
Write the anti-rollback version number with the following command:
AT+OTP=WRAW,378,8,<Value_OTP>
Where
<Value_OTP>is the OTP value corresponding to the target version number. Calculation examples:Example 1: Writing either
FFFCFFFFFFFFFFFForFFCFFFFFFFFFFFFFBoth 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
FFF0FFFFFFFFFFFFor0FFFFFFFFFFFFFFFBoth 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
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
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 0x378 ~ 0x37F.
The number of
0bits 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 64 bits in total, so at most 64 anti-rollback version numbers are supported (version number range: 1 ~ 64).
Enabling Anti-Rollback:
Enabling the anti-rollback feature requires the following 2 steps:
Set the anti-rollback version number in OTP:
Read the current anti-rollback version number with the following command:
AT+OTP=RRAW,378,8
Write the anti-rollback version number with the following command:
AT+OTP=WRAW,378,8,<Value_OTP>
Where
<Value_OTP>is the OTP value corresponding to the target version number. Calculation examples:Example 1: Writing either
FFFCFFFFFFFFFFFForFFCFFFFFFFFFFFFFBoth 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
FFF0FFFFFFFFFFFFor0FFFFFFFFFFFFFFFBoth 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
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
OTP Configuration:
The anti-rollback version number is stored in the OTP (One-Time Programmable) area of the chip:
The physical address range for the BOOT image anti-rollback version in OTP is 0x460 ~ 0x46F (
BL_VER_0~F, see OTP configuration area). The ROM compares the major version number of the BOOT image with this value.The number of
0bits 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 128 bits in total, so at most 128 anti-rollback version numbers are supported (version number range: 1 ~ 128).
Enabling Anti-Rollback:
Enabling the anti-rollback feature requires the following 2 steps:
Set the anti-rollback version number in OTP:
Read the current anti-rollback version number with the following command (the length
10is hexadecimal, i.e. 16 bytes):AT+OTP=RRAW,460,10
Write the anti-rollback version number with the following command:
AT+OTP=WRAW,460,<Length>,<Value_OTP>
Where
<Value_OTP>is the OTP value corresponding to the target version number, and<Length>is its length in bytes (hexadecimal). Calculation examples:Example 1: Writing either
FCorCF(<Length>is1)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
F0or0F(<Length>is1)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
Enable the anti-rollback feature:
The anti-rollback feature is controlled by bit 2 (
ANTIROLL_BACK_DIS) of OTP address 0x456. The feature is enabled when this bit is 0.Read the current value with the following command:
AT+OTP=RRAW,456,1
Set bit 2 of the value read to 0 and write it back. For example, if the value read is FF, write FB:
AT+OTP=WRAW,456,1,FB
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:
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.
Write the start address of the BOOT OTA2 partition confirmed in step 1 to OTP :
RTL8721Dx:AT+OTP=WRAW,36C,2,<Value_OTP>
Value_OTPis 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_OTA2is0x08234000,Value_OTPis3482, and the corresponding command is:AT+OTP=WRAW,36C,2,3482
RTL8720E:AT+OTP=WRAW,36C,2,<Value_OTP>
Value_OTPis 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_OTA2is0x08234000,Value_OTPis3482, and the corresponding command is:AT+OTP=WRAW,36C,2,3482
RTL8710E:AT+OTP=WRAW,36C,2,<Value_OTP>
Value_OTPis 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_OTA2is0x08234000,Value_OTPis3482, and the corresponding command is:AT+OTP=WRAW,36C,2,3482
RTL8726E:AT+OTP=WRAW,36C,2,<Value_OTP>
Value_OTPis 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_OTA2is0x08234000,Value_OTPis3482, and the corresponding command is:AT+OTP=WRAW,36C,2,3482
RTL8713E:AT+OTP=WRAW,36C,2,<Value_OTP>
Value_OTPis 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_OTA2is0x08234000,Value_OTPis3482, and the corresponding command is:AT+OTP=WRAW,36C,2,3482
RTL8730E:AT+OTP=WRAW,36C,2,<Value_OTP>
Value_OTPis 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_OTA2is0x08234000,Value_OTPis3482, and the corresponding command is:AT+OTP=WRAW,36C,2,3482
RTL8721F:AT+OTP=WRAW,36C,2,<Value_OTP>
Value_OTPis 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_OTA2is0x08234000,Value_OTPis3482, and the corresponding command is:AT+OTP=WRAW,36C,2,3482
RTL8720F:AT+OTP=WRAW,36C,2,<Value_OTP>
Value_OTPis 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_OTA2is0x08234000,Value_OTPis3482, and the corresponding command is:AT+OTP=WRAW,36C,2,3482
RTL8735C:The BOOT OTA2 start address is stored in OTP physical addresses 0x45E ~ 0x45F (
OTA_ADDR_0andOTA_ADDR_1, see OTP configuration area):AT+OTP=WRAW,45E,2,<Value_OTP>
Value_OTPis 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_OTA2is0x08440000(the SDK default),Value_OTPis4084, and the corresponding command is:AT+OTP=WRAW,45E,2,4084
Enable the BOOT OTA packaging option:
Refer to Configuration (menuconfig) , navigate to
CONFIG OTA OPTION, and enableEnable Bootloader OTA. This option only integrates the BOOT Image intoota_all.binat 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.
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.
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 .
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 .
The multi-core firmware and the AP FIP image (BL1, BL2, BL32 and BL33) are packed together into the application image, so they are upgraded as a whole through OTA. The default OTA1 and OTA2 partitions are described in Flash Layout .
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.
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:
Image pattern and version number validation follow the same procedure as the standard flow.
Only the APP image supports compression.
The compressed image is always downloaded to the OTA2 region during OTA.
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.
Power-loss protection is supported both during the OTA download and during decompression at boot.
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:
The following example illustrates how compressed OTA works:
The device boots from OTA1 and runs the OTA application.
Compressed image is downloaded to OTA2.
On the next boot, the system selects the compressed image, decompresses it to OTA1, and then boots from OTA1.
The diagram is as follows:
Enabling OTA compression requires the following 2 steps:
Enable the OTA compression option:
Refer to Configuration (menuconfig) , navigate to
CONFIG OTA OPTION, and enableEnable Compress APP image.CONFIG OTA OPTION ---> [*] Enable Compress APP image
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.binota_all.bincontaining the compressed image, used for OTA.
After enabling, you can verify the decompression process by programming the compressed image:
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.
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.
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.
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 |
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:
|
Modifying Configurations
Refer to Image Pattern and Version Number to adjust the version number or switch the scheme.
Adjust the anti-rollback version number and enable anti-rollback if necessary. please refer to the enabling steps in Anti-Rollback.
If upgrading the bootloader is needed, please refer to the enabling steps in BOOT OTA.
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.
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 image)
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 |
|---|---|
HTTP Upgrade: Download and upgrade image from a remote server via HTTP protocol. |
|
HTTPS Secure Upgrade: Securely download and upgrade image via HTTPS protocol with SSL/TLS encryption support. |
|
User-Defined Upgrade: Support custom data sources such as SPI, UART, etc.. |
|
Virtual File System Upgrade: Read and upgrade image from virtual file systems (SD card, Flash, etc.). |