跳转至

BLE/Zigbee/Thread 无线协同处理器示例工程快速入门指南

概述

本文档旨在帮助您快速完成基于 BLE/Zigbee/Thread（BZT）无线协同处理器（Radio Co-Processor，RCP）示例的固件烧录与功能验证。通过本文档，您能够熟悉 BZT 演示套件的配置，并通过该套件控制低功耗蓝牙（BLE）、Zigbee 以及 Matter over Thread 三种不同协议设备。

bzt_application_scenarios.png

硬件软件准备

硬件清单

硬件类型 型号/规格 数量 说明
PC Linux 电脑，Ubuntu 24.04 LTS 系统 1 台 用作开发主机，用于运行烧录软件。
开发板 TL322x 开发板 1 个 TL3228x 开发板，用于烧录 RCP 固件。
TL323x 开发板 1 个 TL3238x 开发板，作为 Matter 设备网络测试节点。
TL3238 Dongle 2 个 一个作为 Zigbee 设备网络测试节点；一个作为 BLE 设备网络测试节点。
泰凌烧录器 Programmer V5 1 台 用于将固件烧录至开发板。
连接线 USB Type-C 数据线 若干 连接 PC 与烧录器，提供烧录通道。
连接 PC 与开发板，用于供电及日志输出。
杜邦线 若干 连接烧录器与开发板的调试/烧录接口。

其中，开发板、Dongle 和烧录器可通过官方淘宝店铺购买，具体型号及价格请咨询在线客服。

Cwcza-XWnznDWBlS\.png

注意

请确保所有开发板在使用时均已安装对应的天线，保证无线通信功能正常。

软件与固件清单

软件类型 名称 说明
烧录工具 Telink BDT for Linux 用于将固件烧录至开发板的专用烧录及调试软件。
预编译固件 ot-zb-ble-rcp_322x_usb.bin RCP 固件，烧录至 TL3228x 开发板，集成了 OpenThread/Zigbee/BLE 协议栈。
sampleLight_tl323x.bin Zigbee 灯控固件，烧录至 TL3238 Dongle。
zigbee_ble_sampleGW_tl323x.bin BLE 固件，烧录至 TL3238 Dongle。
merged_lighting_tl323x_fd_1fd000.bin Matter 应用固件，烧录至 TL3238x 开发板。需配合 factory_data_1141_8005_0x1fd000/1141_8005 目录下的工厂数据一起使用。
应用固件烧录起始地址 0x0，工厂数据烧录起始地址 0x1fd000。
工厂数据 factory_data_1141_8005_0x1fd000 配合 Matter 应用固件一起烧录（和预编译固件一并提供）。

注意

预编译固件、工厂数据与用于控制Zigbee网关的 ZGC 工具的 Linux 版本压缩包，请点击下载获取。

安装 BDT

按照以下步骤完成 Linux 系统中 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 进行烧录。

烧录程序

通过 BDT 进行固件烧录。

连接硬件

两块开发板和两个 Dongle 分别烧录不同的固件，一次烧一块，烧完一块再烧另一块。

在烧录之前，请按照以下逻辑连接电脑、烧录器与开发板或 Dongle：

  • PC ↔ 烧录器（Programmer V5）：使用 USB Type-C 数据线连接。若烧录器上的绿色指示灯常亮，表明烧录器已被 PC 成功识别。
  • 烧录器 ↔ 目标板：使用杜邦线连接：
    • 电源线：VCC ↔ VCC；GND ↔ GND
    • 数据线（单线 SWM 总线）：将烧录器的 SWM 引脚连接至目标板的 SWS 引脚。

烧录固件

固件有两类，一类是 RCP 固件，另一类是节点设备固件，需要分别烧录到不同的开发板上。

