Quick Start

This document aims to guide users in quickly setting up their development environment, which includes compiling the SDK, flashing firmware, updating firmware, and capturing logs. The developers can download the prebuilt images included in the SDK to confirm the compatibility and functionality of the EVB and the development environment.

Users can compile the projects in the SDK using Keil, and then use MPPGTool to flash the files onto the EVB. Once the flashing is complete, users can use DebugAnalyzer to capture logs from the SoC end, as shown in the following figure.

Required EVB

The EVB provides a hardware environment for user development and application debugging. It consists of a motherboard and a daughterboard. Please refer to RTL87x3E EVB Interfaces and Modules for peripheral interface wiring. For more information, please refer to the respective Evaluation Board User Guide.

Reqired Files

For each RTL87x3E/RTL87x3D project, users typically need flash multiple images, including the base images and the application image. The base images contain the necessary firmware and configuration settings for the RTL87x3E/RTL87x3D chipset, while the application image contains the specific code and functionality for the target application.

The default burning files for RTL87x3E/RTL87x3D are as shown in the following table. For more information about these files, please refer to Compilation and Download.

Files

Provided by Realtek

File Type

Note

OTA Header File

(MPPGTool generation)

Base Image

Boot Patch Image

✔

Base Image

DSP APP Image

✔

Base Image

DSP SYS Image

✔

Base Image

DSP Config Image

(DspConfigTool generation)

Base Image

FSBL File

✔

Base Image

Lowerstack EXT Image

✔

Base Image

RTL87X3E only

Platform EXT Image

✔

Base Image

RTL87X3E only

Stack Patch File

✔

Base Image

SYS Patch File

✔

Base Image

RTL87X3E only

Upperstack File

✔

Base Image

RTL87X3E only

Patch File

✔

Base Image

RTL87X3D only

APP Config File

(MCUConfigTool generation)

Base Image

System Config File

(MCUConfigTool generation)

Base Image

VPData Config File

(MCUConfigTool generation)

Base Image

RTL87X3E only

User Data Bin

(GUIPackageTool generation)

Base Image

16M only

APP Demo Bin

(Project compilation generation)

Application Image

Tools

During the development based on RTL87x3E/RTL87x3D SDK, users will need to use Realtek’s development toolkits. Please refer to the following table.

Tools

URL

Tool Version

OS

ARM Keil MDK

https://developer.arm.com

uVision: V5.36
ARMCC: 506build750

Win10

Git Bash

https://git-scm.com/downloads

Win10

J-Link Software

https://www.segger.com/

v6.32 or later

Win10

MPPGTool

\tool\MPPGTool-vX.X.X.X

Win10

DebugAnalyzer

\tool\DebugAnalyzer-vX.X.X.X

Win10

AciHostCLI Tool

\tool\AciHostCLI-vX.X.X.X

Win10

Note

  1. All installation packages under the path are in .zip format and need to be manually extracted by the user.

  2. The tools are compatible for use in Windows systems.

ARM Keil MDK

Users can compile all the applications in the SDK using the Keil MDK. For more detailed information, please refer to Keil MDK in the documentation.

Git Bash

As bash.exe will be used in the pre-build or after-build command line, please install Git from https://git-scm.com/downloads . After Git is installed, take the installation in C:\Program Files as an example, and confirm that the environment variable PATH is added with C:\Program Files\Git\usr\bin.

MPPGTool

Users can flash files using MPPGTool, which has two flashing modes: MP mode and Debug mode. MP mode is suitable for mass production. This document primarily focuses on the Debug mode, which is intended for developers in the early stages of software development. For more information, please refer to MPPG Tool User Guide.

DebugAnalyzer

Users can use DebugAnalyzer to capture and parse SoC logs. For more information, please refer to Debug Analyzer User Guide.

AciHostCLI Tool

AciHostCLI is a test tool running on PC, which is used to demo ACI usage. It can perform cmd/event communication test with ACI Device through USB serial port. For more information, please refer to BT Audio Transceiver AciHostCLI Tool User Manual.

Bring Up EVB

