快速入门

本文档旨在指导用户快速配置RTL87x2G(BEE4)的开发环境，包括编译SDK，烧录固件，升级固件及抓取Log。用户可以下载SDK中的测试文件，确保EVB可以正常工作，并与开发环境兼容且具备相应功能。

概述

RTL87x2G SDK支持Windows和Linux系统，用户可以通过Keil/GCC来编译SDK中的工程，使用MPTool将文件烧录到EVB中，然后通过DebugAnalyzer来抓取SoC端的日志，硬件接线配置及对应PC机软体架构可以参考 EVB工作原理图。

../../../_images/EVBWorkingDiagram.png

EVB工作原理图

准备EVB

EVB评估板提供了用户开发的 硬件环境，用于开发和应用调试设计。它由一块母板和一块子板组成，用户需要准备两条USB数据线连接EVB和PC机，EVB的外围接口接线请参考 EVB接口分布图，更多信息请查阅 评估板指南。

../../../_images/HardwareEnvironment.png

硬件环境

准备文件

EVB正常工作需要烧录以下文件。

  • 基础文件：包括了RTL87x2G所需固件和配置设置文件。

  • 应用文件：包括了目标工程的具体代码和功能实现。

以下是RTL87x2G正常运行需要的 烧录文件，其中 Bank0 APP Config File 为可选烧录文件，文件说明可以参考 编译和下载 章节。

RTL87x2G默认烧录文件

文件

Realtek提供

文件类别

文件烧录选项

System Config File

X（通过MPTool生成）

基础文件

√

Bank0 Boot Patch Image

√

基础文件

√

Bank1 Boot Patch Image

√

基础文件

√

Bank0 OTA Header File

X（通过MPTool生成）

基础文件

√

Bank0 System Patch Image

√

基础文件

√

Bank0 BT Stack Patch Image

√

基础文件

√

Bank0 BT Host Image

√

基础文件

√

Bank0 APP Image

X（工程编译生成）

应用文件

√

Bank0 APP Config File

X（通过MPTool生成）

基础文件

非必选

软件工具

用户在开发RTL87x2G SDK的过程中，需要使用到Realtek的 开发工具包及ARM/GCC开发套件，具体如下。

准备工具

工具

链接/路径

版本

OS

ARM Keil MDK

ARM 链接

uVision: V5.36

ARMCC: V6.17

Win10

GNU Toolchain

GNU Toolchain 链接

13.2.Rel1(或更新)

Windows/Linux

MinGW

MinGW 链接

V3.82.90(或更新)

Windows

MPTool

BEE4-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.x\BeeMPTool\MPTool.exe

Win10

MPCLI Tool

Windows/Linux/MAC OS

MPPackTool

BEE4-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.x\BeeMPTool\tools\MPPackTool.exe

Win10

PACKCLI Tool

Windows/Linux/MAC OS

DebugAnalyzer

BEE4-SDK-Vx.x.x\tools\DebugAnalyzer-vx.x.x.x\DebugAnalyzer.exe

Win10

备注

  • 路径下的安装包均为 .zip 格式，需要用户自行解压缩。

  • MPCLI Tool为MPTool的跨平台版本，PACKCLI是MPPackTool的跨平台版本，如果用户不是基于Windows系统进行开发，可以使用跨平台版本的工具。

ARM Keil MDK

用户可以通过Keil Microcontroller Development Kit(MDK)编译SDK中的应用，更多信息请查阅 Keil MDK 章节。

GNU Toolchain

用户可以通过GNU Toolchain编译SDK中的应用，开发前请先安装 gcc-arm-none-eabi ，更多信息请查阅 GCC 章节 。

MinGW

用户可以使用 MinGW 来解析 Makefile 。

MPTool/MPCLI Tool

用户可以通过MPTool/MPCLI Tool来烧录文件，MPCLI Tool是MPTool的跨平台版本。MPTool有 量产 和 调试 两种烧录模式，量产烧录模式适用于大规模生产，本文主要描述 调试烧录模式，适用于开发者在软件开发的前期阶段的，更多信息请参考 《RTL87x2x MP Tool User Guide》 。

MPPackTool/PACKCLI Tool

