跳转至

tl_platform_sdk Get Started

概述

关于本文档

本文档旨在帮助您快速完成 tl_platform_sdk 开发环境的搭建、SDK 获取、工程的编译与烧录，并成功运行第一个示例项目。

适用范围

tl_platform_sdk 适用于泰凌微电子 TL322x、TL323x、TL721x 、TLSR921x、TLSR951x、TLSR922x、TLSR952x 等系列 SoC。

注意

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

开发准备

硬件准备

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

硬件实物，请参考章节连接硬件。

软件准备

软件 说明
IDE Telink VS Code Extension 或 Telink IoT Studio
工具链 工具链信息，请参阅 Release Notes
烧录工具 BDT (Burning and Debugging Tool) 或 JTAG
SDK Gitee仓库 或 GitHub 仓库

选择开发环境

tl_ble_sdk 支持以下两种开发方式：

根据您的开发习惯选择其中一种即可。两种方式无需同时安装。

您可以根据开发习惯，选择使用 VS Code 插件 或 Telink IoT Studio 集成开发环境。

安装 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。

    7GrSXX4k.png

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

安装工具链

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

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

    f9tSCPvm.png

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

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

    JTXdW39c.png

说明

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

安装辅助工具

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

环境验证

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

  1. 启动 VS Code，确认软件能够正常打开，且启动过程中没有报错信息。

  2. 在左侧活动栏中确认出现 Telink 图标，点击该图标进入 Telink DEVELOPMENT 视图。

  3. 在 DEVELOPMENT TOOLS 树状菜单中，确认需要的工具链已经安装。

  4. 同时确认辅助工具 CMake、Jtag_burn 和 ICEman 右侧也显示已经安装。

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

请根据您的操作系统下载对应的安装包，后续演示将以 Windows 为例：

Telink IoT Studio 的安装步骤：

Windows 环境：

  1. 解压下载的 .zip 压缩包，运行 TelinkIoTStudio_V2025.2.exe，按照向导完成安装。

  2. 安装完成后，必须运行 TelinkIoTStudio Updater.exe 以获取最新的组件更新。

Linux 环境：

  1. 针对运行环境赋予安装包执行权限。

  2. 运行 Telink_IoT_Studio_2025.2_Installer.run 并按照终端提示完成安装。

工具链说明

Telink IoT Studio 提供了一站式的独立安装包，内置了开发所需的所有组件，无需进行额外的工具链安装。所有必需的工具链和辅助工具均在安装 IDE 时已经同步安装。通过点击顶部菜单栏的 Telink，打开对应工具链的 Cygwin Shell。

JTXdW39c.png

环境验证

安装完成后，请按照以下步骤验证 Telink IoT Studio 是否安装成功。

验证 IDE 安装：

  1. 启动 Telink IoT Studio，确认程序能够正常加载并显示主界面，且启动过程中没有出现缺失依赖库等错误提示。

  2. 点击顶部菜单栏 Telink，确认下拉菜单中的 Cygwin Shell 等工具链入口可正常打开。

满足以上条件，说明 Telink IoT Studio 已安装并配置成功。

验证基础依赖：

SDK 的编译和版本管理依赖以下工具，请在系统终端执行相应命令进行验证。

依赖项 验证命令 预期版本
Python python --version 或 python3 --version Python 3.8 或更高（建议 3.8～3.12）
Git git --version Git 2.30 或更高

确认以上依赖均已正确安装后，即可开始 SDK 开发。

获取与导入 SDK

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

下载 SDK

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

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

SDK 目录概览

目录 说明
3rd-party/ 第三方组件
chip/ 芯片相关代码
common/ 通用工具函数
demo/ 示例工程
doc/ 官方文档
project/ 工程文件
tools/ 开发工具
CMakeLists.txt/ 总编译入口

完整目录结构及各目录职责请参考开发手册。

导入工程

根据您的开发环境，选择 VS Code 导入工程或者 Telink IoT Studio 导入工程。

在 VS Code 中导入工程

tl_platform_sdk 为标准的 Telink VS Code Extension 工程，直接点击 VS Code 菜单栏的 File -> Open Folder...，选择该工程的根目录加载即可。

