跳转至

telink_rf4ce_sdk 快速入门

概述

关于本文档

本文档旨在帮助您快速完成 telink_rf4ce_sdk 开发环境的搭建、SDK 获取、工程的编译与烧录，并成功运行第一个示例工程。阅读本文档，需要您具备 C 语言基础、嵌入式开发基本概念。

适用范围

telink_rf4ce_sdk 适用于泰凌微电子 TLSR825x、TLSR827x、TLSR952x、TL321x 等系列的芯片（SoC）。

注意

此处列出的芯片信息可能不是最新版本。关于完整、准确的芯片型号、对应的开发板、开发平台、工具链版本以及 SDK 版本的详细信息，请参阅最新的 Release Notes。

开发准备

硬件准备

硬件 说明
PC Windows 10/11 / Linux / macOS
（本文档以 Windows 为例说明）
开发板 根据 Release Notes，选取合适的开发板
烧录器 推荐使用 Programmer V3
USB 数据线 连接 PC 和烧录器
杜邦线 连接开发板和烧录器

本文档选用 TL321x Dongle 和 TL321x RC（遥控器，Remote Control）定制开发板为例说明。其中，TL321x Dongle 可通过官方淘宝店铺购买，详情请咨询在线客服；TL321x RC 定制开发板面向特定应用场景，如有意向，欢迎联系我们咨询。

开发板实物图如下：

PlYj.png

软件准备

软件 说明
IDE Telink VS Code Extension
烧录调试工具 Burning and Debugging Tool (BDT)
上位机工具 RF4CE_KeySim3.0
SDK GitHub / Gitee

注意

RF4CE_KeySim 上位机工具随 SDK 一同发布，存放于 telink_rf4ce_sdk\Tools 目录中。

安装开发环境

安装 VS Code

在安装插件之前，请确保您的电脑上已安装最新版本的 Visual Studio Code。Telink VS Code Extension 随 VS Code 的最新版本同步更新。若 VS Code 版本过低，可能会导致插件无法正常工作或功能异常。

  1. 启动 VS Code。
  2. 点击左侧活动栏的 Extensions（扩展）图标，或使用快捷键 Ctrl+Shift+X。
  3. 在搜索框中输入 “Telink”。

  4. 在搜索结果中找到 Telink Development Tool，点击 Install。

    nVvCZsirpo6tPE9z.png

安装完成后，在 VS Code 左侧活动栏中将显示 Telink DEVELOPMENT 图标。

安装工具链

在 Telink VS Code Extension 中，通过插件内置的管理器按需下载编译器工具链和辅助工具。

  1. 在 VS Code 左侧的 Telink DEVELOPMENT 视图中，展开 DEVELOPMENT TOOLS 树状菜单。

    q20g.png

  2. 单击需要的工具链，点击右侧 Install Toolchain。

  3. 安装成功后，VS Code 窗口右下角会弹出对应的完成通知。

    vtgJdO35bNvJWLh4.png

说明：如果要在命令行环境中使用工具链，右键单击，在弹出的菜单中点击 Open Terminal 。

安装辅助工具

在工具列表中选中 CMake，右键单击，在弹出的菜单中点击 Install。

环境验证

完成安装后，请按照以下步骤验证 Telink VS Code Extension 是否安装成功：

  1. 启动 VS Code，确认软件能够正常打开，且启动过程中没有报错信息。
  2. 在左侧活动栏中确认出现 Telink 图标，点击该图标进入 Telink DEVELOPMENT 视图。
  3. 在 DEVELOPMENT TOOLS 树状菜单中，确认已安装的工具链右侧显示 Installed 状态。
  4. 同时确认辅助工具 CMake 右侧也显示已经安装。

如果以上检查均正常，则说明 Telink VS Code Extension 及其依赖工具已成功安装并配置完成，即可下载 SDK 并开始开发。

获取与导入 SDK

本章介绍如何获取 Telink 官方 SDK、了解 SDK 的顶层目录结构，以及如何将 SDK 工程导入至 IDE 中。

下载 SDK

通过 GitHub 或者 Gitee 下载最新版 SDK，或执行以下 git clone 命令，将仓库克隆至本地：

git clone https://github.com/telink-semi/telink_rf4ce_sdk.git

或

git clone https://gitee.com/telink-semi/telink_rf4ce_sdk.git

SDK 目录概览

telink_rf4ce_sdk 顶层主要目录如下：

目录 说明
build/ 工程编译目录
net/ 协议栈
platform/ 芯片平台驱动
proj/ 通用函数、驱动适配层
tools/ 脚本工具
vendor/ 示例工程