To ensure that the EVB can work properly, users can follow the steps below:

  1. Prepare an EVB and ensure that the EVB interface is wired correctly (refer to RTL87x3E EVB Interfaces and Modules). Set the EVB to Download Mode (refer to Download Mode) and then power on the EVB (refer to Power Supply).

  2. Double-click to run MPPGTool.exe, as shown in the following figure. For specific operation steps and file paths refer to MPPGTool Download.

    1. In [Flash Map], click open folder icon to load the flash_map.ini file.

    2. Click [Add File(s)] to load all the burning files, refer to Reqired Files.

    3. Click [Detect] to identify the COM port of the EVB.

    4. Click [Open] to open the COM port.

    5. Click [Download] to start the flashing process. The progress bar shows the current flashing progress.

    6. The progress bar shows “Success” when the file is successfully flashed.

  3. After the files are downloaded completely, put the EVB into Normal Mode (refer to Normal Mode).

  4. Observe the behavior of the EVB (LED blinking/phone searching for BLE advertising, etc., based on the actual functionality of the user’s APP Image), or check whether the SoC-side Log meets the expectations (refer to Example Verification).

Hardware Development Environment

The EVB evaluation board provides a hardware environment for user development and application debugging. It consists of a motherboard and a daughterboard. It has Download Mode and Normal Mode, and users need to use different wiring methods to set EVB enter the required mode.

RTL87x3E EVB Interfaces and Modules

Taking RTL87x3E EVB as an example, the EVB interfaces and modules are shown in the following figures.

Note

There may be some differences in the EVB wire map for different ICs (RTL87x3E/RTL87x3D). For detailed information, please refer to the respective Evaluation Board User Guide.

Power Supply

There are two power supply modes for the EVB: USB connector and Li-on battery

If the EVB is powered by the USB connector, please follow the steps below:

  1. Connect VADP of jumper J42 to U_5V_FT (TP25).

  2. Connect the AC adaptor to micro-USB connector CON3, located on the opposite side of the board.

If the EVB is powered by the Li-ion battery, please follow the steps below:

  1. Short jumper J38 (VBAT and BAT+).

  2. Connect the Li-ion battery to the BAT socket J36.

SWD Wiring

RTL87x3E

SWD

GND

GND

IO

SWIO

CLK

SWCK

VDD

Vterf/3.3V

UART

Reset

Microphones

When using the MIC1 jack for electret condenser microphone input, please follow the steps below:

  1. Short J22 and J24.

  2. Connect J25.1 to term 1(+) of the microphone.

  3. Connect J23.1 to term 2(-) of the microphone.

The wire map for the MIC2/MIC3 jack is similar to that of the MIC1 jack.

Headphone

When using the headphone jack for headphone output, please follow the steps below:

  1. Connect J9.3 to J9.2.

  2. Short J8 and J13.

Log Pin Wiring

When using FT232 on EVB for log, please follow the steps below:

  1. Make sure pull off all the jumpers between J40 and J41.

  2. Connect J33.2 FT_VIO to J33.3 VIO2 (1.8V by default, VDDIO1/LDO_AUX in spec) to guarantee the voltage consistency.

  3. Connect TP6 LOG and J41.3 RX, and connect the USB connector CON3 on the bottom side to PC as USB to UART input.

Download Mode

  1. Connect USB connector CON3 on bottom side to PC as USB to UART input and supply power for the EVB, as introduced in Power Supply.

  2. Make sure J33.2 FT_VIO is connected to J33.1 VIO1 (3.3V fixed, VDDIO0/LDO_HV33 in spec) to guarantee the voltage consistency.

  3. Use jumpers to connect J40.1 M3_0 to J41.4 TX and connect J40.2 M3_1 to J41.3 RX.

  4. Connect TP6 LOG to TP7 PD and then push RST key to reset SoC.

  5. After entering the download mode, please refer to MPPGTool Download for instructions on how to flash the program.

Normal Mode

  1. Supply power for the EVB, as introduced in Power Supply.

  2. Connect J33.2 FT_VIO to J33.3 VIO2 (1.8V by default, VDDIO1/LDO_AUX in spec) to guarantee the voltage consistency.

  3. Disconnect TP6 LOG and TP7 PD.

  4. Pull off all the jumpers between J40 and J41

  5. If printing logs is required, please refer to Log Pin Wiring.

Compilation and Download

The default burning files for RTL87x3E/RTL87x3D are as introduced in Reqired Files.

The Boot Patch Image, DSP APP Image, DSP SYS Image, FSBL File, Lowerstack EXT Image, Platform EXT Image, Stack Patch File, SYS Patch File, Upperstack File, Patch File are provided by Realtek. Users can download the above information through Anchor which is a release system from Realtek, if there is no Anchor account, please apply for registration from the agent/PM/FAE. Alternatively, users can also download these files directly from the RealMCU website at the following URL: https://www.realmcu.com

