快速入门

本文档旨在指导用户快速配置 RTL8777G EVB 开发环境，包括编译 SDK，烧录固件，升级固件及抓取 Log。RTL8777G SDK 提供了 matter/thread 相关的模块，方便 matter 厂商可以二次开发 matter 相关的应用。

环境需求

准备EVB

RTL8777G EVB 评估板提供了用户开发和应用调试的硬件环境，是给用户开发和应用调试设计的，带有 USB 模块直接供电，分下载模式和工作模式，用户需要使用不同的接线方法来设置 EVB 进入所需的模式。

硬件连线

下载模式

../../../_images/image4_5.png

下载模式接线图 正面（左） 反面（右）

如下载模式接线图（左） 将 P3_1 和 TX 短接，P3_0 和 RX 短接，下载模式接线图（右） LOW 和 LOG 短接，接着按下 reset，进入下载烧录模式。

备注

芯片在上电后会读取 Log Pin 的电平信号，如果电平为低，则 Bypass Flash，进入烧录模式，否则运行应用层程序。

工作模式

../../../_images/image6_7.png

工作模式接线图 正面（左） 反面（右）

如 工作模式接线图 所示，LOW 和 LOG 断开。 将 RX 和 LOG 用跳线帽相接，如工作模式接线图 (右) 所示，连接完成后，请参考 Log 验证 。

配置选项

对于示例工程，请使用默认配置。

编译和下载

固件编译

  1. Prepare openthread

$ cd beeSDK/subsys/openthread

  1. Clone openthread in the current folder

$ git clone https://github.com/openthread/openthread

  1. Prepare Matter

$ cd beeSDK/subsys/matter

  1. Clone Matter source code in the current folder:

$ git clone https://github.com/project-chip/connectedhomeip
$ cd connectedhomeip/
$ git checkout v1.4.0.0

  1. Modify matter

$ cd subsys/matter/connectedhomeip/
$ git apply ../rtk_matter/rtl87x2g_matter1.4.patch
$ tar -xvf ../rtk_matter/connectedhomeip.tar -C ./

  1. Setup Matter environment

$ cd connectedhomeip/
$ git submodule update --init --recursive
$ source scripts/bootstrap.sh
$ source scripts/activate.sh

  1. Build Matter lighting app

$ cd subsys/matter/samples
$ ./build.py rtl8777g lighting

固件下载

为确保 EVB 可以正常使用，用户可以按照以下步骤进行操作：

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

  2. 双击运行 MP Tool.exe，如 MP Tool 烧录界面 所示，具体操作步骤和文件路径参考 MP Tool。

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

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

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

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

    5. 点击 Download 进行烧录，进度条显示当前烧录进度。

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

../../../_images/image8.png

MP Tool 烧录界面

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

  2. 观察 EVB 行为（LED 闪烁/手机搜索 Bluetooth Low Energy 广播等，以用户 APP Image 的实际功能为准），或者查看 SoC 端 Log 是否符合预期。

文件准备

EVB可以正常运作需要烧录多份文件，包括基础文件和应用文件。基础文件包括了 RTL8777G 所需固件和配置设置文件，应用文件包括了目标工程的具体代码和功能实现。

RTL8777G 默认烧录文件如下，相关文件说明可以参考RTL8777G 烧录文件说明.

RTL8777G 默认烧录文件

文件

Realtek 提供

文件类别

System Config File

(MP Tool 生成)

基础文件

Bank0 Boot Patch Image

√

基础文件

Bank0 OTA Header File

(MP Tool 生成)

基础文件

Bank0 System Patch Image

√

基础文件

Bank0 Bluetooth Stack Patch Image

√

基础文件

Bank0 Bluetooth Host Image

√

基础文件

Bank0 APP Image

(工程编译生成)

应用文件
RTL8777G 烧录文件说明

序号

文件名称

说明

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 Bluetooth Stack Patch Image

Bluetooth Controller 中 stack 相关 feature 的支持

6

Bank0 Bluetooth Host Image

实现了 BLE Upperstack

7

Bank0 APP Image

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

备注

  • 其中 Boot Patch Image/System Patch Image/Bluetooth Host Image/Bluetooth Stack Patch Image 由 Realtek 直接提供。

  • 用户可以通过 Anchor（Realtek 文件释出系统）下载上述资料，若没有 Anchor 账号，请向代理商/PM/FAE 申请注册，或者可以登录 RealMCU 网站直接下载。

注意事项：

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

  2. 烧录文件前需要先加载 flash map.ini 文件，flash map.ini 即为生成的 flash layout，可以理解为是各部分在 flash 中的地址分配，可以点击 MP Tool 界面上的 Flash Map Tool 直接生成。

../../../_images/image9.png