固件名称 类别 对应目标板
ot-zb-ble-rcp_322x_usb.bin RCP 固件 TL3228x 开发板
sampleLight_tl323x.bin Zigbee 节点设备固件 TL3238 Dongle
zigbee_ble_sampleGW_tl323x.bin BLE 节点设备固件 TL3238 Dongle
merged_lighting_tl323x_fd_1fd000.bin Matter 节点设备固件 TL3238x 开发板

RCP 固件烧录

  1. 选择目标板的芯片型号和固件，目标板为 TL322x 开发板。 在左侧的芯片下拉菜单中，选择您开发板对应的目标芯片，例如 TL322x，随后选择待烧录的固件二进制文件 ot-zb-ble-rcp_322x_usb.bin。

    PPXWGkIVks-PXbIn\.png

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

    TXV1TvlaP5gwrPwk\.png

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

    -l-u-VStU4F9pNpg\.png

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

    a9wYa9K1qXbeTHSO\.png

节点设备固件烧录

BLE 设备烧录

目标板为 TL3238 Dongle，硬件连接方式参见连接硬件章节。选择开发板类型 TL323x，固件选择 zigbee_ble_sampleGW_tl323x.bin，烧录详细步骤参见 RCP 固件烧录章节。

Zigbee 设备烧录

目标板为 TL3238 Dongle，硬件连接方式参见连接硬件章节。选择开发板类型 TL323x，固件选择 sampleLight_tl323x.bin，烧录步骤参见 RCP 固件烧录章节。

Matter over Thread 设备烧录

目标板为 TL3238x 开发板，硬件连接方式参见连接硬件章节，选择开发板类型 TL323x。

FTDtyxfLG8k0wfD9\.png

Matter over Thread 设备需要烧录两个固件到目标板上，点击菜单栏 Open 边上的扩展按钮。

  1. 选择 merged_lighting_tl323x_fd_1fd000.bin，烧录地址为 flash 的 0 地址。
  2. 打开 factory_data_1141_8005_0x1fd000/1141_8005 目录，选择一个文件夹，找到 factory_data.bin，烧录地址为 flash 的 0x1fd000 地址。

两个固件都选好后点击 Download，BDT 会自动完成两个固件的烧录。

NqrnPDxrDo92-8ln\.png

验证示例运行结果

Host 环境配置

OTBR 服务安装

按照官方文档中的步骤，安装 OTBR（OpenThread Border Router）服务。安装完成后，按照下面步骤完成 OTBR 服务的配置和启动：

  1. 编辑配置文件，配置串口设备和波特率：

    sudo nano /etc/default/otbr-agent

    在配置文件中，找到以下行（如果不存在则创建）：

    OTBR_AGENT_OPTS=""

    将其修改为：

    OTBR_AGENT_OPTS="-I wpan0 -B enp3s0 spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=115200"

    注意

    /dev/ttyACM0 为设备名称，请根据您系统上的实际设备名称进行调整。

  2. 重启服务：

    sudo systemctl daemon-reload
sudo systemctl restart otbr-agent
sudo systemctl status otbr-agent

chip-tool 安装

CHIP 工具（chip-tool）是一款 Matter 控制器实现程序，安装过程十分简单，只需在终端中执行以下命令：

sudo snap install chip-tool

关于 chip-tool 的详细使用说明和更多资料，请参阅官方文档。

ZGC 工具安装

Zigbee Gateway Controller（ZGC）是一款用于控制 Zigbee 网关的工具，其 Linux 版本以压缩包 zgc_ble_controller_linux.tar.gz 与预编译固件一并提供。请按照以下步骤完成安装与初始配置：

  1. 解压 zgc_ble_controller_linux.tar.gz。

  2. 运行安装命令：

    sudo python3 zgc_tool.py

注意

如果是首次运行，需要安装额外的依赖项（bluez、python3）来完成配置：

sudo apt-get update
sudo apt-get install bluez python3 python3-pip libxcb-cursor0

安装 Python 模块：

pip3 install csv pyserial PySide6 pandas

Matter 设备入网与控制

本节介绍如何通过 OTBR 启动 Thread 网络，并使用 chip-tool 完成 Matter 设备的配网与控制。

