跳转至

telink_zigbee_sdk Get Started

概述

关于本文档

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

适用范围

telink_zigbee_sdk 适用于泰凌微电子TL321x、TL323x、TLSR921x 等系列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)
SDK GitHub / Gitee

选择开发环境

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

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

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

udn7Mk6v.png

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

安装工具链

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

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

    vEgEbnIm.png

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

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

    N9gCnbBd.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 的开发。

请根据您的操作系统下载对应的安装包，后续演示将以 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。

IZahV996.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 的开发。

获取与导入 SDK

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

下载 SDK

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

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

SDK 目录概览

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

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

导入工程

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

在 VS Code 中导入工程

telink_zigbee_sdk 工程导入后，需要执行转换操作后，才可在 VS Code环境中使用。

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

  2. 点击左侧活动栏中的 Telink 图标，进入 Telink Extension 视图，点击 PROJECT OUTLINE后面的 Convert Telink Project 键。

    O40SL2Cz.png

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

    2cBEE6WJ.png

工程导入成功后，在 VS Code 中编译工程 。

WaMFr7ZL.png

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

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

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

    EjErQ5Zd.png

  3. 点击Browse，进入 build 文件夹选择相应的工程，点击 Finish，完成工程导入。

    CxL0wIF6.png

工程导入成功后，在 Telink IoT Studio 中编译工程。

编译和运行第一个示例

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

选择示例

建议使用官方提供的 sampleGW 作为第一个示例工程。该示例有 LED 指示，可以快速验证固件烧入和运行是否正常。

本示例选用 TL321x Dongle 开发板进行演示，如果您手上只有EVK开发板，请修改 app_cfg.h 中的开发板选择，参考如下。

#define BOARD                               BOARD_TL321X_EVK//BOARD_TL321X_DONGLE

更多示例请参考 ...\telink_zigbee_sdk\tl_zigbee_sdk\apps 。

编译工程

在 VS Code 中编译工程

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

    4ExBEltH.png

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

    NUA9U2l7.png

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

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

    oSgMUFHE.png

  1. 在左侧 Project Explorer 中选中要编译的工程。
  2. 点击顶部工具栏 Build 按钮（锤子图标）旁边的下拉小箭头。

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

    rxwRT6pN.png

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

    E9M5ZWB6.png

以 TL321x 平台的 sampleGW 为例，编译产生的 bin 文件存放在

...\telink_zigbee_sdk\tl_zigbee_sdk\build\iot_riscv_tl321x\sampleGW_tl321x 文件夹下，其中 ELF 格式的文件用于调试，BIN 格式的文件则用于烧录。

烧录程序

通过 BDT 工具（免安装烧录调试工具）进行固件烧录。

步骤一： 连接硬件

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

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

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

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

    1Y2j35ry.png

步骤二：安装 BDT

  1. 下载 BDT 工具。

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

    1Y2j35ry.png

  2. 解压缩工具包

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

    以 Windows 为例:

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

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

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

    Vesmhk52.png

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

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

    rdkap2aA.png

步骤三：烧录固件

  1. 连接设备

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

    E4ZOcE1h.png

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

  2. 配置与烧录步骤

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

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

    oswuryrb.png

    说明

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

    b. 选择下载模式为 EVK。

    FnEpFsFs.png

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

    p0XaXIMJ.png

    注意

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

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

    4xw8dcBz.png

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

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

    X3Wte0f8.png

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

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

    xgK8EHpg.png

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

    IxPpdbM3.png

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

    2jJy4a1A.png

验证运行结果

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

  1. 烧录完成后，开发板将自动复位重启，如果未自动复位，请按下开发板上的 Reset 按键进行复位。
  2. 观察开发板上的红色 LED 是否正常点亮。
  3. 长按开发板上的 SW1 按键 3 秒以上，观察绿色 LED 是否发生变化，灯亮代表 Zigbee 网络开启，灯灭代表 Zigbee 网络关闭。

  4. 如果条件允许，可以使用 ubiqua 或 wireshark 等专业的抓包工具，观察开发板在网络开启和关闭时是否有广播 Permit Join 命令。

    8vo5i2HU.png

其他参考资料

文档 说明
开发手册 详细的软件架构、仓库结构及功能模块说明

附录1：常见问题

环境安装失败

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

    解决办法：修改安装路径

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

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

编译失败

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

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

烧录失败

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

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

示例运行异常

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

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

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

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