OTA

OTA refers to the wireless delivery of software updates to devices. SDK supports OTA via Bluetooth. SDK supports two Bluetooth transports for Android and iOS: OTA via GATT, which is suitable for both iOS and Android, and OTA via SPP, which is only suitable for Android. The OTA has more details on OTA principle and design. The OTA project gives a simple example of how to use OTA. This project implements dual bank OTA.

Requirements

The sample supports the following development kits:

Hardware Platforms	Board Name	Build Target
RTL87x3E HDK	RTL87x3E EVB	ota_demo_4M_bank0 ota_demo_4M_bank1 ota_demo_16M_bank0 ota_demo_16M_bank1
RTL87x3D HDK	RTL87x3D EVB	ota_demo_8M_bank0 ota_demo_8M_bank1 ota_demo_16M_bank0 ota_demo_16M_bank1 ota_demo_cs_16M_bank0 ota_demo_cs_16M_bank1
RTL87x3EP HDK	RTL87x3EP EVB	ota_demo_4M_bank0 ota_demo_4M_bank1 ota_demo_16M_bank0 ota_demo_16M_bank1

When built for an xxx_4M_xxx build target, the sample is configured to compile and run with a 4M flash map.

When built for an xxx_8M_xxx build target, the sample is configured to compile and run with an 8M flash map.

When built for an xxx_16M_xxx build target, the sample is configured to compile and run with a 16M flash map.

The sample also requires a phone installed RTKOTA APP.

To quickly set up the development environment, please refer to the detailed instructions provided in Quick Start.

Configurations

To disable OTA via GATT or OTA via SPP, modify the macros OTA_DEMO_VIA_GATT_ENABLE and OTA_DEMO_VIA_SPP_ENABLE in src\sample\ota_demo\app_flag.h.

Building and Downloading

The detailed information about Building and Downloading can be found in Building and Downloading.

This sample can be found under sdk\board\evb\ota_demo in SDK folder structure. Take the project rtl87x3e_ota_demo.uvprojx and target ota_demo_4M_bank0 as an example, to build and run the sample with Keil development environment, follow the steps listed below:

Open rtl87x3e_ota_demo.uvprojx.
Choose the build target ota_demo_4M_bank0.
Building the target.

After a successful compilation, the app bin file ota_demo_bank0_MP-v0.0.0.0-xxx.bin will be generated in the directory bin\rtl87x3e\flash_4M_dualbank\bank0.

Download app bin into EVB board.

Experimental Verification

The detailed test procedure can be found in Experimental Verification. Note that the OTA project enables LE advertising all the time for OTA via GATT and users don’t need to enable LE advertising by MCUConfig Tool.

Code Overview

The OTA demo overview will be introduced according to the following parts:

The OTA sample project overview will be introduced in the chapter Source Code Directory.
The OTA sample project source code overview will be introduced in the chapter Source Code Overview.

Source Code Directory

This section describes the project directory and project structure. The reference files directory is as follows:

Project directory: sdk\board\evb\ota_demo.
Project source code directory: sdk\src\sample\ota_demo.
ota_service.c: sdk\src\ble\profile\server.
ota_service.h: sdk\inc\bluetooth\profile\server.

Source files in the sample project are currently categorized into several groups as below.

└── Project: xxx
   ├── include
   └── Device                   		includes startup code
	   ├── startup_rtl.c
	   └── system_rtl.c
   ├── Lib                      		includes all binary symbol files that the OTA is built on
   └── Profile                  		includes LE profiles or services used by the OTA
	   ├── ota_service.c
	   └── transmit_service.c
   └── APP                      		includes the OTA user application implementation
	   ├── app_main.c
	   ├── app_ota.c
	   ├── app_sdp.c
	   :
	   ├── app_cmd.c
	   └── app_transfer.c

Source Code Overview

The following sections describe important parts of this application.

Initialization

main() is invoked when the application is powered on or the chip is reset, and it performs the following initialization functions:

int main(void)
{
    void *app_task_handle;
    APP_PRINT_INFO0("OTA_DEMO START FROM HW_RESET");

    os_msg_queue_create(&ota_demo_io_queue_handle, "ioQ", MAX_NUMBER_OF_IO_MESSAGE, sizeof(T_IO_MSG));
    os_msg_queue_create(&ota_demo_evt_queue_handle, "evtQ", MAX_NUMBER_OF_EVENT_MESSAGE,
                        sizeof(unsigned char));
    app_init_timer(ota_demo_evt_queue_handle, MAX_NUMBER_OF_APP_TIMER_MODULE);

    board_init();
    framework_init();
    app_bt_gap_init();
    app_ota_init();
    app_gap_init();

#ifdef OTA_DEMO_BY_BLE_ENABLE
    app_ble_gap_init();
    app_ble_service_init();
#endif
    app_sdp_init();
    app_spp_init();
    app_transfer_init();

    os_task_create(
        &app_task_handle,       /* Task handle. */
        "ota_demo_main_task",   /* Text name for the task, to facilitate debugging only. */
        ota_demo_main_task,     /* Pointer to the function that implements the task. */
        (void *)0,              /* We are not using the task parameter. */
        APP_TASK_STACK_SIZE,    /* Stack depth in bytes, 1KB. */
        APP_TASK_PRIORITY       /* This task will run at priority 2. */
    );
    os_sched_start();

    return 0;
}

Detailed OTA source code overview can be found in Code Overview.

Troubleshooting

This section introduces some frequently asked questions.

How to Generate Bank1 Images?

OTA needs bank1 images, and here is how to generate bank1 images.

Add bank1 target based on bank0 target.
Modify macro BUILD_BANK to 1 to generate bank1 scatter file based on bank0 scatter file.
Modify bank1 images generation path.