跳转至

tl_matter SDK 快速入门

概述

关于本文档

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

适用范围

本文档适用于基于 Telink RISC-V SoC 平台进行 Matter 应用开发。有关支持的芯片型号、对应开发板、开发平台、工具链及 SDK 版本的详细信息，请参阅最新发布的《Release Notes》。

注意

  • 打开《Release Notes》 页面后，在左侧目录中选择与当前 SDK 版本对应的版本。

SDK 依赖关系说明

tl_matter SDK 基于 tl_zephyr SDK 构建。两者紧密关联，必须配套使用：

组件 作用 是否必需
tl_zephyr SDK 提供 Zephyr RTOS 内核、Telink HAL、BLE 协议栈、MCUBoot、OpenThread、West 工具和构建工具链 ✅
tl_matter SDK 提供 Matter 协议栈和 Telink 示例应用；通过 TELINK_ZEPHYR_BASE 使用 tl_zephyr SDK ✅

两者缺一不可 —— tl_matter SDK 无法脱离 tl_zephyr SDK 独立构建，而仅使用 tl_zephyr SDK 则不具备 Matter 协议支持能力。

版本配套说明：

每个 tl_matter SDK 发布版本均针对特定的 tl_zephyr SDK 版本进行了验证。使用不匹配的 tl_zephyr SDK 版本可能导致构建失败或运行时异常。请参阅《Release Notes》的 Updates/Dependencies 章节获取对应的版本配套信息。

开发流程

1. 准备硬件和软件

2. 搭建 tl_zephyr SDK 环境

3. 获取 tl_matter SDK 源码

4. 初始化编译环境

5. 编译并烧录 Matter 示例

6. 验证示例运行结果

开发准备

硬件准备

硬件 说明
PC Ubuntu 24.04 LTS （推荐）
开发板 请根据《Release Notes》，选择合适的开发板
烧录器 泰凌烧录器
USB 数据线 用于连接 PC 与烧录器
杜邦线 用于连接烧录器与开发板

软件准备

软件 说明
烧录工具 Telink BDT (Burning and Debugging Tool) for Linux，用于固件烧录和调试
工具链 riscv64-zephyr-elf，用于编译 Matter 固件
tl_zephyr SDK 提供底层驱动和系统支持
tl_matter SDK 用于开发符合 Matter 标准的智能家居设备

开发环境搭建

Telink Matter 示例使用 west build 进行构建，依赖 tl_zephyr SDK。

在配置 tl_matter 环境之前，请先参阅《Telink Zephyr SDK 快速入门》，完成 tl_zephyr SDK 开发环境的搭建、SDK 的获取，并编译其第一个应用程序以验证开发环境是否配置正确。

注意

  • 请确保拉取的 tl_zephyr SDK 分支与您计划使用的 tl_matter 版本匹配，否则后续编译可能失败。

完成 tl_zephyr SDK 环境配置与验证后，参考获取 tl_matter SDK 源码章节获取源码。

获取 tl_matter SDK 源码

安装 Matter 主机端依赖

sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \
  libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \
  python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev

获取并配置 tl_matter 仓库

mkdir -p ~/zephyrproject && cd ~/zephyrproject
git clone https://github.com/telink-semi/tl_matter.git connectedhomeip
cd connectedhomeip
git checkout <telink_matter_branch>     # e.g. dev-tlk_v1.5
./scripts/checkout_submodules.py --platform telink linux

初始化 Matter 编译环境

source scripts/bootstrap.sh

注意

  • 首次执行需要下载 pip/gn 等依赖，可能需要较长时间。

  • 如果后续切换 Commit 或分支，请先清理环境，然后重新运行 bootstrap：

    rm -rf .environment
source scripts/bootstrap.sh

编译与烧录第一个 Matter 示例

选择第一个 Matter 示例

在正式开发 Telink Matter 应用之前，建议首先编译并运行 Lighting App 示例，验证 tl_matter SDK 开发环境是否配置正确。

本文档以 TL3238X 芯片（EVK：C1T388A20_V1.1，默认配置：2 MB Flash）为例，演示第一个 Matter 示例的编译与运行。

注意

  • Telink Matter 示例位于 examples/<app-name>/telink/ 目录下。每个示例均使用 west build 进行编译，并基于 Zephyr 构建系统完成构建。
  • TL3238X 芯片提供多种配置，具体取决于 Flash 容量及是否启用 Matter + Zigbee 双模，详见附录2：TL3238X 编译配置。