在 VS Code 中导入工程

  1. 点击 VS Code 菜单栏的 File -> Open Folder...，选择该工程的根目录加载即可。

  2. 点击左侧活动栏中的 Telink 图标，进入 Telink Extension 视图，点击 PROJECT OUTLINE 旁边的 Convert Telink Project 按钮。

    cxYYXTT-fiU0wuRe.png

  3. 在搜索栏中选择您需要的芯片型号，转换为 Telink VS Code Extension 工程。

    PHzSdClWPxYpPNKq.png

工程导入成功后，您会看到：

52yDlCt7wZ4XMrFq.png

编译并运行第一个示例

本章将引导您完成从选择示例、代码编译，到最终烧录并运行的完整开发闭环。

选择示例

建议使用官方提供的 zrc2_dongle_tl321x 和zrc2_rc_tl321x 作为第一组示例工程：

这两个工程的配套测试方法如下：

  • zrc2_dongle_tl321x（Dongle 端）：将此工程编译后生成的固件zrc2_dongle_tl321x.bin 烧录至 Dongle 开发板。该板通过 USB 连接电脑后会被识别为一个 COM 口。通过该串口可快速验证固件烧录与基础运行状态。在此测试中，它模拟的是电视或机顶盒设备。
  • zrc2_rc_tl321x（RC 端）：将此工程编译后生成的固件 zrc2_rc_tl321x.bin 烧录至 RC 开发板，作为遥控器设备。

更多示例请参考 ...\telink_rf4ce_sdk\tl_rf4ce_sdk\vendor。

编译工程

  1. 在 VS Code 左侧侧边栏中找到 PROJECT OUTLINE，选择需编译的工程及其对应的 Target。

  2. 点击右侧的编译按钮进行编译。

    YJAZVilb0Lqhgdr-.png

    编译完成后，在 ...\telink_rf4ce_sdk\tl_rf4ce_sdk\cmake_builds\tl_rf4ce_sdk_tl321x\TL32_ELF_MCULIB_V5_GCC12_2 文件夹下输出文件（.elf、.bin、.ls），其中 elf 格式的文件用于调试，bin 格式的文件则用于烧录。 编译成功，看到类似的输出：

    7I9KOIlIoJ1wTfEk.png

测试时，将上述工程编译生成的固件zrc2_dongle_tl321x.bin和 zrc2_rc_tl321x.bin烧录到对应的 Dongle 开发板与 RC 开发板，即可验证完整的遥控功能。

烧录固件

通过 BDT 工具进行固件烧录。RC 开发板与 Dongle 开发板按相同方式连接硬件后分别烧录（一次烧一块，依次进行）。

步骤一：连接硬件

在使用 BDT 工具前，请按以下方式连接电脑、烧录器与开发板：

  • PC ↔ 烧录器：使用 USB 数据线连接。若烧录器上的绿色指示灯常亮，表明烧录器已被 PC 成功识别。

  • 烧录器 ↔ 开发板：使用杜邦线连接：

    • 电源线：VCC ↔ VCC；GND ↔ GND
    • 数据线（单线 SWM 总线）：将烧录器的 SWM 引脚连接至开发板的 SWS (Swire) 引脚。

    4d5B1.png

注意

RC 开发板的烧录线需要从开发板背面接线引出。

步骤二：安装 BDT

Telink 烧录调试工具 (Telink Burning and Debugging Tool，简称 BDT) 用于将编译生成的固件烧录至目标芯片或开发板中。

  1. 下载 BDT 工具。

    访问 Telink 开发者中心 - 开发工具，根据您的操作系统下载对应的工具包。

    wDb6b1QoQ6PxojHW.png

  2. 解压缩工具包（BDT 工具为绿色免安装版，解压即可使用）。

    以 Windows 为例：

    • 将下载的工具包解压到自定义的路径，例如 C:\Telink\BDT。
    • 进入解压后的发布目录，例如 C:\Telink\BDT\release_v5.9.4。
    • 双击运行 Telink BDT.exe 即可启动该工具。

    50wHeshRRlmgdvEA.png

  3. 选择烧录器版本与芯片兼容性。

    BDT 支持多个版本的烧录器，需根据所使用的芯片型号选择对应版本。本文档对应的 TL321x 开发板使用 Programmer V3：

    ul69Ys2GVSPhPsdO.png