OTBR 启动

  1. 启动 host，用 USB Type-C 数据线将 RCP 设备（TL3228x 开发板）和 host 连接，请确保数据线插入 TL3228x 开发板右上方的 USB 端口。

  2. 在终端中执行以下命令，检查系统是否正确识别到 RCP 的两路串口。正常情况下，输出应包含两个 ttyACM 端口：

    ls /dev/tty*

  3. 执行以下命令，确认 RCP 与 host 的连接正常。若返回结果不包含 "Connection refused"，则表示连接成功：

    sudo ot-ctl state

    若返回结果包含 "Connection refused"，请参考常见问题：RCP 无法与 host 通信章节。

  4. 依次执行以下命令，配置并启动 Thread 网络。每条命令执行后应返回 Done：

    sudo ot-ctl dataset set active 0e08000000000000000000030000144a0300000b35060004001fffe0020811111111222244440708fddead00beef00000510ffeeddccbbaa9988776655443322110003037365640102058b0410567138be961fa4dbf260cbbd420b39f00c0402a0f7f8
sudo ot-ctl ifconfig up
sudo ot-ctl thread start

  5. 等待片刻后，执行以下命令查看网关角色。若返回 leader，则表示网络已正常启动：

    sudo ot-ctl state

  6. 查询 OTBR 当前信道，在 shell 中输入以下命令。返回值应为 20。后续 Zigbee 网络配置也需要使用相同的信道。

    sudo ot-ctl channel

    OTBR 支持通过命令行控制，详细命令请参阅 OpenThread CLI 官方文档。使用时，需在命令前加 sudo ot-ctl 前缀。

Matter 设备入网与控制

在 Thread 网络正常运行后，按以下步骤完成 Matter 设备的入网与控制。

  1. 上电 Matter 子设备（TL3238x 开发板），使其进入待配网状态。

  2. 使用 chip-tool 将设备加入网络。在终端中执行以下命令：

    chip-tool pairing ble-thread 1 hex:0e08000000000000000000030000144a0300000b35060004001fffe0020811111111222244440708fddead00beef00000510ffeeddccbbaa9988776655443322110003037365640102058b0410567138be961fa4dbf260cbbd420b39f00c0402a0f7f8 ${PIN_CODE} ${DISCRIMINATOR}

    参数说明：

    • ${PIN_CODE} 和 ${DISCRIMINATOR} 为变量，需替换为实际值。实际值可在固件目录 Firmware\factory_data_1141_8005_0x1fd000\1141_8005\ 中找到。进入烧录 factory_data.bin 所在的文件夹，查看 summary.json 文件，其中 passcode 对应 ${PIN_CODE}，discriminator 对应 ${DISCRIMINATOR}。

    ksRZc3zZBQRtjLoc\.png

  3. 设备成功入网后，可通过 chip-tool 控制 Matter 设备。执行以下命令后，应能观察到 TL3238x 开发板上的红、蓝、绿三色 LED 亮起或熄灭：

    chip-tool onoff toggle 1 1

    We9PixR01i-fSJ4H\.png

Zigbee 设备入网与控制

本节介绍如何使用 ZGC 工具启动 Zigbee，并完成 Zigbee 子设备（TL3238 Dongle）的入网与控制操作。

  1. 在 host 中打开一个新的命令行终端，执行以下命令进入 ZGC 工具所在目录并启动程序： 
    cd bzt/tool/zgc_ble_controller_linux/
