【泰凌微实战 - 06】泰凌微 ZigBee 开发实战全指南（2026 最新版）

泰凌微是国内 ZigBee 芯片的主流供应商，其 TLSR8/TLSR9/TL 系列芯片凭借高集成度、低功耗、低成本和完整的 ZigBee 3.0 认证，广泛应用于智能家居、工业物联网等领域。本指南从环境搭建到实战项目，带你快速掌握泰凌微 ZigBee 开发核心技能。

一、前期准备：硬件与软件

1.1 核心硬件清单

1.2 软件环境搭建（Windows 推荐）

1. 下载安装 Telink IoT Studio（一站式 IDE，支持 TC32 和 RISC-V 平台）

   • 官网下载：https://www.telink-semi.cn/development-tools
   • 重要：必须安装在C 盘根目录，且以管理员身份运行，否则会出现 Java 环境找不到的错误
   • TLSR9 系列芯片需要在泰凌开发者论坛注册获取免费激活证书

2. 下载最新 ZigBee SDK

   • 官方 Gitee：https://gitee.com/telink-semi/telink_zigbee_sdk（最新版本 V3.7.1.4）
   • 双模 SDK：https://gitee.com/telink-semi/telink_zigbee_ble_concurrent_sdk（支持 ZigBee+BLE 并发）

3. 导入 SDK 工程

   • 打开 Telink IoT Studio，依次点击File -> Import -> Existing Projects into Workspace
   • 选择 SDK 解压后的build/tlsr_tc32（TLSR8 系列）或build/tlsr_riscv（TLSR9 系列）目录
   • 勾选 "Copy projects into workspace"，点击 "Finish" 完成导入

二、ZigBee 核心概念（泰凌微实现）

ZigBee 是一种低功耗、短距离、自组织的 Mesh 网络协议，泰凌微 SDK 完全遵循 ZigBee 3.0 标准。

2.1 网络设备类型

• 协调器（Coordinator）：网络的创建者和管理者，每个网络只能有一个协调器，负责分配网络地址和管理密钥
• 路由器（Router）：扩展网络覆盖范围，转发其他设备的数据，不能休眠
• 终端设备（End Device）：只能通过父节点（协调器或路由器）通信，支持低功耗休眠模式

2.2 关键通信概念

• 节点（Node）：一个物理设备，具有唯一的 64 位 MAC 地址，入网后获得 16 位网络短地址
• 端点（Endpoint）：应用层的服务入口，一个节点最多支持 240 个用户端点（1-240），端点 0 用于 ZDO 设备管理
• 簇（Cluster）：一组相关功能的集合，分为输入簇（接收命令）和输出簇（发送命令）。例如：
  • 0x0006：开关簇（On/Off）
  • 0x0402：温度测量簇
  • 0x0405：湿度测量簇
• 属性（Attribute）：簇中的数据项，例如开关簇的 On/Off 属性（0x0000）

三、实战项目 1：Hello World（LED 开关控制）

这是最基础的 ZigBee 项目，实现协调器控制终端设备的 LED 亮灭。

3.1 工程选择与配置

1. 在导入的 SDK 工程中，找到以下两个示例：

   • sampleGW_8258：协调器工程
   • sampleLight_8258：终端设备（灯）工程

2. 关键配置（在app_cfg.h中修改）：

   // 设备类型配置 #define ZB_COORDINATOR 0 // 0: 终端设备 1: 协调器 #define ZB_ROUTER 0 // 0: 非路由器 1: 路由器 // 网络参数配置 #define ZB_CHANNEL_MASK 0x07FFF800 // 支持所有11-26信道 #define ZB_PAN_ID 0x1234 // 网络PAN ID

3.2 核心代码解析

终端设备（灯）端：

// 注册开关簇的属性回调函数 zb_zcl_register_attr_cb(ZCL_CLUSTER_GEN_ON_OFF, ZCL_ATTR_ON_OFF, on_off_attr_cb); // 开关属性变化回调函数 void on_off_attr_cb(zb_uint8_t endpoint, zb_uint16_t cluster_id, zb_uint16_t attr_id, zb_uint8_t *value) { if (attr_id == ZCL_ATTR_ON_OFF) { if (*value) { gpio_set_output_en(LED_PIN, 1); // 点亮LED } else { gpio_set_output_en(LED_PIN, 0); // 熄灭LED } } }

协调器端：

// 向指定设备发送开关命令 void send_on_off_command(zb_uint16_t short_addr, zb_uint8_t endpoint, zb_bool_t on_off) { zb_zcl_on_off_send_on_off_req(short_addr, endpoint, on_off); } // 按键处理函数 void key_handler(zb_uint8_t key_id, zb_uint8_t key_state) { if (key_id == KEY1 && key_state == KEY_PRESSED) { static zb_bool_t led_state = ZB_FALSE; led_state = !led_state; send_on_off_command(0x0001, 1, led_state); // 向短地址0x0001的设备发送命令 } }

3.3 编译与测试

1. 分别编译协调器和终端设备工程，生成.bin文件
2. 使用 BDT 工具将固件分别烧录到两个开发板
3. 先上电协调器，等待其创建网络（约 3 秒）
4. 打开协调器的入网允许（默认 180 秒），然后上电终端设备
5. 终端设备入网成功后，按下协调器的 KEY1 按键，即可控制终端设备的 LED 亮灭

