OTA

OTA (Over-The-Air) technology refers to a method of remotely updating the flash storage of RTL8752H series devices via Bluetooth transmission. This technology provides an efficient and convenient way for devices to receive and install updates without the need for physical connections or manual intervention. The SDK supports OTA functionality wirelessly, making it compatible with devices running Android and iOS systems. Specifically, the SDK utilizes the GATT (Generic Attribute Profile) protocol for Bluetooth data transmission to ensure the stability and reliability of the update process. Moreover, OTA updates can not only enhance the performance and functionality of the devices but also fix known vulnerabilities and security issues, thereby improving user experience and device security.

../../../_images/OTA_overview.png

OTA diagram

OTA Scheme

Depending on different Flash Layout, there are two OTA schemes:

  • supporting Bank switching scheme
    OTA Bank0 and OTA Bank1 will serve as backup firmware storage areas for each other. During firmware updates, these two storage areas can be used interchangeably, ensuring that the system can roll back to the previous backup firmware in case of a failed update, thereby guaranteeing system stability and security.
  • non-supporting Bank switching scheme
    OTA Bank1 does not need to be allocated space. Instead, the OTA TMP area needs to be allocated, and its size must be no less than the largest image size of OTA Bank0, thereby saving Flash space relatively. Once the OTA transmission is complete, the BootLoader will move the data from the OTA TMP area to the designated image area of OTA Bank0, and then reboot to apply the update, which relatively increases the reboot time required to complete the OTA upgrade.

Note

  • The supporting Bank switching OTA scheme requires maintaining images for both Bank addresses. The image released by default by Realtek only supports running on Bank0, if user need to run it on Bank1, please contact Realtek for assistance.

  • In the non-support Bank switching scheme, the compressed OTA solution is also supported. During the upgrade, the LZMA compression algorithm is used to compress the image before transferring it to the OTA TMP area, with a compression rate of approximately 70%, which can solve the issue of insufficient Flash space. This solution is not enabled by default and requires contacting Realtek to obtain customized ROM Patch support.

Process Description

The OTA upgrade process is as follows. The overall process of the OTA update and the interaction between the various modules can be more clearly understood from the diagram. In this process, the mobile phone acts as the Controller, and the SoC as the Target. Before the OTA begins, the Controller and Target establish a connection. Subsequently, the Controller retrieves information from the Target to determine whether an upgrade is permissible.

../../../_images/OTA_flow.png

OTA upgrade process

Transmission Protocols

OTA upgrades can be categorized into Silent OTA and Normal OTA based on different transmission protocols.

  • Silent OTA

    During the image upgrade process, the original functions of the device can be used normally. After the upgrade is completed, it only takes a short restart time for the program to automatically switch to the new functions.

  • Normal OTA

    The function is stable. However, the upgrade process requires switching the device to DFU mode, and the original functions cannot be used until the upgrade is completed.

Note

Both types of upgrades will use the OTA Service and DFU Service.

  • OTA Service：used to obtain device information or enter DFU mode.

  • DFU Service：used to execute the upgrade process.

OTA Service

The UUID and Characteristic of OTA Service are as follows:

{0x12, 0xA2, 0x4D, 0x2E, 0xFE, 0x14, 0x48, 0x8e, 0x93, 0xD2, 0x17, 0x3C, 0xFF, 0xD0, 0x00, 0x00}
OTA Service Characteristics

Characteristic Name

Requirement

UUID

Properties

Format

Value

Instruction

OTA CMD

Mandatory

0xFFD1

Write Without Response

Uint8

1

The control endpoint that allows the device to enter DFU mode

Device Mac

Mandatory

0xFFD2

Read

Uint8*6

XX:XX:XX:XX:XX:XX

Read the Bluetooth address of the device to compare with the Bluetooth address in DFU mode

Device Info

Mandatory

0xFFF1

Read

Device info Format

Device info Format

Read device information

Image Counter

Optional

0xFFF2

Write Response

Uint8

0xNN

Inform the device how many image files need to be written next

Image Version

Mandatory

0xFFE0~FFEF

Read

Uint32*N

0xNNNNNNNN

Read the device’s image version
Device info Format (OTA version=1)

Byte

Value