工程加载后，点击左侧活动栏中的 Telink 图标，进入 Telink Extension 视图。此时 PROJECT OUTLINE 面板显示当前工程的目录结构，表示工程已成功导入。

5dqUOF3a.png

工程加载后，若 PROJECT OUTLINE 面板为空，则说明当前工程仍为旧版 Telink IoT Studio 工程，需要执行转换操作。

xccMKJzt.jpg

转换成功右下角显示结果：

utSmwibi.png

若您选择使用 Telink IoT Studio 作为主开发环境，请按照以下步骤导入工程：

  1. 点击顶部菜单栏 File -> import。

  2. 在弹出的对话框中展开 General 目录，选择 Existing Projects into Workspace ，点击 Next。

  3. 选择工程目录导入。

导入工程

  1. 选择 Browse已经下载好的工程,选择相应芯片平台的工程，点击 Finish，一个工程导入成功。

选择相应芯片平台

工程导入成功后如下图所示：

导入成功

编译并运行第一个示例

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

选择示例

建议使用官方提供的 debug _demo 作为第一个示例工程。该示例代码逻辑精简、依赖少，不涉及复杂的无线协议栈。本示例选用 TL322X: C1T371A20 EVK 进行演示。

更多示例请参考 ...\tl_platform_sdk\demo\vendor。

编译工程

根据您的开发环境，选择 VS Code 编译工程或者 Telink IoT Studio 编译工程。

在 VS Code 中编译工程

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

    WGt2B9uP.png

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

    编译完成后，输出文件（.elf、.bin、.ls），其中 ELF 格式的文件用于调试，BIN 格式的文件则用于烧录。

    ELF文件和BIN文件可以在编译后在 PROJECT OUTLINE下找到，以 TL322x 平台的Debug_Demo为例，编译产生的 .elf、.bin、.ls文件存放在 ...\tl_platform_sdk\cmake_builds\TL_PLATFORM_SDK_322X\TL32_ELF_MCULIB_V5F_GCC12_2目录下

    编译成功，看到类似的输出：

    6hVtRMb5.png

  1. 在左侧 Project Explorer 中选中要编译的工程。

  2. 点击顶部工具栏 Build 按钮（锤子图标）旁边的下拉小箭头。

  3. 在下拉菜单中选中您要编译的配置（Configuration），系统即开始编译。

    uqGqJMHe.png

  4. 观察控制台（Console）输出，若无报错信息并显示 Build Finished，则表示编译成功。

    d2G8yXKY.png

以 TL322x 平台的 debug _dem 为例，编译产生的 bin 文件存放在 ...\tl_platform_sdk\project\tlsr_riscv\tl322x\Debug_Demo目录下。

烧录程序

Telink 支持通过 BDT 工具（免安装烧录调试工具）或 JTAG（配合 ICEman 仿真服务） 进行固件烧录。请根据您的硬件环境选择。

通过 BDT 烧录固件

步骤一： 连接硬件

在使用 BDT 工具前，请按照以下逻辑连接电脑、烧录器与目标板：

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

  • 烧录器 (Programmer) ↔ 目标板：使用杜邦线连接：

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

    Ucgyu1rL.png

步骤二：安装 BDT

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

  1. 下载 BDT 工具。

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

    xk1QAQBS.png

  2. 解压缩工具包

    BDT 工具为绿色免安装版，解压即可使用。

    以 Windows 为例:

    a. 将下载的工具包解压到自定义的路径，例如 C:\Telink\BDT。

    b. 进入解压后的发布目录，例如 C:\Telink\BDT\release_v5.9.2 。

    c. 双击运行 Telink BDT.exe 即可启动该工具。

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

    Telink 提供了四个版本的烧录器（Programmer）。在启动 BDT 界面时，推荐选择 Programmer V1.0 \~ V3.0 的烧录器版本。

    Y4KMxDY8.png

步骤三：烧录固件

  1. 连接设备。

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

    WaejXcGR.png

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

  2. 配置与烧录步骤。

    a. 选择目标板的芯片型号。

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

    Jh00TQOw.png

    说明：

    • B91: 指代TLSR921x、TLSR951x系列芯片；
    • B92: 指代TLSR922x、TLSR952x系列芯片。

    b. 选择下载模式为 EVK。

    V250Mf3A.png

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

    注意： 您可以通过配置 SRAM 或 OTP 选项，将目标固件下载到 SRAM 或 OTP 的目标区域。

    cZ8lVP6n.png

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

    7CMmMDyG.png

    UjT9cAbo.png

    e. 检查目标板和PC之间的连接状态。

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

    umGTdMVZ.png

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

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

    Ed61nSIp.png

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

    joeZ9BWh.png

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

    xZmr9Ajp.png