四、实战项目 2：温湿度传感器数据采集

实现终端设备采集 DHT11 温湿度数据，并通过 ZigBee 网络上报给协调器。

4.1 硬件连接

将 DHT11 传感器连接到终端设备开发板的 GPIO 引脚（例如 PB0）：

• VCC → 3.3V
• GND → GND
• DATA → PB0

4.2 核心代码实现

终端设备端：

// 定义温湿度属性 zb_uint8_t temperature = 0; zb_uint8_t humidity = 0; // 注册温度和湿度测量簇 zb_zcl_register_cluster(1, ZCL_CLUSTER_MS_TEMPERATURE_MEASUREMENT, ZB_ZCL_CLUSTER_SERVER_ROLE); zb_zcl_register_cluster(1, ZCL_CLUSTER_MS_RELATIVE_HUMIDITY, ZB_ZCL_CLUSTER_SERVER_ROLE); // 周期性采集温湿度数据并上报 void temperature_humidity_report(void) { dht11_read(&temperature, &humidity); // 读取DHT11数据 // 上报温度属性 zb_zcl_report_attr(1, ZCL_CLUSTER_MS_TEMPERATURE_MEASUREMENT, ZCL_ATTR_TEMPERATURE_MEASUREMENT_VALUE, &temperature); // 上报湿度属性 zb_zcl_report_attr(1, ZCL_CLUSTER_MS_RELATIVE_HUMIDITY, ZCL_ATTR_RELATIVE_HUMIDITY_VALUE, &humidity); } // 在主循环中每5秒调用一次 zb_os_timer_register(temperature_humidity_report, 5000, ZB_OS_TIMER_REPEAT);

协调器端：

c

运行

// 注册属性上报回调函数 zb_zcl_register_report_cb(temperature_humidity_report_cb); // 温湿度数据上报回调函数 void temperature_humidity_report_cb(zb_uint16_t short_addr, zb_uint8_t endpoint, zb_uint16_t cluster_id, zb_uint16_t attr_id, zb_uint8_t *value) { if (cluster_id == ZCL_CLUSTER_MS_TEMPERATURE_MEASUREMENT && attr_id == ZCL_ATTR_TEMPERATURE_MEASUREMENT_VALUE) { printf("收到设备0x%04X的温度数据：%d℃\n", short_addr, *value); } else if (cluster_id == ZCL_CLUSTER_MS_RELATIVE_HUMIDITY && attr_id == ZCL_ATTR_RELATIVE_HUMIDITY_VALUE) { printf("收到设备0x%04X的湿度数据：%d%%\n", short_addr, *value); } }

五、常见问题与调试技巧

5.1 烧录失败

• 检查烧录线连接是否正确，确保 SWM 和 GND 引脚连接良好
• 降低 Swire 同步速度（在 BDT 工具中设置）
• 确保目标板供电稳定（3.0-3.6V），且未处于低功耗模式
• 尝试先擦除整个 FLASH，再重新烧录固件

5.2 设备无法入网

1. 硬件检查：确认天线焊接良好，供电稳定（大功率发射时压降不超过 0.2V）
2. 网络检查：确保协调器已创建网络，且入网允许已打开
3. 参数检查：确认协调器和终端设备的 PAN ID、信道、密钥一致
4. 信号检查：确保设备之间的距离不超过 10 米，且无明显遮挡（RSSI > -85dBm）
5. 日志分析：开启协议栈调试日志，查看入网过程中的错误信息

5.3 通信不稳定

• 避免在 2.4GHz 频段干扰严重的环境中使用（如 WiFi 路由器附近）
• 增加路由器节点，扩展网络覆盖范围
• 控制单帧数据长度不超过 100 字节，超过时手动分片
• 为数据帧添加 CRC 校验，丢弃校验失败的帧

六、进阶内容

6.1 OTA 空中升级

泰凌微 SDK 提供了完整的 ZigBee OTA 升级解决方案，支持批量设备升级：

1. 使用 SDK 自带的zigbee_ota_tool工具生成带 OTA 头的固件镜像（.ota 格式）
2. 将 OTA 镜像存储在协调器的 FLASH 中
3. 终端设备周期性查询 OTA 服务器，发现新版本后自动下载并升级
4. 支持双 Bank 交替存储，升级失败时自动回滚到原固件

6.2 低功耗优化

对于电池供电的终端设备，可通过以下方式降低功耗：

• 启用休眠模式，设置合适的休眠周期
• 关闭不必要的外设（如 UART、PWM 等）
• 降低射频发射功率
• 减少数据上报频率

6.3 与主流智能家居平台对接

泰凌微 ZigBee 设备可轻松对接以下平台：

• 小米米家
• 华为鸿蒙智联
• 天猫精灵
• Apple HomeKit（需通过 HomeBridge）

七、官方资源与社区

• 泰凌微电子官网：https://www.telink-semi.cn
• 官方文档中心：https://doc.telink-semi.cn
• 开发者论坛：https://forum.telink-semi.cn
• Gitee 代码仓库：https://gitee.com/telink-semi

下篇预告： 【泰凌微实战 - 07】泰凌微SDK 私有Mesh实现差分升级（OTA）完整实操方案

原创不易，如果本文对你有帮助，欢迎点赞、收藏、关注三连！有任何问题都可以在评论区留言，我会及时回复。