Below is a brief introduction of the default burning files:

  1. OTA Header File

    The OTA Header File is a file that defines the layout of the Flash Bank. It is generated by the MPPGTool.

  2. Boot Patch Image

    The Boot Patch Image is provided by Realtek. The ROM code reserves the Patch function entry point, which can be used to optimize the Boot flow, modify the behavior of the secure ROM code, and expand the functionality of the ROM code.

  3. DSP APP Image

    Default DSP application code for RWS project. It could be replaced by the same file generated via DSP SDK.

  4. DSP SYS Image

    Default DSP system code for sample project. It is reserved by Realtek.

  5. DSP Config Image

    Default DSP UI parameter file for sample project. It could be replaced by the same file generated via DSP Configure Tool.

  6. FSBL File

    The binary file is experimental boot loader function which is only needed for development phase.

  7. Lowerstack EXT Image

    Extended for BT Controller stack code.

  8. Platform EXT Image

    Extended for platform code.

  9. Stack Patch File

    The Stack Patch File is a file provided by Realtek that supports features related to the BT Controller stack.

  10. SYS Patch File

    The SYS Patch File is a file provided by Realtek. The ROM code reserves the Patch function entry point, which allows modifications to the behavior of the non-secure ROM code and the expansion of ROM code functionality.

  11. Upperstack File

    Default upperstack code for sample project.

  12. Patch File

    Realtek’s internal code for stack bug fixing or feature extension. It is necessary for any project.

  13. APP Config File

    Default audio application UI parameter file for sample project. It could be replaced by the same file generated via MCUConfigTool.

  14. System Config File

    Default system configuration UI parameter file for sample project. It could be replaced by the same file generated via MCUConfigTool.

  15. VPData Config File

    Default Voice Prompt file for sample project. It could be replaced by the same file generated via MCUConfigTool.

  16. User Data Bin

    The User Data Bin contains the GUI resources that users need to index and use in the MCU, mainly including images and fonts. This bin file is closely tied to the screen display effect.

  17. APP Demo Bin

    The APP Demo Bin is an application developed by the developer. It is compiled from Keil/GCC project and processed using tools like fromelf.

Note

  1. Please store the SDK, tools, and other related materials in a path that does not contain any spaces or chinese characters.

  2. Before burning the files, users need to load the flash_map.ini file, which represents the allocation of addresses for each file in the flash. Users can generate the flash_map.ini file by clicking on [Flash Map Generator] on the MPPGTool interface, as shown in the following figure.

3. If [Chip Erase] is clicked, the flash memory will be completely erased before writing. If this button is not clicked, only the area of files that are being downloaded will be erased from the flash, as shown below.

Generating Flash Map

The flash map.ini file can be generated in the ways introduced in How to Configure Flash Layout.

If do not have any parameters to modify, users can skip this section and directly load the default file from the SDK, located at: \bin\rtl87x3x\flash_map_config\xM\flash_xM\flash_map.ini.

Generating OTA Header

The OTA Header File can be generated in the ways introduced in Generate OTA Header.

If do not have any parameters to modify, users can skip this section and directly load the default file from the SDK, located at:\bin\rtl87x3x\87x3x\xM\BANK0\OTAHeader\mdk\OTAHeader_Bank0_vx.x.x.x_resign-xxxxxxxxxx.bin.

Generating MCU Config File

The APP Config File, System Config File and VPData Config File can be generated in the ways introduced in MCUConfigTool.

If do not have any parameters to modify, users can skip this section and directly load the default file from the SDK, located at:\bin\rtl87x3x\87x3x\xM\rcfg\For EVB.

Generating App Image

All applications in the SDK can be compiled and used through the Keil MDK. Before starting software development, it is necessary to install Keil. It is generally not recommended to create a new project, but to directly open an existing example project and add functional code on top of it.

Keil MDK

Keil MDK is the complete software development environment for a range of ARM Cortex-M based microcontroller devices. MDK includes the µVision IDE and debugger, ARM C/C++ compiler, and essential middleware components.

All applications in the SDK can be compiled and developed using the Keil MDK. Therefore, before starting software development, users need to obtain and install Keil. For more information about Keil, please visit https://www.keil.com/.

The toolchain version information used by Realtek is shown in the following figure. To avoid compatibility issues between ROM executables and applications, it is recommended to use uVision V5.36 or a later version. Configure the default compiler to ARMCC_506build750, as shown below.