Byte0

ic_type

Byte1

spec version

Byte2

secure version

Byte3

Bit0: buffer check

0: not support buffer check

1: support buffer check

Bit1: AES

0: AES not enable

1: AES enable

Bit2: encryption mode

0: encrypt First 16bytes

1: encrypt 16*N bytes

Bit3: copy image

0: not support copy image

1: support copy image

Bit4: multi image

0: update one image at a time

1: update multi image at a time

Bit5: handshake

0: not support handshake

1: support handshake

Bit6: compress mode

0: not support ota image compressed

1: support ota image compressed

Byte4~5

max buffer size

Byte6

temp bank size (unit: 4KB)

Byte7

reserved

Byte8~11

Indications for each image version. Each indication uses 2 bits.

00: image does not exist.

01: image exists in bank0, OTA should update image for bank1.

10: image exists in bank1, OTA should update image for bank0.

11: image is standalone. OTA should update image for standalone.

Byte12~13

ctrl header offset

The offset of the ctrl header in the image header

Byte14~15

compressed ctrl header offset

The offset of the compressed ctrl header in the image header

DFU Service

DFU Service UUID characteristics are shown below.

{0x12, 0xA2, 0x4D, 0x2E, 0xFE, 0x14, 0x48, 0x8E, 0x93, 0xD2, 0x17, 0x3C, 0x87, 0x62, 0x00, 0x00}

  • Data Characteristic: accepts image data (write no response)

  • Control Point Characteristic: accepts control commands (write/notification)

All control points supported by the DFU Service are listed in the table below:

DFU Opcode

Opcode value

Procedure

Requirement

Properties

Parameter Description

Response Parameter

0x01

Start DFU

Mandatory

Write

crc16(UINT16)

ic_type(UINT8)

secure_version(UINT8)

ctrl_flag.value(UINT16)

image_id(UINT16)

payload_len(UINT32)

start_dfu_mode(UINT8)

None

0x02

Receive FW Image Information

Mandatory

Write

image_id(UINT16)

cur_offset(UINT32)

None

0x03

Validate FW

Mandatory

Write

image_id(UINT16)

None

0x04

Activate Image and Reset

Mandatory

Write

None

None

0x05

Reset System

Mandatory

Write

None

None

0x06

Report Received Image Information

Mandatory

Write

image_id(UINT16)

origin_image_version(UINT32)

cur_offset(UINT32)

0x07

Connection Parameter Update

Mandatory

Write

connIntervalMin(UINT16)

connIntervalMax(UINT16)

connLatency(UINT16)

supervisionTimeout(UINT16)

None

0x09

Buffer Check Enable

Mandatory

Write

image_id(UINT16)

Max buffer size(UINT16)

Mtu size(UINT16)

0x0A

Buffer Check Size & CRC

Mandatory

Write

mBufferSize(UINT16)

mCRC(UINT16)

Next send offset(UINT32)

0x0B

IC Type

Optional

Write

None

ic_type(UINT8)

Note

  • After receiving the image control header, the not_ready in the image control header is temporarily set to 1 and then written into the flash. Once the image transfer is completed and the image integrity check is successful, the not_ready in the backup area image is changed to 0 to mark the backup area image as valid. This design ensures that when the OTA transfer is interrupted, the BootLoader can easily identify whether the image is in a ready state.

  • During data transmission, if AES encryption is used, every 16 bytes of data will be encrypted, and the part less than 16 bytes will not be encrypted and sent directly. After receiving the data, the receiving end needs to decrypt the encrypted part first.

  • If buffer check is enabled, data is written into the flash after the buffer check size is fully received.

OTA Protocol Process

During an OTA upgrade, the upgrade image is transmitted to the upgrade area via the OTA Service and DFU Service. Once the transfer is complete, a reboot occurs and the Bootloader handles the activation process.

Transmission Process

../../../_images/OTA_Bluetooth_transmission_process.png

OTA Bluetooth transmission process