python3 zgc_tool.py
  2. 程序启动后，桌面上将弹出 ZGC 图形界面。请按以下步骤进行配置：
    • 端口选择：选择编号较大的 ttyACM 端口
    • 波特率：设置为 115200
    • 功能勾选：
      • 勾选左下角的 "bleHci" 选项
      • 勾选左侧的 "scroll to bottom" 选项
    • 连接：点击 "Open" 按钮完成串口连接。

  3. 在 ZGC 工具界面中，点击 "BDB" 选项卡。必须将 Zigbee 网络通道设置为与 Matter 网络相同的通道（例如通道 20），以确保无线通信兼容。

    Xc1GO.png

  4. 点击 "start network"，ZGC 将启动 Zigbee 网络。启动成功后，RCP（TL3228x 开发板）设备上的绿色 LED 指示灯会亮起，表示网络已正常运行。

    KK-W7jhpaAZlBpHl.png

  5. 为 Zigbee 子设备通电。等待片刻后，子设备上的绿色 LED 指示灯会亮起，表示已成功加入 Zigbee 网络。

  6. 在 ZGC 界面中，选择 "nodesMGMT" 选项卡，然后点击 "get joined nodes"。界面将列出当前网络中所有已入网的设备节点。从中选择一个目标设备，然后点击 "on"/"off" 按钮，即可控制该 Zigbee 子设备上蓝色 LED 指示灯的亮灭。

    2jALFUT5nrlVOeX-\.png

BLE 设备连接

本节介绍如何使用 ZGC 工具通过低功耗蓝牙（BLE）连接 BLE 子设备（TL3238 Dongle）。

  1. 在 host 中打开一个新的命令行终端，执行以下命令进入 ZGC 工具所在目录并启动程序： 
    cd bzt/tool/zgc_ble_controller_linux/
python3 zgc_tool.py

  2. 程序启动后，桌面上将弹出 ZGC 图形界面。请按以下步骤进行配置：

    • 端口选择：选择编号较大的 ttyACM 端口
    • 功能勾选：
      • 勾选左下角的 "bleHci" 选项
      • 勾选左侧的 "scroll to bottom" 选项
    • 连接：点击 "Open" 按钮完成串口连接。

    bLZnTN73EkwxDtzV\.png

  3. 为 BLE 子设备通电，使其进入可被发现状态。

  4. 在 ZGC 界面右侧选择 "bleHci" 选项卡。在 "scan para set" 后面的输入框中分别输入 0x0123 和 0x0064，然后点击 "scan para set" 完成参数配置。

    注意

    请确保先完成步骤 3（设备上电），再执行本步骤的参数设置，以保证设备可被正常扫描到。

  5. 点击 "start scan" 开始扫描。接收界面将显示大量 HCI 命令日志。等待约 10 秒后，点击 "stop scan" 结束扫描。

    FiUy014EA6hkyI\.png

  6. 在扫描结果中，找到名为 "BZT-DEMO1" 的设备并选中，然后点击 "connect" 按钮。连接成功后，界面将显示 "BLE connected"。如果连接失败，请重新选择设备并多次尝试连接，参考常见问题：BZT Demo 无法连接 BLE 设备章节。

常见问题

RCP 无法与 host 通信

现象描述：OTBR 启动时，输入 OTBR 控制命令后返回 "Connection refused" 报错。

解决方法：

  1. 重启 RCP。
  2. 在 shell 界面输入命令，检查是否有两个 ttyACMx 节点被枚举。 
    ls /dev/tty*
  3. 打开 otbr-agent 配置文件，检查 spinel 端口号是否为较小的那个 ttyACMx 节点，更新为实际的节点。 
    sudo nano /etc/default/otbr-agent
OTBR_AGENT_OPTS="-I wpan0 -B enp3s0 spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=115200"
  4. 重启 OTBR 服务。 
    sudo systemctl daemon-reload
sudo systemctl restart otbr-agent
sudo systemctl status otbr-agent

BZT Demo 无法连接 BLE 设备

现象描述：ZGC 工具无法扫描到 BLE 设备的广播，导致无法连接 BLE 设备。

解决方法：

  1. 重启 BLE 子设备。
  2. 确认 scan 参数设置正确，重新点击 start scan，等待 10 秒，然后点击 stop scan，等待右边刷新 BLE 设备列表。
  3. 选中 "BZT-DEMO1" 设备连接。

社区与资源

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