用户可以通过MPPackTool来打包文件，适用于 OTA （空中升级）和量产烧录，PACKCLI Tool是MPPACKTool的跨平台版本，更多信息请参考 《RTL87x2x Pack Tool User Guide》 。

DebugAnalyzer

用户可以通过DebugAnalyzer 抓取SoC端Log，更多信息请参考 《Debug Analyzer User Guide》 。

启动EVB

为确保EVB可以正常使用，用户可以按照以下步骤进行烧录测试：

  1. 准备一块EVB，确认 EVB接口 接线正确，让EVB进入 下载模式，给EVB 上电。

  2. 双击运行 MPTool.exe，具体操作步骤和文件路径请参考 MPTool 章节。

    1. 在 Load Layout 处点击 ..，加载 flash_map.ini 文件。

    2. 点击 Browse 加载所有 烧录文件。

    3. 点击 Detect 成功识别EVB的COM口。

    4. 点击 Open 成功打开COM口。

    5. 勾选 Erase All for Download，点击 Download 进行烧录，进度条显示当前烧录进度。

    6. 进度条显示 OK 表示文件烧录成功。

  3. 程序烧录完成后，让EVB进入 工作模式。

  4. 观察EVB行为，可以通过 手机App验证，或者查看 SoC端Log 是否符合预期。

../../../_images/MPToolBurningInterface.png

MPTool烧录界面

备注

  • 请将SDK、Tool等资料存放在不含空格的非中文路径下。

  • 在下载时勾选 Erase All for Download，会先将Flash进行全擦，然后再开始烧写，如果没有勾选，烧录时只根据需要下载的文件进行擦除。

硬件开发环境

EVB提供了用户开发和应用调试的 硬件环境 ，它由主板和子板组成。EVB有 下载模式 和 工作模式 ，用户需要使用不同的接线方法来设置正确的模式。

EVB接口和模块

../../../_images/EVBInterfaceDistribution.png

EVB接口分布图

../../../_images/EVBModulesDistribution.png

EVB模块分布图

供电

CON1和CON2的USB接口均需要与电脑连接给EVB供电。

../../../_images/EVBPowerSupply.png

EVB供电接线

SWD接线

RTL87x2G - SWD对应接口

RTL87x2G

SWD

GND

GND

SWDIO

SWIO

SWDCLK

SWCK

VDDIO

Vterf/3.3V
../../../_images/SWDWiring.png

SWD接线

UART

../../../_images/UARTInterface.png

UART接口

Reset

../../../_images/ResetKey.png

Reset按键

Log接线

在EVB的正反面各有一个拨码开关，将两个开关均拨至“1”端，RX和LOG用跳线帽相接，连接完成后，查看SoC端Log 是否符合预期。

../../../_images/LogWiring.png

Log接线

下载模式

  1. 给EVB上电前，用户需要先将Log Pin(P0_3)接地，有以下两种方法：

    • 方法一：在EVB的正反面各有一个拨码开关，任意一个拨至“ON”，即表示Log接地。

    ../../../_images/GroundingLogPinMethod1.png

    Log接地方法一

    • 方法二：在EVB的正反面各有一个拨码开关，将开关均拨至“1”，连接Log和GND。

    ../../../_images/GroundingLogPinMethod2.png

    Log接地方法二

  2. EVB进入下载模式后，可以通过 MPTool 进行程序烧录。

    备注

    • 使用方法一，程序烧录完成后，EVB进入工作模式，需要将两个拨码开关均拨至“1”。

    • 使用方法二，程序烧录完成后，EVB进入工作模式，需要断开Log和GND之间的连线。

    • 芯片在上电后会读取Log Pin的电平信号，电平为低，则Bypass Flash进入下载模式，否则进入工作模式，运行应用层程序。

工作模式

EVB正常工作需要将正反面的拨码开关均拨至“1”，断开Log和GND。

../../../_images/NormalMode.png

工作模式

编译和下载

以下是 RTL87x2G的烧录文件说明 ：

RTL87x2G的烧录文件说明

序号

文件名称

说明

1

System Config File

用于记录IC硬件配置和蓝牙配置等信息，例如：配置BT地址，修改Link数目等

参数设置项的具体含义可以参考 《RTL87x2x MP Tool User Guide》

2

Boot Patch Image