Activation Process

  • supporting combined image upgrades

    When writing image data to the OTA TMP area, the remaining space in the OTA TMP area is calculated to determine if it can accommodate the next image file to be written. If it can, the next image file is written to the OTA TMP area. When it cannot, the system will first restart to move the OTA TMP area data to the OTA Bank0 area. After the copy activation takes effect, other files are then upgraded.

  • non-supporting combined image upgrades

    When the packaged file to be upgraded contains Patch, APP, or APP DATA, one file upgrade needs to be successfully verified. After the copy is restarted and activated to take effect, the next file can be upgraded.

When the packaged files to be upgraded contain OTA Header file, Patch, APP, or APP DATA, each file must be individually transmitted and validated as successfully received before transmitting and validating the next file. All files must be successfully transmitted and validated before a reboot can occur, otherwise, the current upgrade attempt will be invalid. This is because, in the bank switching scheme, all files in the Bank area need to become effective together for the system to run properly.

Tools Guide

The following are the tools required for the OTA upgrade process.

OTA Upgrade Tools

Tool

Description

Path

Flash Map Generate Tool

Generate flash_map.h, flash map.ini and OTA Header file

RTL8752H-SDK-Vx.x.x\tool\BeeMPTool_vx.x.x.xBeeMPTool\tools\FlashMapGenerateTool.exe

MP Pack Tool

Package OTA file

RTL8752H-SDK-Vx.x.x\tool\BeeMPTool_vx.x.x.xBeeMPTool\tools\MPPackTool.exe

APP Data Tool

Generate APP Data files that can be packaged

RTL8752H-SDK-Vx.x.x\tool\Gadgets\AppData

User Data Tool

Generate User Data files that can be packaged

RTL8752H-SDK-Vx.x.x\tool\Gadgets\UserData

Note

The usage of Flash Map Generate Tool and MP Pack Tool will be introduced in two ways according to whether Bank switching is supported.

Supporting Bank Switching Scheme

Supporting Bank Switching Scheme Flash Layout example is as follows:

Flash Layout Sample (supporting Bank switching)

Sample Layout for flash (total size = 1MB)

Size(Bytes)

Start Address

Reserved

4K

0x00800000

OEM Header

4K

0x00801000

OTA Bank0

344K

0x00802000

  • OTA Header

4K

0x00802000

  • Secure Boot Loader code

4K

0x0080A000

  • ROM Patch code

28K

0x00803000

  • BT Stack Patch code

28K

0x0080B000

  • Upperstack code

144K

0x00812000

  • APP code

132K

0x00836000

  • APP data1

0K

0x00857000

  • APP data2

0K

0x00857000

  • APP data3

0K

0x00857000

  • APP data4

0K

0x00857000

  • APP data5

0K

0x00857000

  • APP Config File

4K

0x00857000

OTA Bank1

344K

0x00858000

  • OTA Header

4K

0x00858000

  • Secure Boot Loader code

4K

0x00860000

  • ROM Patch code

28K

0x00859000

  • BT Stack Patch code

28K

0x00861000

  • Upperstack code

144K

0x00868000

  • APP code

132K

0x0088C000

  • APP data1

0K

0x008AD000

  • APP data2

0K

0x008AD000

  • APP data3

0K

0x008AD000

  • APP data4

0K

0x008AD000

  • APP data5

0K

0x008AD000

  • APP Config File

4K

0x008AD000

FTL

16K

0x008AE000

OTA TMP

0K

0x008B2000

user data1

0K

0x008B2000

user data2

0K

0x008B2000

Note

Flash Layout should be determined based on the actual size of the image and data.

Operating Steps：

  1. Use Flash Map Generate Tool to flash map.ini, flash_map.h, Bank0 OTA Header file and Bank1 OTA Header file.

    1. Flash Size select an appropriate size.

    2. Support OTA Switch select Enable.

    3. Set up two-level flash layout.

    4. Click Confirm to complete the flash layout settings.

    5. Modify the OTA Header file version at Version.

    6. Click Confirm to generate flash_map.h, flash map.ini, Bank0 OTA Header file and Bank1 OTA Header file.

    ../../../_images/dual_bank_Flash_layout_config.png

    Flash layout config and generate OTA Header - supporting Bank switching

    Note

    The version number of the OTA Header used for packaging is higher than the version number of the original running version, so that the new bank can take effect normally after the OTA upgrade.

  2. Copy flash_map.h to the upper-level directory with the project. Link and compile the project to generate app_MP_sdk#####+version+MD5.bin file for packaging.

    ../../../_images/Build_APP_image.png

    Build APP image

    Note

    • Supporting Bank switching scheme needs to compile the app images of OTA Bank0 and OTA Bank1.

    • The demo APP project in the Realtek released SDK can only compile the app image of OTA Bank0 by default. Compiling app image of OTA Bank1 needs modifying the macro #define APP_BANK in mem_config.h in the upper-level directory as the project file to 1.

    /** @brief set app bank to support OTA: 1 is ota bank1, 0 is ota bank0 */