激活 Matter 开发环境

cd connectedhomeip
source scripts/activate.sh

编译

cd examples/lighting-app/telink
west build -b tl3238x

默认情况下，编译完成后生成的固件位于：build/zephyr/zephyr.bin。

烧录

Telink 提供 BDT 软件用于固件烧录。请参考《Telink Zephyr SDK 快速入门》的烧录固件章节完成烧录。

验证运行结果

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

复位后，观察开发板上的板载 LED 状态。若 LED 按固定周期闪烁，表示固件已正常启动并运行。

Running Result

相关参考文档和资源

文档导航

文档 说明
Telink Matter 开发手册 tl_matter SDK 的软件架构、仓库结构及功能模块说明
Telink Zephyr SDK 快速入门 tl_zephyr SDK 环境搭建、编译及烧录说明

社区与资源

资源 说明
Telink 官方论坛 技术交流与支持
Telink 官方网站 产品中心及文档中心
Zephyr Project Zephyr 官方社区
Matter Project Matter 官方社区
GitHub SDK 源码仓库

附录1：常见问题

west build 报错：找不到目标开发板

原因：当前使用的分支可能未包含目标开发板的板级定义。Telink 开发板仅在 Telink Fork 仓库的对应分支中可用。

解决方案：

1. 查阅《Release Notes》的 Updates/Dependencies 章节，确认您计划使用的 tl_matter SDK 分支及与其配套的 tl_zephyr SDK 分支。

2. 检查当前 tl_zephyr SDK 分支：

cd ~/zephyrproject/zephyr
git remote -v                 # should include telink-semi/tl_zephyr
git branch --show-current

如果当前分支不正确，请切换到对应的分支：

git checkout <matched-branch-or-commit>     # switch if needed
west update

切换 tl_zephyr SDK 分支后，请参考《Telink Zephyr SDK 快速入门》中的获取 Telink HAL 章节，重新获取 HAL 文件。

3. 检查当前 tl_matter SDK 分支：

cd ~/zephyrproject/connectedhomeip
git branch --show-current

如果当前分支不正确，请切换到对应的分支，并重新配置 Matter 开发环境：

git checkout <matched-branch-or-commit>     # switch if needed
./scripts/checkout_submodules.py --platform telink linux
rm -rf .environment
source scripts/bootstrap.sh
source scripts/activate.sh

4. 完成上述检查和配置后，重新执行编译命令：

cd examples/lighting-app/telink
west build -b <your_board>

附录2：TL3238X 编译配置

TL3238X 支持多种编译配置，具体取决于 Flash 大小及是否需要双模（Matter + Zigbee）支持。主要配置组合如下：

配置 Flash OTA LZMA Matter + Zigbee 配置文件
默认配置 2 MB 否 否 否 boards/tl3238x.conf
OTA + BT DFU + LZMA 2 MB 是 是 否 boards/tl3238x_2m_flash_ota_lzma.conf
Dual-mode + OTA 4 MB 是 否 是 boards/tl3238x_4m_flash_dual_mode_ota.conf

注意

  • 对于 2 MB Flash + OTA 配置，必须启用 LZMA 压缩，否则固件无法放入可用的 Flash 空间。

示例：2 MB Flash with OTA + LZMA（software version 2）

west build -p -b tl3238x -d build_tl3238x_lzma_v2 -- \
  -DCONF_FILE="prj.conf boards/tl3238x_2m_flash_ota_lzma.conf" \
  -DCONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2

如果开发板使用的 Flash 容量不是默认的 2 MB，请在编译时指定 Flash 容量。例如，指定为 4 MB：

west build -b tl3238x -- -DFLASH_SIZE=4m

有关 TL3238X 及其他开发板的详细编译配置和编译命令，请参阅附录3：各开发板编译说明。

附录3：各开发板编译说明

各开发板均在 examples/<app>/telink/boards/ 目录下提供对应的 *_README.md 文件，其中提供该开发板各构建配置的详细构建命令，包括默认配置、OTA + LZMA、Matter + Zigbee 双模、4 MB Flash 以及 DFU/OTA 镜像的软件版本 2 配置等。

Lighting App

Light Switch App