包含Bank0 Boot Patch Image和Bank1 Boot Patch Image两份文件，ROM code中保留了Patch函数入口，通过Patch可以优化Boot flow、修改secure ROM code原有行为、扩充ROM code功能等

3

Bank0 OTA Header File

定义Flash Bank layout的文件

4

Bank0 System Patch Image

ROM code中保留了Patch函数入口，通过Patch可以修改non-secure ROM code原有行为、扩充ROM code功能等

5

Bank0 BT Stack Patch Image

BT Controller中stack相关feature的支持

6

Bank0 BT Host Image

实现了BLE Upperstack

7

Bank0 APP Image

开发者开发的BLE应用程序，由Keil/GCC工程编译生成，并经过fromelf等工具处理

8

Bank0 APP Config File

用于记录App配置等信息，例如：配置GAP Config信息等

参数设置项的具体含义可以参考 《RTL87x2x MP Tool User Guide》

备注

Boot Patch Image、System Patch Image、BT Host Image、BT Stack Patch Image由Realtek直接提供。用户可以通过Anchor（Realtek文件释放系统）下载上述资料，如果没有Anchor账号，请向Agent/PM/FAE申请注册，或者可以登录 RealMCU 直接下载。

生成Flash Map

使用MPTool，点击 Flash Map Tool，界面会跳转到FlashMapGenerateTool，点击 Confirm 可生成 flash_map.ini，同步还会生成一份 flash_map.h 文件。

如果没有参数需要修改，可以跳过此章节，直接加载SDK中的 默认文件 。

../../../_images/flash_map.ini.png

flash_map.ini

备注

  • 烧录文件前需要先加载 flash_map.ini 文件，flash_map.ini 即为生成的flash layout，可以理解为是各部分在Flash中的地址分配。

  • 在 FlashMapGenerateTool界面，点击下拉 Flash Size 选项，用户可以根据Flash的实际使用情况，选择合适的Flash Size。

  • 用户可以根据实际需求，自行修改Flash Layout，点击 Layout Init，调整各区域大小，确认后点击 Confirm，更多详细信息请参考 Memory指南。

  • 根据Flash布局排布的不同，分成两种OTA方案：支持Bank切换和不支持Bank切换，用户根据实际情况点击 Support OTA Switch 进行选择，默认选择Disable，更多详细信息请参考 OTA。

../../../_images/FlashMapGenerate.png

Flash Map Generate Tool

备注

  • 如果Flash Layout有被修改，请将新生成的 flash_map.h 文件复制到 图示路径，生成正确的加载地址，供Bank0 APP Image使用，更多详细信息请参考 Memory指南。

  • 图示路径 是SDK默认的flash_map.h路径，适用于大多数示例工程，如果应用工程使用其他路径下的 flash_map.h，需要更新对应路径下的文件。

../../../_images/flash_map.png

flash_map.h

生成OTA header

使用MPTool，点击 Flash Map Tool，界面会跳转到FlashMapGenerateTool，点击 Confirm，生成 flash_map.ini 的同时也会同步生成 OTA Header File。BootLoader会按照此文件读取各Image的布局分布。

如果没有参数需要修改，可以跳过此章节，直接加载SDK中的 默认文件。

../../../_images/OTAHeader.png

OTA Header File

备注

如果Flash Layout有被修改，OTA Header File 也会同步更新，请注意 flash_map.ini 和 OTA Header File 的一致性。

生成System Config File

使用MPTool，点击 Config Set，在Config Setting界面调整相关参数，点击 Confirm 后会直接生成 System Config File 并加载到对应区域。对于初次使用的开发者，Config Setting界面的参数设置建议保持默认配置，更多参数设置可以参考 《RTL87x2x MP Tool User Guide》。

如果没有参数需要修改，可以跳过此章节，直接加载SDK中的 默认文件。

../../../_images/SystemConfigFile.png

System Config File

备注

如果Flash Layout有被修改，需要重新生成 System Config File。

编译APP Image

SDK中所有的应用都能够通过Keil Microcontroller Development Kit(MDK)/GCC编译以及使用。在进行软件开发之前，需要先安装Keil或GCC编译环境。为了方便快速建立开发工程，用户可以拷贝或直接打开现有的示例工程，在此基础上增加功能代码。