#define APP_BANK                                       1

  3. Get the ROM Patch, BT Stack Patch, Secure Boot Loader and Upperstack image that runs in OTA Bank1.

    Note

    The default released ROM Patch, BT Stack Patch, Secure Boot Loader and Upperstack image can only run in OTA Bank0. Please consult Realtek to get the ROM Patch, BT Stack Patch, Secure Boot Loader and Upperstack image that runs in OTA Bank1 when choosing the supporting Bank switching scheme.

  4. Generate a packet file of ImgPacketFile-xxxxxx.bin in the current directory, which is used for updating.

    1. Select the ForOTA option.

    2. Load the generated flash map.ini.

    3. Click Browse to load all OTA Bank0 and Bank1 images.

    4. Click Confirm to generate the package file.

    ../../../_images/MPPackTool_dual_bank.png

    package files - supporting Bank switching

    Note

    • All the contents defined within the Flash layout in the Bank need to be packaged.

    • It is recommended to package both Bank0 and Bank1.

Non-supporting Bank Switching Scheme

Non-supporting Bank Switching Scheme Flash Layout example is as follows:

Flash Layout Sample (non-supporting Bank switching)

Sample Layout for flash (total size = 512KB)

Size (Bytes)

Start Address

Reserved

4K

0x00800000

OEM Header

4K

0x00801000

OTA Bank0

344K

0x00802000

  • OTA Header

4K

0x00802000

  • Secure Boot Loader code

4K

0x0080A000

  • ROM Patch code

28K

0x00803000

  • BT Stack Patch code

28K

0x0080B000

  • Upperstack code

144K

0x00812000

  • APP code

132K

0x00836000

  • APP data1

0K

0x00857000

  • APP data2

0K

0x00857000

  • APP data3

0K

0x00857000

  • APP data4

0K

0x00857000

  • APP data5

0K

0x00857000

  • APP Config File

4K

0x00857000

OTA Bank1(Equal to 0)

0K

0x00858000

FTL

16K

0x00858000

OTA TMP

144K

0x0085C000

user data1

0K

0x00880000

user data2

0K

0x00880000

Note

The space for APP data is not allocated in this sample. Flash Layout should be distributed based on the actual size of image and data.

Operating Steps：

  1. Use Flash Map Generate Tool to flash map.ini, flash_map.h, and Bank0 OTA Header file.

    1. Flash Size select an appropriate size.

    2. Support OTA Switch select Enable.

    3. Set up two-level flash layout.

    4. Click Confirm to complete the flash layout settings.

    5. Modify the OTA Header file version at Version.

    6. Click Confirm to generate flash_map.h, flash map.ini, and Bank0 OTA Header file.

    ../../../_images/single_bank_Flash_layout_config.png

    Flash layout config and generate OTA Header - non-supporting Bank switching

    Note

    The flash map.ini generated here needs to be consistent with the flash map.ini used internally within the SoC.

  2. Copy flash_map.h to the project directory. Link and compile the project to generate app_MP_sdk#####+version+MD5.bin file for packaging.

    Note

    Non-supporting Bank switching scheme only needs to compile the OTA Bank0 image. The configuration can be found in the project’s parent directory in the mem_config.h file under #define APP_BANK. The specific code is as follows:

/* @brief set app bank to support OTA: 1 is ota bank1, 0 is ota bank0 */
#define APP_BANK                         0

  1. Generate a packet file of ImgPacketFile-xxxxxx.bin in the current directory, which is used for updating.

    1. Select ForOTA option.

    2. Load the generated flash map.ini.

    3. Click Browse to load all OTA Bank0 images.

    4. Click Confirm to generate the package file.

    ../../../_images/MPPackTool_single_bank.png

    package files - non-supporting Bank switching

    Note

    • Bank0 OTA Header file can’t be packaged.

    • If only Patch Image or APP Image, either of them can be packaged.

