OTA

OTA (Over-The-Air) technology refers to a method of remotely updating the flash storage of RTL87x2G 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.

  • Whether or not Bank switching is supported, the Boot Patch image is always independently dual-banked, serving the same function and acting as a backup for each other. For example, if the current Boot Patch is running in Bank0, the OTA can only upgrade the Boot Patch in Bank1. After the upgrade is complete, the system will restart and choose the Bank with the higher version number to run. If the version numbers are the same, it will run in Bank0.

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 flow

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

Protocol Type

Mandatory

0xFFF3

Read

Uint16

0xNNNN

A read request to obtain OTA protocol information

Image Version

Mandatory

0xFFE0~FFE1

Read

(Uint32+Uint16)*21+2

Byte0: bank num

  • 0: active bank

  • 1: inactive bank

Byte1: image num

Byte2~Byte3: image ID 1

Byte4~Byte7: image version 1

Byte8~Byte9: image ID 2

Byte10~Byte13: image version 2

……

read image versions of device, see the following notes for details

Image Section Size

Mandatory

0xFFE4~FFE5

Read

(Uint32+Uint16)*21+1

Byte0: image num

Byte1~Byte2: image ID 1

Byte3~Byte6: image max size 1

Byte7~Byte8: image ID 2

Byte9~Byte12: image max size 2

……

a read request to obtain the maximum size of the firmware layout.

Device info Format (OTA version=1)

Byte

Value

Byte0

ic_type

Byte1

spec version

Byte2

Bit0: buffer check

0: not support buffer check

1: support buffer check

Bit1: AES

0: AES not enabled

1: AES enabled

Bit2: encryption mode

0: Encrypt First 16 bytes

1: Encrypt 16*N bytes

Bit3: multi image

0: Update one Image at a time

1: Update Multi Image at a time

Byte3

Reserved

Byte4~5

OTA Temp Buffer Size (uint 4KB)

Byte6

active OTA bank num

0: not support dual bank

1: dual bank, bank0 is the active bank

2: dual bank, bank1 is the active bank

Byte7

active Boot Patch bank num

0: not support dual bank

1: dual bank, bank0 is the active bank

2: dual bank, bank1 is the active bank

Byte8

active Secure APP bank num

0: not support dual bank

1: dual bank, bank0 is the active bank

2: dual bank, bank1 is the active bank

Byte9~10

ctrl header offset

The offset of the ctrl header in the image header

DFU Service

The UUID and Characteristic of DFU Service are as follows:

{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)

None

0x02

Receive FW Image Information

Mandatory

Write

image_id(UINT16)

nImageLength(UINT32)

None

0x03

Validate FW

Mandatory

Write

image_id(UINT16)

is_the_last_image(UINT8)

None

0x04

Activate Image and Reset

Mandatory

Write

is enter DFU mode directly

after reset(UINT8)

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)

0x0D

Get Image Version

Mandatory

Write

bank_num(UINT8)

bank_num(UINT8)

image_num(UINT8)

image_id1(UINT16)

image_version1(UINT16)

0x0F

Check Sha256 Value

Optional

Write

image_num(UINT16)

image_id(UINT16)

sha256 value(UINT16)

image_id(UINT16)

check ret(UINT8)

0x12

Report Image Number

Mandatory

Write

image id(UINT16)

current image number(UINT8)

total image number(UINT8)

None

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

    While writing the image data to the OTA TMP area, the remaining space in the OTA TMP area will be calculated to determine if it can accommodate the next image file to be written. If it can, the process continues by writing the next image file to the OTA TMP area. If it cannot, the data in the OTA TMP area is moved to the OTA Bank0 region, and after a restart, the copy and activation take effect. Subsequently, the next file can be 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

RTL87x2G-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.xBeeMPTool\tools\FlashMapGenerateTool.exe

MP Pack Tool

Package OTA file

RTL87x2G-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.xBeeMPTool\tools\MPPackTool.exe

APP Data Tool

Generate APP Data files that can be packaged

RTL87x2G-SDK-Vx.x.x\tools\AppData

User Data Tool

Generate User Data files that can be packaged

RTL87x2G-SDK-Vx.x.x\tools\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 = 2MB)

Size(Bytes)

Start Address

Reserved

4K

0x04000000

OEM Header

4K

0x04001000

Bank0 Boot Patch

32K

0x04002000

Bank1 Boot Patch

32K

0x0400A000

OTA Bank0

596K

0x04012000

  • OTA Header

4K

0x04012000

  • System Patch code

32K

0x04013000

  • BT Stack Patch code

60K

0x0401B000

  • BT Host code

212K