步骤三：烧录

  1. 连接设备

    打开 BDT 软件。固件烧录前必须确保工具已检测到烧录器，如下图所示。

    BIChCq2aCh-IhgMN.png

    • 如果 BDT 没有找到设备，点击 Device -> Refresh 查看可用设备。

    • 如果 BDT 发现多个设备，所有设备都会列出。点击 Refresh 后默认激活第一个设备，您也可以在列表中手动切换目标设备。

  2. 配置与烧录步骤

    1. 选择开发板的芯片型号。在顶部的芯片下拉菜单中，选择您开发板对应的目标芯片，例如 TL321x。

      ct4aG9I-kMobJcmo.png

    2. 选择下载模式为 EVK。

      XUCBY1NmDSidJy2i.png

    3. 点击 Setting 按钮打开配置窗口，切换到 FLASH 选项卡。在 Download Addr 栏中设定固件的起始偏移地址，默认值 0x000000。

      G9ZDIakPx-9kaz1D.png

    4. 点击菜单栏 File -> Open/Reopen，选中您编译生成的 .bin 固件。加载成功后，主界面底部会显示完整文件路径。

    5. 检查开发板和 PC 之间的连接状态。

      • 如果连接状态正常，主界面的左下方会显示 evk device: ok。
      • 如果主界面的左下方显示 usb device: not found，表示开发板没有正确连接到电脑上。

    6. 先点击 Active，再点击 Unlock 按钮或勾选 auto unlock 选项，解除 flash 的写保护状态。

      如果 flash 处于写保护状态，则 Download 会失败，所以在烧录固件到 flash 之前，需要确保 flash 处于可编程状态。

      B-QoBueAPBItKhTj.png

    7. 点击 Download 按钮，等待日志窗口提示烧录成功。

    8. 您可以在烧录前将复位模式设为 auto mode，或在烧录后切换到 manual mode 并点击 Reset 按钮手动复位 MCU 运行程序。

      WBoFGHnHGJ6oU2mm.png

验证运行结果

固件烧录完成后，请按照以下步骤验证示例程序是否已在开发板上正常运行。

烧录完成后，重新连接硬件用于验证：

  1. Dongle 开发板直接插到 PC 上的任意 USB 口。
  2. RC 开发板：仅需使用烧录器（或任意 3.3V 供电）保持上电即可，无需连接 PC。

整体验证连接效果如下：

2NAvXpFcAczHNhUa.jpg

配合上位机工具，完成示例工程功能测试：

  1. Dongle 开发板 USB 口插到电脑后，打开上位机工具（RF4CE_KeySim3.0(64bit).exe），在 Setting 下选择 Dongle 对应的 COM 口，点击 确定。

    O2Gbnt5r9pERICVr.png

  2. 点击 Start Test 按钮，状态按钮变为绿色，表示开始测试。

    mDCgvFFgBc6KL1Qd.png

  3. 长按 RC 开发板上的 SW5 按键超过 5 秒，RC 开发板上的指示灯开始闪烁，设备进入配对模式。

  4. 上位机界面上会跳出 3 个数字，请在 RC 开发板上尽快依次输入这 3 个数字，RC 开发板上的指示灯会快闪 3 次，指示配对过程完成。

    2Fz08v9XdsNew4Ez.png

    按照 SDK TL321x 的默认配置，RC 开发板按键值如下：

    L0Ep2l-7PwpAr42I.png

    键值配置文件为：...\tl_rf4ce_sdk\vendor\rc_app\board_telink_rc_tl321x.h

  5. 配对成功后，按 RC 开发板上的按钮，上位机会显示按键效果，如下：

    P3-eVjCkiQlUa2yp.png

社区与资源

资源 说明
Telink 官方论坛 技术交流与支持
Telink 官方网站 产品中心
Telink 文档网站 文档中心

附录1：常见问题

环境安装失败

  • 可能原因：安装路径包含中文字符，导致安装程序无法正确识别路径。

    解决办法：修改安装路径。

  • 可能原因：安装时电脑上运行的杀毒软件拦截了安装程序的必要操作。

    解决办法：在安装前，请暂时关闭所有正在运行的杀毒软件或安全防护软件。

编译失败

  • 可能原因：修改头文件后未清理工程。

    解决办法：编译前先清理工程。

  • 可能原因：编译失败并提示 boot.link 文件不存在，说明脚本文件的换行符格式为 CRLF。

    解决办法：将脚本文件的换行符格式保存为 LF。

烧录失败

  • 可能原因：开发板尚未被激活（Activate）或未进行解锁（Unlock）操作，芯片处于保护状态，无法接收烧录指令。

    解决办法：在 Download 之前，先点击 Activate 激活芯片，出现 Activate MCU ok 之后，再进行 Download 操作进行烧录。

示例运行异常

  • 可能原因：当前烧录的固件与所使用的开发板硬件型号不匹配。

    解决办法：请在工程配置中确认目标芯片型号，修改为正确配置后，重新编译、烧录并运行程序。

  • 可能原因：开发板的 flash 存储器中残留了之前烧录的其他程序数据。

    解决办法：在烧录新固件之前，先执行擦除（Erase）操作，清空 flash 中的旧数据，然后再烧录新的固件文件。