Flash Map Tool

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

../../../_images/image10.png

Erase All for Download

Flash Map

生成 flash map.ini 文件有以下两种方式，用户可以任选其中一种来操作：

  • 方法一：使用 MP Tool，点击 Flash Map Tool，界面会跳转到 Flash Map Generate Tool，接着使用方法二。
    文件路径：BEE4-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.x\BeeMPTool\FlashMap\flash map.ini
  • 方法二：直接使用 Flash Map Generate Tool，点击 Confirm 生成 flash map.ini。
    工具路径：BEE4-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.x\BeeMPTool\tools\FlashMapGenerateTool.exe
    文件路径：BEE4-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.x\BeeMPTool\tools\flash map.ini
../../../_images/image11.png

Flash Map Generate Tool

注意事项：

  1. 在 Flash Map Generate Tool 界面，点击下拉 Flash Size 选项，用户可以根据 flash 的实际使用情况，选择合适的 Flash Size。

../../../_images/image12.png

Flash Size

  1. 用户可以根据实际需求，自行修改 Flash Layout，点击 Layout Init，调整各区域大小，确认后点击 Confirm 。

../../../_images/image13.png

Flash Layout

  1. 使用方法一和方法二生成 flash map.ini 文件 memory 时，还会创建一个 flash_map.h 文件。请将 flash_map.h 文件复制到合适路径，以生成正确的加载地址，以供 Bank0 APP Image 使用。更多详细信息请参考 Memory 指南 。

Matter 方法一 生成对应路径：BEE4-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.x\BeeMPTool\FlashMap\flash_map.h
Matter 方法二 生成对应路径：BEE4-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.x\BeeMPTool\tools\flash_map.h

备注

  • 需要将上面生成的 flashmap.h 复制到 Matter project build 时 flash_map.h 路径：BEE4-SDK-Vx.x.x\subsys\openthead\vendor\bee4\8777g\flashmap.h

  • flash_map.h 建议保持默认配置

OTA Header

使用 MP Tool，点击 Flash Map Tool，界面会跳转到 Flash Map Generate Tool，点击 Confirm 可生成 flash map.ini。同步会生成 OTA Header File，路径：BEE4-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.x\BeeMPTool\OTAHeader

../../../_images/image14.png

OTA Header File

System Config File

使用 MP Tool，点击 Config Set ，在 Config Setting 界面调整相关参数，点击 Confirm 后会直接生成 System Config File 并加载到对应区域。对于初级使用者，Config Setting 界面设置建议保持默认配置。

../../../_images/image15.png

System Config File

APP Image

SDK 中所有的 matter 应用使用 ubuntu GCC 编译。默认生成路径：\subsys\openthread\build\bin\matter-cli-ftd_bank0_MP_DEV_XXX.bin。一般不建议用户新建工程开发，而是直接打开现有的示例工程，在此基础上增加功能代码。

MP Tool

请参考 下载模式 ，让 EVB 进入下载模式，然后用户可以通过 MP Tool 给设备烧录程序。

路径：BEE4-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.x，软件版本不低于 V1.1.0.x。

  1. 双击运行：MP Tool.exe

../../../_images/image16.png

MP Tool.exe

  1. 选择 Chip type：RTL8777G

../../../_images/image17.png

MP Tool 芯片选型

  1. Type：调试，如 MP Tool 模式选择.
    MP Tool 支持两种烧录模式：
    a. 量产模式：用于产线生产
    b. 调试模式：用于开发人员开发调试时使用
../../../_images/image18.png

MP Tool 模式选择

  1. 在 MP Tool 烧录界面 的 Load Layout 处点击 .. 按钮，加载 flash map.ini 文件。
    路径：BEE4-SDK-Vx.x.x\subsys\openthead\vendor\bee4\8777g\flash map.ini

  2. 在 MP Tool 烧录界面 点击 Browse，加载所有烧录文件，文件类型对应的文件名如下。

备注

  • MP Tool 可烧录单个或者多个文件。

  • 如果只是烧录单个文件，比如 Bank0 APP Image，不要勾选图中的 Erase All for Download。

烧录文件类型名称对应表

文件类型

文件

文件路径

System ConfigFile

configFile_xxx.bin

\subsys\openthread\vendor\bee4\rtl8777g\firmware\trustzone_disable

Bank0 Boot PatchImage

BANK0_boot_patch_MP_release_xxx.bin

\subsys\openthread\vendor\bee4\rtl8777g\firmware

Bank0 OTA HeaderFile

OTAHeader_Bank0_xxx.bin

\subsys\openthread\vendor\bee4\rtl8777g\firmware\trustzone_disable

Bank0 SystemPatch Image

sys_patch_MP_release_xxx.bin