0x0402A000

  • APP code

284K

0x0405F000

  • APP Config File

4K

0x040A6000

  • APP data1

0K

0x040A7000

  • APP data2

0K

0x040A7000

  • APP data3

0K

0x040A7000

  • APP data4

0K

0x040A7000

  • APP data5

0K

0x040A7000

  • APP data6

0K

0x040A7000

OTA Bank1

596K

0x040A7000

  • OTA Header

4K

0x040A7000

  • System Patch code

32K

0x040A8000

  • BT Stack Patch code

60K

0x040B0000

  • BT Host code

212K

0x040BF000

  • APP code

284K

0x040F4000

  • APP Config File

4K

0x0413B000

  • APP data1

0K

0x0413C000

  • APP data2

0K

0x0413C000

  • APP data3

0K

0x0413C000

  • APP data4

0K

0x0413C000

  • APP data5

0K

0x0413C000

  • APP data6

0K

0x0413C000

Bank0 Secure APP code

0K

0x0413C000

Bank0 Secure APP Data

0K

0x0413C000

Bank1 Secure APP code

0K

0x0413C000

Bank1 Secure APP Data

0K

0x0413C000

OTA Temp

32K

0x0413C000

FTL

16K

0x04148000

APP Defined Section

736K

0x040FF000

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
  1. Get the System Patch, BT Stack Patch, and BT Host image that runs in OTA Bank1.

    Note

    The default released System Patch, BT Stack Patch, and BT host image can only run in OTA Bank0. Please consult Realtek to get the System Patch, BT Stack Patch, and BT Host image that runs in OTA Bank1 when choosing the supporting Bank switching scheme.

  2. 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 = 1MB)

Size (Bytes)

Start Address

Reserved

4K

0x04000000

OEM Header

4K

0x04001000

Bank0 Boot Patch

32K

0x04002000

Bank1 Boot Patch

32K

0x0400A000

OTA Bank0

612K

0x04012000

  • OTA Header

4K

0x04012000

  • System Patch code

32K

0x04013000

  • BT Stack Patch code

60K

0x0401B000

  • BT Host code

212K

0x0402A000

  • APP code

304K

0x0405F000

  • APP Config File

4K

0x040AC000

  • APP data1

0K

0x040AD000

  • APP data2

0K

0x040AD000

  • APP data3

0K

0x040AD000

  • APP data4

0K

0x040AD000

  • APP data5

0K

0x040AD000

  • APP data6

0K

0x040AD000

OTA Bank1 (Equal to 0)

0K

0x040AD000

Bank0 Secure APP code

0K

0x040AD000

Bank0 Secure APP Data

0K

0x040AD000

Bank1 Secure APP code

0K

0x040AD000

Bank1 Secure APP Data

0K

0x040AD000

OTA Temp

312K

0x040AD000

FTL

16K

0x040FB000

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 1280-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 1280 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-0e3f724a441696591000cac6f98aa8a4.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 1280 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-0e3f724a441696591000cac6f98aa8a4.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 = 1MB)

Size (Bytes)

Start Address

Reserved

4K

0x04000000

OEM Header

4K

0x04001000

Bank0 Boot Patch

32K

0x04002000

Bank1 Boot Patch

32K

0x0400A000

OTA Bank0

612K

0x04012000

  • OTA Header

4K

0x04012000

  • System Patch code

32K

0x04013000

  • BT Stack Patch code

60K

0x0401B000

  • BT Host code

212K

0x0402A000

  • APP code

192K

0x0405F000

  • APP Config File

4K

0x0408F000

  • APP data1

0K

0x04090000

  • APP data2

0K

0x04090000

  • APP data3

0K

0x04090000

  • APP data4

0K

0x04090000

  • APP data5

0K

0x04090000

  • APP data6

0K

0x04090000

OTA Bank1(Equal to 0)

0K

0x04090000

Bank0 Secure APP code

0K

0x04090000

Bank0 Secure APP Data

0K

0x04090000

Bank1 Secure APP code

0K

0x04090000

Bank1 Secure APP Data

0K

0x04090000

OTA Temp

212K

0x04090000

FTL

16K

0x040C5000

user data1

16K

0x040C9000

user data2

16K

0x040CD000

user data3

16K

0x040D1000

user data4

16K

0x040D5000

user data5

16K

0x040D9000

user data6

16K

0x040DD000

user data7

16K

0x040E1000

user data8

16K

0x040E5000

APP Defined Section

4K

0x040E9000

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

  1. Use the script : RTL87x2G-SDK-Vx.x.x\tools\UserData to generate a User Data file that supports packaging.

  2. 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.