跳转至

Telink Zephyr SDK Get Started

概述

关于本文档

本文档旨在帮助您快速完成在 Ubuntu 操作系统上 Telink Zephyr SDK 开发环境的搭建、SDK 获取、示例工程编译、固件烧录并成功运行第一个 Zephyr 示例应用。

本文档适用于首次使用 Telink Zephyr SDK 的开发者。

通过本文档，您可以完成：

  1. 安装 Zephyr 开发环境；
  2. 获取 Telink Zephyr SDK；
  3. 安装编译工具链；
  4. 配置开发环境；
  5. 编译示例工程；
  6. 验证开发环境是否正常。

完成本文档后，开发者可以继续基于 Telink Zephyr SDK 进行 Bluetooth® LE、Thread、Matter 等无线物联网应用开发。

适用范围

本文档适用于基于 Telink Zephyr SDK 开发的 Telink RISC-V SoC 平台，对应 Zephyr Getting Started Guide 的Telink 定制版本，请重点关注 Telink 分支仓库、Telink 硬件抽象层二进制固件获取步骤以及 RISC-V 工具链的选择。

关于完整、准确的芯片型号、对应的开发板、开发平台、工具链以及 SDK 版本的详细信息，请参阅最新发布的 Release Notes。打开 Release Notes 页面后，通过左侧下拉列表，选择与您当前使用的 SDK 版本对应的 Release Notes 查看。

开发准备

硬件准备

硬件 说明
PC Linux distro as Ubuntu 24.04 LTS （推荐）
开发板 请根据 Release Notes，选择合适的开发板
烧录器 Telink Programmer V5
USB 数据线 用于连接 PC 与烧录器
杜邦线 用于连接烧录器与开发板

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

软件准备

软件 说明
烧录工具 Telink BDT for Linux (Burning and Debugging Tool)
编译工具链 riscv64-zephyr-elf
SDK Telink Zephyr SDK

开发环境搭建

本章以 Ubuntu 24.04 LTS 为例介绍 Telink Zephyr SDK 开发环境搭建流程。

注意

对于其他 Linux 发行版，请根据系统类型参考 Install Linux Host Dependencies 安装所需的软件依赖。

APT 更新与升级

打开 Terminal，更新系统。

sudo apt update
sudo apt upgrade

安装开发工具

安装 Zephyr 编译环境需要的 CMake、Python、Device Tree Compiler 等工具。

  1. 安装 Kitware APT 软件源，以获取满足 Zephyr 要求的最新 CMake 版本。然后安装开发环境所需的依赖组件。

    wget https://apt.kitware.com/kitware-archive.sh
sudo bash kitware-archive.sh

  2. 安装 Zephyr 所需依赖。

    sudo apt install --no-install-recommends git cmake ninja-build gperf ccache dfu-util device-tree-compiler python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev

    注意

    AArch64（ARM64）系统无法提供 gcc-multilib 和 g++-multilib 软件包，若您使用 ARM64 架构的 Linux 主机，请从依赖安装列表中移除这两个软件包。

  3. 验证各个依赖项的版本。

    python3 --version
cmake --version
dtc --version

    推荐版本：

    Python >= 3.6
cmake version >= 3.20.0
dtc version >= 1.4.6

安装 West

West 是 Zephyr 官方提供的多仓库工程管理工具，按照下面步骤安装 West：

  1. 创建 Python 虚拟环境：

    python3 -m venv ~/zephyrproject/.venv

  2. 激活虚拟环境：

    source ~/zephyrproject/.venv/bin/activate

    虚拟环境激活后，命令行提示符前方会出现(venv) 标识。

    注意

    每次启动新的终端会话，必须先激活虚拟环境。若未激活，系统将找不到 west 等命令，或导致命令会在其他 Python 环境中运行，进而出现错误。

  3. 安装 West：

    pip3 install west

Telink Zephyr SDK 基于 Zephyr Project 构建， 它是 zephyrproject-rtos/zephyr 仓库的一个分支版本，托管在 telink-semi/zephyr，并针对 Telink RISC-V SoC 平台进行了适配和扩展，存放于 release-v1.0-v4.1-branch 分支。

完整获取流程如下：

初始化 Telink Zephyr SDK
        ↓
获取 Telink HAL
        ↓
安装 Zephyr SDK 工具链
        ↓
配置 Zephyr SDK 环境变量

  1. 使用 Zephyr Manifest 初始化 West 工作区。该操作会创建 ~/zephyrproject 工作空间，并使用 Zephyr 主仓库作为 Manifest 仓库。

    west init ~/zephyrproject