通过 JTAG 烧录固件

JTAG 烧录需要依赖后端服务进程 ICEman。

在 VS Code 中通过 JTAG 烧录固件

  1. 项目成功编译后，在工程目录树中找到生成的 .bin 固件文件。点击文件右侧的 JTAG 烧录 图标，即可弹出 Telink JTAG Burn With ICEman 页面。

    TY9JLcL4.png

  2. Telink JTAG Burn With ICEman 页面中，配置路径与参数：

    • 填入 ICEman 和 Jtag_Burn 的本地可执行文件路径。
    • 配置正确的目标芯片型号以及烧录起始地址。
    • 配置 ICEman 的通信接口类型与对应端口号。

    6i8x1pWQ.png

    ZJ6ldmP8.png

  3. 点击 Start ICEman 按钮。系统会提示选择连接启动模式：

    • Default 模式：JTAG 为默认的四线连接方式（推荐使用模式）。
    • SDP 2-wire 模式：ICEman 启动时添加 -I aice_sdp.cfg，JTAG 使用两线的连接方式，需要确保硬件支持。
    • H 模式：ICEman 启动时添加 -H 选项，在连接成功后，立即对目标芯片执行复位并挂起（Reset-and-hold）操作。

    THCyUWcC.png

  4. 观察日志，当出现 ICEman is ready to use 时，表示连接成功。配置好 Jtag_Burn 执行时的参数后点击 Burn 按钮开始传输，通过后续滚动日志确认烧录结果。

    PUTF9HfA.png

    MNuMarFb.png

    0yBW948S.png

在 Telink IoT STudio 中通过 JTAG 烧录固件

  1. 点击顶部菜单栏的 Telink -> Jtag Burn (SPI Burn)，调出 JTAG 配置页面。

    CnNS3ztG.png

  2. 在弹出的页面中，检查预备烧录的 .bin 固件是否正确。

  3. 为 Jtag_Burn 配置运行参数，如下图标注，然后点击 Start ICEman。

  4. 当看到控制台输出 ICEman is ready to use 后，表明硬件后台连接成功。此时点击右侧的 Burn 按钮，即可开始固件烧录。

    5j2Q1fKZ.png

4.4 验证运行结果

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

操作步骤

  1. 烧录完成后，开发板将自动复位；如果未自动复位，请按下开发板上的 Reset 按键进行复位。

  2. 观察开发板上 LED 指示灯的状态。

预期结果

如果程序运行正常，则说明固件已成功下载并启动。

以 TL322x 开发板为例，成功运行时的现象如下：

  • 蓝灯、红灯、绿灯和白灯同时闪烁。

如果观察到上述现象，则说明开发环境配置、程序编译、固件下载及运行均已验证成功。您已完成第一个示例程序的运行。

Validate

下一步

我想…… 阅读文档
学习 SDK 功能 开发手册

附录1： 常见问题

环境安装失败

  • 从 VScode Telink Development 拓展的DEVELOPMENT TOOLS安装 ICEMan 环境以及其他开发工具时，安装过程失败。
  • 解决办法：请改用离线安装方式。下载并参照以下文档完成安装：离线安装包

编译失败

  • 使用 VS Code 编译例程 Demo 时，编译失败。
  • 解决办法：检查工程路径是否包含中文字符（如中文文件夹名、中文用户名等）。

烧录失败

  • 使用 Jtag 烧录时，提示错误信息 “Burning failed due to target errors”
  • 解决办法：检查 JTAG 接线是否正确，特别注意 VTREF 引脚必须连接到目标板的 JTAG I/O 电源（即参考电压）。
  • 使用 BDT 烧录时，提示错误信息 “DUT command execute error”
  • 解决办法：在 Download 之前，先点击 Activate 激活芯片，出现 “Activate MCU ok” 之后，再进行 Download 操作进行烧录。