Keil MDK

Keil MDK是一套完整的软件开发环境，适用于多种基于Arm Cortex-M的微控制器设备。MDK包括了µVision集成开发环境和调试器、Arm C/C++编译器，以及必要的中间件组件。

SDK中所有的应用能够通过Keil Microcontroller Development Kit(MDK)编译以及使用。所以在进行软件开发之前，要先取得并安装Keil。有关Keil的更多信息请访问 www.keil.com。

Realtek使用的工具链版本信息如图所示。为避免产生ROM可执行程序和应用之间的兼容性问题，建议使用uVision V5.36版本或者更新的版本，并将ARMCLANG默认编译器配置成compiler 6.17。

../../../_images/KeilVersionInformation.png

Keil版本信息

../../../_images/KeilCompilerVersionConfiguration.png

Keil编译器版本配置

以ble_peripheral工程为例，编译成功后会在工程的bin文件夹下生成 带md5校验的bin文件 和对应的 .trace 文件，其中 .trace 文件用于解析SoC端Log。

../../../_images/Compileble_peripheralProject.png

编译ble_peripheral工程

../../../_images/ProjectCompileGenerateFiles.png

工程编译生成文件

备注

MPTool采用md5作为烧录文件的校验值，并要求将md5值加入到待烧录文件的文件名后缀中，所以烧录的是带MP前缀的APP Image。

GCC

编译GCC工程，需要对 GNU Toolchain 和 MinGW 进行正确的环境变量配置，以D盘为安装根路径为例，添加如下路径到环境变量。

D:\GCC\MinGW\bin;
D:\GCC\MinGW\include;
D:\GCC\MinGW\lib;
D:\GCC\gcc-arm-none-eabi-10-2020-q4-major-win32\gcc-arm-none-eabi-10-2020-q4-major\bin;

以ble_peripheral为例，在工程所在的gcc目录下运行cmd指令，输入指令 mingw32-make，GCC工程编译成功后会在工程的bin文件夹下生成 带md5校验的bin文件。

../../../_images/GCCProjectCompilation.png

GCC工程编译

../../../_images/GCCAPPImagePath.png

GCC下的AppImage文件路径

文件下载

MPTool

设置EVB进入下载模式，然后用户可以通过MPTool给设备烧录程序，软件版本不低于V1.1.0.x。

  1. 双击运行MPTool.exe。

../../../_images/MPTool.exe.png

MPTool.exe

  1. 【芯片类型】选择：RTL8762G_VB（别称：BEE4）。

../../../_images/MPToolICTypeSelection.png

MPTool芯片选型

  1. 【类型】选择：调试。

../../../_images/MPToolModeSelectionCN.png