\subsys\openthread\vendor\bee4\rtl8777g\firmware

Bank0 Bluetooth StackPatch Image

bt_stack_patch_MP_master_xxx.bin

\subsys\openthread\vendor\bee4\rtl8777g\firmware

Bank0 Bluetooth HostImage

bt_host_MP_xxx.bin

\subsys\openthread\vendor\bee4\rtl8777g\firmware

Bank0 APP Image

matter-cli-ftd_xxx.bin

\subsys\openthread\vendor\bee4\rtl8777g\firmware\trustzone_disable
../../../_images/image19.png

MP Tool 烧录界面

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

../../../_images/image20.png

MP Tool COM 口识别

  1. 点击 Open，如果MP Tool COM 口识别成功，进度条右侧会显示 “OK”，否则显示 “Fail”。
    如果显示 “Fail”，用户可以参照常见错误逐一排查，检查无误后重复步骤，点击 Detect Open
../../../_images/image21.png

MP Tool COM 口识别成功

常见错误如下

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

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

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

  • 检查 COM 被占用

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

    1. Download 完成后会显示 “OK”。

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

../../../_images/image22.png

MP Tool 程序烧录过程

../../../_images/image23.png

MP Tool 程序烧录成功

MP Pack Tool

用户可以通过 MP Pack Tool 对设备进行升级文件的打包处理，一般适用于量产或 OTA，如果是在开发初期调试阶段，用户可以先跳过此章节。

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

../../../_images/image24.png

MP Pack Tool.exe

  1. 在 MP Pack Tool 界面 双击运行 MP Pack Tool.exe （以Bank0 Boot Patch Image & Bank0 APP Image 为例）

    1. IC Type：RTL8762G_VB

    2. 点击 ForOTA

    3. 点击 Browse

    4. 选择需要升级的文件

备注

  • 待升级的文件大小不能超过设置的 OTA Tmp 区大小（参考工程里的 flash_map.h ），如果待升级总文件的大小超出 OTA Tmp 区，需要分批次打包，然后逐包升级。

  • 由于 Patch，Stack 等文件很少更新，用户一般只需要单独打包 APP Image 即可。

../../../_images/image25.png

MP Pack Tool 界面

  1. 文件加载完成后，点击 Confirm，会生成 ImaPacketFile.bin 文件，如 MP Pack Tool 文件打包确认 和 生成的打包文件 所示。
    路径：BEE4-SDK-Vx.x.x\tools\BeeMPTool_vx.x.x.x\BeeMPTool\tools\ImaPacketFile.bin

    备注

    勾选 save patch，可以选择生成 OTA 文件的保存目录，不勾选默认存在根目录下。

../../../_images/image26.png

MP Pack Tool 文件打包确认

../../../_images/image27.png

生成的打包文件

测试和验证

App验证

在将示例编程到 EVB 板后，用户可以用单灯控制来进行测试。

需要完成以下步骤：

  1. 在执行切换命令前检查开关属性值

    $ ./chip-tool onoff read on-off <node_id> <endpoint_id>

    • <node_id>: user-defined ID of the commissioned node.

    • <endpoint_id>: ID of the endpoint with OnOff cluster implemented.

    例如：

    $ ./chip-tool onoff read on-off 2 1

    Log 中将出现以下信息：

    CHIP:TOO:    OnOff: False

  2. 切换开关属性状态。

    $ ./chip-tool onoff toggle <node_id> <endpoint_id>

    例如：

    $ ./chip-tool onoff toggle 2 1

  3. 检查开关属性值在切换命令后是否已更改。

    $ ./chip-tool onoff read on-off <node_id> <endpoint_id>

    例如：

    $ ./chip-tool onoff read on-off 2 1

    Log 中将出现以下信息：

    CHIP:TOO:    OnOff: True

Log 验证

用户可以通过 Debug Analyzer 抓取和解析 SoC Log。

路径：BEE4-SDK-Vx.x.x\tools\DebugAnalyzer-vx.x.x.x

../../../_images/image28.png

Debug Analyzer.exe

  1. 双击运行 Debug Analyzer.exe，点击 Setting，Baud rate 默认是 2M，在 App Trace File 处加载对应工程的 .trace 文件。路径：BEE4-SDK-Vx.x.x\download_images\ble_peripheral\app.trace，最后点击 Confirm 确认设置。

../../../_images/image29.png

Debug Analyzer 参数设置界面

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

    备注

    默认保存路径：Debug Analyzer.exe 同目录下的 DataFile 文件夹，如 Soc Log 保存路径 所示。

../../../_images/image30.png

Debug Analyzer 抓取 Log

../../../_images/image31.png

Soc Log 保存路径

备注

  • 确保 .trace 文件与当前 SoC 运行代码匹配。

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