cd ~/zephyrproject
west update

    注意

    在中国大陆运行 west init 和 west update 获取 Zephyr 源码可能需要额外的时间，并且某些项目可能无法从国外服务器更新成功。请使用镜像源或代理，或者单独下载源码包。

  2. 导出 Zephyr CMake 包，同时允许应用工程调用 Zephyr 构建系统。

    west zephyr-export

  3. 安装 Zephyr 的 Python 依赖项 。

    pip3 install -r ~/zephyrproject/zephyr/scripts/requirements.txt

  4. 切换至 Telink Zephyr SDK 分支，以获取 Telink 平台适配代码。

    cd ~/zephyrproject/zephyr
git remote add telink https://github.com/telink-semi/zephyr
git fetch telink
git checkout release-v1.0-v4.1-branch
cd ..
west update

Telink Hardware Abstraction Layer (HAL) 以二进制文件包的形式提供 BLE 协议栈支持，并根据芯片类型选择 HAL 获取方式。

HAL版本 支持芯片 获取方式
hal_v1 TLSR9518ADK80D、TLSR9528A、TL321X、TLSR9118 执行命令：
west blobs fetch hal_telink
每当切换分支或更新 workspace 时，都需要重新运行该代码。
hal_v2 TL322X、TL323X、TL721X 进入目录：cd ~/zephyrproject/modules/hal/telink/hal_v2
执行： chmod +x fetch_sdk.sh
运行：./fetch_sdk.sh

注意

  • fetch_sdk.sh 使用了默认的仓库（ telink-semi/tl_ble_sdk_zephyr ），以及最新的提交记录。如果您想要固定某个特定的仓库或提交记录，可以将它们作为参数传递：
  • ./fetch_sdk.sh https://github.com/telink-semi/tl_ble_sdk_zephyr.git f50d422d780efb73af93b650ef7b8c6bf5a0b99b

切换分支或提交

如果您已经完成了上述设置，并且想要切换到另一个 Telink 分支或进行提交操作，请运行以下命令：

cd ~/zephyrproject/zephyr
git fetch telink
git checkout <your-target-branch-or-commit>
cd ..
west update

分支切换后，按照上述获取 Telink HAL 中的步骤，选择与您的芯片相匹配的版本，重新获取 HAL 文件。

安装 Zephyr SDK 工具链

Telink Zephyr SDK 选用 riscv64-zephyr-elf 工具链。

  1. 下载 Zephyr SDK v0.17.0 最小归档文件：

    wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.17.0/zephyr-sdk-0.17.0_linux-x86_64_minimal.tar.xz

  2. 验证下载：

    wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.17.0/sha256.sum | shasum --check --ignore-missing

  3. 解压归档文件到目标路径（例如 ~/zephyr-sdk-0.17.0）：

    tar xvf zephyr-sdk-0.17.0_linux-x86_64_minimal.tar.xz ~/zephyr-sdk-0.17.0

    注意

    • SDK 可以安装在以下推荐的任何路径中：
      • $HOME/zephyr-sdk[-x.y.z]
      • $HOME/.local/zephyr-sdk[-x.y.z]
      • $HOME/.local/opt/zephyr-sdk[-x.y.z]
      • $HOME/bin/zephyr-sdk[-x.y.z]
      • /opt/zephyr-sdk[-x.y.z]
      • /usr/zephyr-sdk[-x.y.z]
      • /usr/local/zephyr-sdk[-x.y.z]
    • [-x.y.z] 是下载的 SDK 版本，例如 -0.17.0。

    警告

    • 安装后请勿移动 SDK 文件夹。

  4. 安装工具链：

    cd zephyr-sdk-0.17.0
./setup.sh -t riscv64-zephyr-elf -h -c

注意

如果您需要完整的 Zephyr SDK（包含 QEMU 和 OpenOCD 等主机工具），请将最小归档文件替换为完整归档文件：

wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.17.0/zephyr-sdk-0.17.0_linux-x86_64.tar.xz
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.17.0/sha256.sum | shasum --check --ignore-missing
tar xvf zephyr-sdk-0.17.0_linux-x86_64.tar.xz ~/zephyr-sdk-0.17.0
cd zephyr-sdk-0.17.0
./setup.sh -t riscv64-zephyr-elf -h -c

配置 Zephyr 环境变量

将 Zephyr 环境脚本添加到 ~/.bashrc，以便 west build 在每个新终端中都能找到工作空间。