APP Data Upgrade

APP Data Tool is used to convert the original APP Data bin file into an APP Data type image that can be programmed into Flash using the MP Tool.

After processing with the APP Data Tool, a 512-byte MP header and a 1024-byte image header will be added to the original APP data. These headers are used for MP Tool programming and Bootloader verification, respectively. Suppose the original APP Data bin file size is 120KB. The final size programmed into the flash will be 1024 bytes of the image header plus 120KB of the APP data payload.

The following example uses APP Data1, with the specific path as follows:

../../../_images/app_data_tool.png

APP Data1

  1. File Description：

    1. SampleAppData1.bin is the original APP data bin file.

    2. SampleImageAppData1_MP_0.0.0.1-b9dff8aa815059047f6844497d328342.bin is the bin file of APP Data1 generated by Tool for download.

  2. Open run.bat and replace all instances of SampleAppData1 with the bin file name of the APP Data that needs to be processed..

    ../../../_images/run.bat.png

    run.bat

    Note

    Note that the last line must be “xxx_MP.bin”, and the suffix “_MP” cannot be changed.

  3. By running run.bat，three additional files will be generated:

    1. SampleImageAppData1.bin：a bin file with a 1024 bytes image header added to the original APP Data bin file.

    2. SampleImageAppData1_MP.bin：a bin file with an additional 512 bytes MP Header added to the SampleImageAppData1.bin file.

    3. SampleImageAppData1_MP_0.0.0.1-b9dff8aa815059047f6844497d328342.bin：the MD5 checksum is calculated based on xxx_MP.bin.

    Note

    Note that only bin files with both _MP and MD5 checksums can be used for final download and OTA.

User Data Upgrade

User Data is primarily used to store data that does not affect system functionality. The upgrade strategy for User Data differs from other images. For other images, they are first transferred to the OTA TMP area, while User Data is directly transferred to its corresponding Flash address.

Below is an example of upgrading User Data with a 1M byte flash. The flash layout is shown in the table below:

Flash Layout Sample (User Data upgrade)

Sample Layout for flash (total size = 1M)

Size (Bytes)

Start Address

Reserved

4K

0x00800000

OEM Header

4K

0x00801000

OTA Bank0

344K

0x00802000

  • OTA Header

4K

0x00802000

  • Secure Boot Loader code

4K

0x0080A000

  • Platform Patch code

28K

0x00803000

  • BT Stack Patch code

28K

0x0080B000

  • Upperstack code

144K

0x00812000

  • APP code

136K

0x00836000

  • APP data1

0K

0x00858000

  • APP data2

0K

0x00858000

  • APP data3

0K

0x00858000

  • APP data4

0K

0x00858000

  • APP data5

0K

0x00858000

  • APP Config File

4K

0x00858000

OTA Bank1(Equal to 0)

0K

0x00859000

FTL

16K

0x00859000

OTA TMP

144K

0x0085D000

user data1

32K

0x00881000

user data2

32K

0x00889000

Operating Steps：

  1. Use Flash Map Generate Tool to flash map.ini, flash_map.h, and Bank0 OTA Header file.

    ../../../_images/user_data_Flash_layout_config.png

    Flash layout config and generate OTA Header – User Data upgrade

    Note

    The flash map.ini generated here needs to be consistent with the flash map.ini used internally within the SoC.

  2. Use the script : RTL8752H-SDK-Vx.x.x\tool\Gadgets\UserData to generate a User Data file that supports packaging.

  3. Generate a packet file of ImgPacketFile-xxxxxx.bin in the current directory, which is used for updating.

    1. Select ForOTA option.

    2. Load the generated flash map.ini.

    3. Click Browse to load User Data image.

    4. Click Confirm to generate the package file.

    ../../../_images/MPPackTool_user_data.png

    package files – User Data upgrade

    Note

    • If only certain User Data needs to be updated, only one of them can be packaged.

    • Allows User Data to be packaged and upgraded together with other images.