Taking bt_audio_trx project as an example, after successful compilation, a bin file with MD5 verification will be generated in the bin folder of the project, as shown in the following figures.

Note

MPPGTool uses MD5 as the checksum value for the burning file and requires adding the MD5 value to the suffix of the file name to be burned. Therefore, the burning file is an APP Image with the prefix “MP”.

Images Download

MPPGTool Download

Please refer to MPPGTool to use MPPGTool to burn the files onto the device.

Example Verification

Mobile App Verification

Taking the “bt_audio_receiver” project as an example, Path:
\bin\rtl87x3e\app_demo_bin\mdk\bt_audio_trx\4M\bt_audio_receiver\BANK0.

For the hardware peripheral wiring of the EVB, users can refer to RTL87x3E EVB Interfaces and Modules and Download Mode. For burning files, please refer to MPPGTool Download. After completing the above steps, press the Reset button on the EVB board, or power-cycle the EVB board.

Users can search for Bluetooth devices through the Bluetooth settings interface on their smartphones. The default device name is 8763ESE, as shown in the following figure. Click on the desired device to establish a connection. Once both the phone and the device confirm the connection, the smartphone will display a successful connection message.

Log Verification

Users can use DebugAnalyzer to capture the SoC Log to check whether the program is running correctly. For details about Log connection, please refer to Log Pin Wiring. Path: \tool\DebugAnalyzer-vx.x.x.x, as shown in the following figure.

Double-click to run DebugAnalyzer.exe, click [Setting], [Baud rate] is set to 2M by default, and load the corresponding .trace file in the [App Trace File].
Path: \trace\app_demo_bin\mdk\bt_audio_trx\4M\bt_audio_receiver\BANK0\bt_audio_trx_bank0.trace, click [Confirm] to confirm the Settings, as shown in the following figure.

Select the correct Serial Port, click on [Start], and DebugAnalyzer will start working. It will save the captured Raw Data in a .bin file, and based on the user’s settings of the .trace file, it will parse the raw data into plain text logs and save them in a .log file.

Taking the “bt_audio_receiver” project as an example, after powering on the EVB board and successfully connecting the Bluetooth device, the following log message app_bond_get_pair_idx_mapping success will be displayed:

While using a mobile phone to play music, the device’s speaker will output the audio. Additionally, the DebugAnalyzer will display the following log messages media_buffer_write and audio_track_path_cback: handle as verification.

Note

  1. Default save path: the DataFile folder in the same directory as DebugAnalyzer.exe, as shown below.

  2. Make sure the .trace file matches the current SoC running image.

  3. If users encounter any issues during the development process, please provide the .log, .bin and .cfa files located in the DebugAnalyzer\DataFile directory, as well as the corresponding .trace file. This will help Realtek analyze and locate the issue more effectively.

Document Descriptions

A series of user guides introducing various functions are provided in the SDK. Users can refer to specific user guides to become familiar with certain functions. Some documents included basic introductions and major functions are listed in this chapter. For more details, please refer to Overview.

Primary Stage

  1. Evaluation Board User Manual

    Make sure to learn this document. This is a basic introduction.

  2. Platform Overview

    This document introduces how to use a SDK to develop Bluetooth Low Power applications, including software, hardware architecture, application introduction, storage, interrupts, programming, debugging and so on.

  3. OTA User Manual

    To generate the required OTA_header file for downloading, users should refer to this document.

Functional Requirements

  1. Understand Flash and storage space

    1. Flash User Guide

    2. Memory Hierarchy User Manual RTL87X3E

    3. OTA User Manual

    This section describes the current allocation and margin of memory space, and how to allocate FlashLayout and storage space during OTA.

  2. Bluetooth communication correlation: BLE Stack User Manual

    This document describes various aspects of Bluetooth technology, including broadcast, connection, pairing, service reading and writing, data processing and so on.

  3. Peripheral related Settings: IO User Manual

    This document describes all related peripheral register settings and functions.

  4. OTA upgrade function: OTA User Manual

    OTA represents the technology that uses Bluetooth to update the image (code and data) running in Flash memory.

  5. Deep low power: Low Power Mode User Manual

    This document introduces the trigger conditions of entering DLPS mode and get out from DLPS, and the corresponding settings. Please read and learn from it carefully, and refer to the BLE Peripheral project.

  6. Flash/Image security: MP Flow for Secure-Enabled Chip

    This document provides instructions on encrypting images and downloading the corresponding encryption key into Efuse.