echo "source ~/zephyrproject/zephyr/zephyr-env.sh" >> ~/.bashrc
source ~/.bashrc

警告

如果跳过此步骤，稍后可能会遇到 west build 错误。

编译与烧录第一个应用程序

在正式开发 Telink Zephyr 应用之前，建议首先编译并运行 Blinky 示例，验证 Telink Zephyr SDK 开发环境是否配置正确。本示例选用TL323x EVK。

编译第一个应用程序

  1. 进入 Zephyr 根目录：cd ~/zephyrproject/zephyr

  2. 编译 Blinky 示例：

    west build -p auto -b tl3238x samples/basic/blinky -d build_blinky

  3. 查看编译结果。

    编译成功后，您将在 build_blinky/zephyr/ 文件夹中找到 zephyr.bin。

烧录固件

使用 BDT 工具进行固件烧录。BDT 是 Telink SoC 的官方烧录器。它适用于 Windows 和 Linux。本文档以 Linux BDT 为例。

步骤一： 连接硬件

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

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

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

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

    aZTlqS9R.png

步骤二：下载 BDT

  1. 安装 BDT 所需的依赖。

    sudo apt update
sudo apt install -y libgtk-3-dev libusb-1.0-0-dev

  2. 创建 BDT 工具目录。

    mkdir -p ~/tools/telink-bdt

  3. 将 Telink BDT for Linux 下载到 ~/Downloads 目录，并解压 BDT_Linux.zip 软件包。

    cd ~/Downloads
unzip BDT_Linux.zip -d ~/tools/telink-bdt/

    解压后的 BDT_Linux 目录包含两个工具包：TGui-BDT 和 Telink-BDT

  4. 解压 TGui-BDT。

    cd ~/tools/telink-bdt/BDT_Linux/
tar -xzf TGui-BDT-Linux-V1.0.2.tar.gz -C ~/tools/telink-bdt/

  5. 启动 TGui-BDT 。

    cd ~/tools/telink-bdt/TGui-BDT-Linux-V1.0.2/
sudo ./TGui

启动后即可使用 TGui-BDT 对 TL323X 开发板进行烧录。

步骤三：烧录固件

  1. 选择目标板的芯片型号和固件。

    在左侧的芯片下拉菜单中，选择您开发板对应的目标芯片，例如 TL323x ， 随后选择待烧录的固件二进制文件，例如 build_blinky/zephyr/zephyr.bin。

    AmwfOYy7.png

  2. 擦除 flash 。擦除大小设置为 2040 KB，随后执行 flash 擦除操作。对于具有 2 MB 外部闪存的开发板，最后 8 KB 保留给 SoC 数据，因此最大可擦除区域为 2040 KB。

    a96Yy6TU.png

  3. 验证 SWS、解锁 flash 并下载固件。先点击 SWS，确认与目标设备通信正常。点击 Unlock 以解除闪存保护，随后点击 Download，将所选固件烧录至设备。

    WEmjLd6j.png

  4. 复位开发板。烧录完成后，重新给开发板上电（或按下其 Reset 按钮）以启动新固件。

    VgmT7AJU.png

验证运行结果

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

操作步骤

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

  2. Blinky 示例程序会控制开发板上的 LED 进行电平翻转。观察开发板上的板载 LED 状态，确认 LED 是否按照固定周期闪烁。

    8pG61VAV.png

预期结果

程序正常运行时，您将观察到开发板上的板载 LED 按固定周期闪烁（默认频率约为 1 Hz，每秒亮灭一次）。

相关参考文档和资源

文档导航

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

社区与资源

资源 说明
Telink 官方论坛 技术交流与支持
Telink 官方网站 产品中心及文档中心
Zephyr Project Zephyr 官方社区
Zephyr Project Documentation Zephyr 技术文档
Zephyr 示例工程 Zephyr 示例程序说明
API Reference API 查询
GitHub SDK 源码仓库
Contribution Guide 开发者提交 Issue、贡献代码及开发规范

附录1：常见问题

芯片状态显示 Not Activate

  • BDT 连接芯片时提示：

    Not Activate

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

Blinky 示例运行后 LED 不闪烁

  • 固件烧录完成并复位开发板后，板载 LED 未按照预期闪烁。
  • 请检查以下内容：
    • 确认固件是否成功烧录；
    • 确认开发板供电正常；
    • 检查开发板 Jumper 配置是否正确；
    • 确认当前工程配置与开发板型号匹配