MPTool模式选择

  1. 在 MPTool烧录界面 的 Load Layout 处点击 .. 按钮，加载 flash_map.ini 文件。

  2. 点击 Browse，加载所有烧录文件，文件类型和加载路径如下表所示。

    1. Bank0 APP Image：建议加载 默认文件 中的APP Image。

    2. 设备上电后会发出广播，可以通过 手机端扫描广播，测试设备端程序是否正常运行。­

    RTL87x2G烧录文件和路径

    文件类型

    文件名

    文件路径

    System Config File

    configFile_xxx.bin

    BEE4-SDK-Vx.x.x\bin\rtl87x2g\default_bin\disable_bank_switch \trustzone_disable\common

    Bank0 Boot Patch Image

    BANK0_boot_patch_MP_release_xxx.bin

    BEE4-SDK-Vx.x.x\bin\rtl87x2g\default_bin\disable_bank_switch \trustzone_disable\common

    Bank1 Boot Patch Image

    BANK1_boot_patch_MP_release_xxx.bin

    BEE4-SDK-Vx.x.x\bin\rtl87x2g\default_bin\disable_bank_switch \trustzone_disable\common

    Bank0 OTA Header File

    OTAHeader_Bank0_xxx.bin

    BEE4-SDK-Vx.x.x\bin\rtl87x2g\default_bin\disable_bank_switch \trustzone_disable\common\bank0

    Bank0 System Patch Image

    sys_patch_MP_release_xxx.bin

    BEE4-SDK-Vx.x.x\bin\rtl87x2g\default_bin\disable_bank_switch \trustzone_disable\common\bank0

    Bank0 BT Stack Patch Image

    bt_stack_patch_MP_master_xxx.bin

    BEE4-SDK-Vx.x.x\bin\rtl87x2g\default_bin\disable_bank_switch \trustzone_disable\common\bank0

    Bank0 BT Host Image

    bt_host_MP_xxx.bin

    BEE4-SDK-Vx.x.x\bin\rtl87x2g\default_bin\disable_bank_switch \trustzone_disable\common\bank0

    Bank0 APP Image

    app_MP_sdk_xxx.bin

    BEE4-SDK-Vx.x.x\bin\rtl87x2g\default_bin\disable_bank_switch \trustzone_disable\common\bank0\ble_peripheral

    Bank0 APP Config File

    appConfigFile_xxx.bin

    BEE4-SDK-Vx.x.x\bin\rtl87x2g\default_bin\disable_bank_switch \trustzone_disable\common\bank0

  3. 点击 Detect，界面会显示识别到的设备COM口。

  4. 点击 Open，如果COM口可以正常打开，进度条右侧会显示 OK，否则显示 Fail。
    如果显示 Fail，用户可以参照常见错误逐一排查，检查无误后重复步骤，点击 Detect ‣ Open。

    常见错误如下

    • 检查串口Tx/Rx是否接反

    • 检查设备P0_3即Log Pin接地再上电

    • 检查串口转接板是否支持1M波特率

    • 检查COM被占用

  5. 串口打开成功，点击 Download，COM口右侧进度条显示当前程序下载进度。

    1. Download完成后会显示 OK。

    2. 如果显示 Fail，按下EVB上的Reset按键或给EVB重新上电后重复上述步骤。

    备注

    • MPTool支持两种烧录模式：

      • 量产模式：用于产线生产

      • 调试模式：用于开发人员开发调试时使用

    • ­­MPTool可烧录单个或者多个文件，如果只是烧录单个文件，比如Bank0 APP Image，不要勾选 Erase All for Download。

示例验证

手机App验证

以ble_peripheral工程为例，确认 EVB接口 接线正确，让EVB进入 下载模式 ，加载SDK中的 默认文件，烧录完成让EVB进入 工作模式。

用户可以通过手机蓝牙APP搜索BLE广播，广播名称默认是 BLE_PERIPHERAL，点击 Connect，手机与设备成功连接后，会在手机端显示对端设备的Service。

../../../_images/BLEAdvertising.png

设备广播

../../../_images/ConnectionSuccess.png

手机连接广播成功

Log验证

用户可以通过DebugAanlyzer抓取SoC端Log确认程序是否正确运行，请正确完成 Log接线。

../../../_images/DebugAnalyzer.exe.png

DebugAnalyzer.exe

双击运行DebugAnalyzer.exe，点击 Setting，Baud rate 默认是2M，在 App Trace File 处加载对应工程的 .trace 文件，最后点击 Confirm 确认设置。

../../../_images/DebugAnalyzerParameterSetting.png

Debug Analyzer参数设置界面

选择正确的Serial Port，点击 Start，DebugAanlyzer开始工作，PC会将抓取的原始数据（Raw Data）保存在 .bin 文件中，并根据用户设置的 .trace 文件，将原始数据解析为明文Log，保存在 .log 中。

以ble_peripheral工程为例，EVB板上电后，如果有 GAP adv start 的Log，代表设备开始广播。点击手机蓝牙APP界面的 Connect，Log打印 GAP adv stoped:because connection created，代表手机与设备连接成功。

../../../_images/ADV.png

ADV Start

../../../_images/ConnectionCreate.png

Connection Create

../../../_images/LogDataFile.png

Log Data File

备注

  • Log文件默认保存路径如上图所示：DebugAnalyzer.exe同目录下的 DataFile文件夹。

  • .trace 文件是用于解析串口接收到的二进制Log流，工程每次编译完成后都会生成新的 .trace 文件，需要确保 .trace 文件与当前SoC运行代码匹配。

  • 开发过程中如遇到问题，请提供上图 DataFile文件夹 路径下的 .log .bin .cfa 文件以及 .trace 文件，以便Realtek解析定位问题。