跳转至

泰凌Zigbee/BLE双模SDK开发指南

概述

Telink Zigbee-BLE Concurrent SDK是基于Telink Zigbee SDK和BLE SDK开发的双模SDK，使Zigbee和BLE可以同时工作。

本文档针对双模SDK特有的特性进行说明，关于Zigbee和BLE的特性和接口可参考各自的详细文档。

设备类型

(1) Zigbee支持的设备类型

  • 路由器（Router: ZR）

  • 协调器（Coordinator：ZC）

  • 终端节点（End Device: ZED）

(2) BLE支持的设备类型

  • BLE Slave设备

  • BLE Master设备

  • BLE controller（TL321x和TL721x支持）

网络类型

Zigbee支持的网络类型：

  • Central网络：ZC组建，ZED、ZR加入

  • Distribute网络：ZR组建，ZED、ZR加入

硬件平台

Telink Zigbee-BLE Concurrent SDK支持多个硬件平台，如TLSR8258、TLSR921x、TL321x、TL721x等。

BLE支持的连接和数量

TLSR8258、TLSR921x的BLE是单连接平台，需要通过app_cfg.h文件以下配置来选择slave或master角色，会编译生成不同的固件：

##define    BLE_SLAVE_ROLE_ENABLE                       1
##define BLE_MASTER_ROLE_ENABLE                     0

TL321x、TL721x的BLE是多连接平台，可以在同一固件中支持slave和master角色，在app_cfg.h文件配置支持的数量：

##define ACL_CENTRAL_MAX_NUM                            0 
##define ACL_PERIPHR_MAX_NUM                            1

Flash分布说明

当前SDK所有平台默认都是1 MB flash配置。如果使用512 KB flash，要确保固件小于208 KB。

512 KB Flash分布

只支持ZED的设备，暂不支持软件bootloader方式。

硬件bootload方式的512 KB Flash空间分配

1 MB Flash分布

支持2种boot方式：硬件bootloader和软件bootloader方式。

硬件bootload方式的1M Flash空间分配

软件bootload方式的1M Flash空间分布

SDK框架

协议架构

Zigbee-BLE双模整体框架

Zigbee-BLE双模调度机制

利用时分复用的方式实现Zigbee/BLE的功能。

BLE通信采用的时间同步方式，而Zigbee采用的是异步通信方式，因为此特性，模式切换调度基于BLE的时序要求，以BLE任务优先处理，在BLE空闲状态下启动Zigbee模式，当BLE Sync时间到达时，要快速切回到BLE模式。

Zigbee-Ble双模时序图

对于低功耗模式，会将Zigbee协议栈状态注册到BLE协议栈里，BLE协议栈会根据Zigbee状态和自己的状态，决定是否进入低功耗以及进入哪种低功耗模式。当BLE处于Idle状态时，设备的低功耗由Zigbee协议栈管控。

TLSR8258和TLSR921x的BLE协议栈只支持进入suspend的休眠模式，TL321x和TL721x支持进入suspend或deepsleep retention模式。当BLE协议栈停止工作后，所有平台的Zigbee协议栈默认进入deepsleep retention休眠模式。

SDK目录架构

Telink Zigbee-Ble双模SDK框架是基于Telink Zigbee SDK的，可参考文档《AN-19052900-E_Telink Zigbee SDK Developer Manual.pdf》。

在Telink Zigbee SDK基础上，增加“\stack”放置Zigbee、BLE协议栈代码( “\stack\zigbee”, “\statck\ble”)

Zigbee-Ble双模代码目录

应用层目录

我们针对Zigbee的3种设备类型，提供3个app的demo。

  • common: 应用层公共代码目录

  • sampleGW：Zigbee网关和BLE应用例程（Zigbee设备类型为Coordinator）

  • sampleLight：Zigbee灯和BLE应用例程（Zigbee设备类型为Router）

  • sampleSwitch：Zigbee开关和BLE应用例程（Zigbee设备类型为ZED）

和Zigbee SDK不同的是，双模SDK的每个示例的main函数入口在各自示例代码下的concurrent_main.c文件中。

应用层目录

Common文件目录

common文件目录

所有平台的通用文件如下：

  • zigbee_ble_switch.c：Zigbee和BLE模式转换条件判断及转换

  • comm_cfg.h: 代码版本和模式配置

  • factory_reset.c/h：通过断电操作来进行设备复位

  • module_test.c：模块测试文件，仅供开发过程中测试验证使用

TL321x和TL721x BLE多连接平台特有的文件：

  • hci_transport：BLE controller的hci接口初始化和收发数据处理

  • device_manage.c/h：BLE连接设备管理

  • tlkapi_debug.c/h：调试信息打印

APP文件目录

3个例程目录下文件内容基本一致，我们以sampleGW为例说明。

sampleGW目录

  • app_ble2zigbee.c：用BLE数据配置Zigbee网络接口文件

  • app_cfg.h：应用配置文件

  • app_ui.c/h：按键和灯控制接口文件

  • board_xxxx.h：不同硬件平台配置文件

  • concurrent_main.c：app主程序入口，平台初始化

  • sampleGateway.c/h：Zigbee初始化和应用主处理函数文件

  • sampleGatewayEpCfg.c：GW应用支持的endpoint和cluster注册文件

  • sampleGatewayMultiBLE.c：多连接BLE配置和初始化文件（TL321x和TL721x支持）

  • sampleGatewayMultiBLEController：多连接BLE controller配置和初始化文件（TL321x和TL721x支持）

  • sampleGwBLESlave_8258：TLSR8258平台BLE slave角色配置和初始化文件

  • sampleGwBLESlave_b91：TLSR921x平台BLE slave角色配置和初始化文件

  • stack_cfg.h：Zigbee协议栈配置文件

  • version_cfg.h：Zigbee协议栈版本配置文件，主要用于Zigbee OTA升级版本判断

  • zb_appCb.c：Zigbee协议栈事件上报回调函数处理文件

  • zcl_sampleGatewayCb.c：Zigbee ZCL应用数据处理文件

应用配置

这里介绍下双模SDK特有的配置，通用配置：

(1) ZBHCI_BLE

用于配置BLE是否接收处理Zigbee HCI数据，可使GW通过BLE控制Zigbee节点。

(2) TLKAPI_DEBUG_ENABLE

用于配置是否打开调试打印，默认是GPIO模拟串口打印模式，可用宏DEBUG_INFO_TX_PIN来配置GPIO管脚。

(3) APP_SECURITY_ENABLE

适用于TLSR8258和TLSR921x的BLE单连接示例，使能后BLE连接过程中支持配对绑定。

(4) APP_DIRECT_ADV_ENABLE

适用于TLSR8258和TLSR921x的BLE单连接示例，使能后，如果支持APP_SECURITY_ENABLE，查询到有绑定设备后，会发送带绑定设备的定向广播。

(5) PM_ENABLE和BLE_APP_PM_ENABLE

用于配置设备是否支持进入低功耗模式。

(6) BLE_ACTIVE_BY_UI

按照默认配置，BLE工作一段时间后，完成配置功能，会使BLE协议栈停止工作，设备会进入deepsleep retention休眠模式。使能BLE_ACTIVE_BY_UI后，按键唤醒设备可使BLE重新工作。

BLE多连接示例特有配置：

(1) ACL_CENTRAL_MAX_NUM和ACL_PERIPHR_MAX_NUM

用于配置支持的slave和master是数量，可配置的最大值均为4。

(2) ACL_PERIPHR_SMP_ENABLE和ACL_CENTRAL_SMP_ENABLE

对于不同的角色，是否支持配对。

(3) BLE_OTA_SERVER_ENABLE

是否支持BLE自带的OTA流程，因为示例中OTA和BLE应用数据用的是同一个service，所以不能同时支持，如果要同时支持，用户可自行更改代码。

(4) PM_DEEPSLEEP_RETENTION_ENABLE

用于配置设备是否支持进入deepsleep retention休眠模式。

主要函数接口说明

初始化函数

(1) void drv_platform_init(void)

平台初始化，包括内存、系统clock、GPIO、随机数以及射频模块等的初始化。

(2) void os_init()

Zigbee协议栈中设计的buffer、队列的初始化。对于系统由Retention sleep唤醒时无需调用。

(3) void user_zb_init(bool isRetention)

Zigbee相关初始化，包括协议栈、zcl、应用端口、用户参数等的初始化。

(4) void ble_radio_init(void)

BLE射频模块初始化，默认为BLE 1M模式。

(5) void user_ble_init();

BLE相关初始化，包括协议栈、用户参数等的初始化。

主要任务函数

(1) void concurrent_mode_main_loop(void)

Zigbee/BLE模式调度主函数。

(2) void zb_task(void)

Zigbee相关任务处理函数。

(3) void blt_sdk_main_loop(void)

BLE相关任务处理函数。

双模切换函数

(1) void restore_zigbee_rf_context(unsigned char *rxBuf)

将射频基带重启，清除rf中断和中断buffer后，配置Zigbee射频相关参数。

(2) void restore_ble_rf_context(void)

将射频基带重启，清除rf中断和中断buffer后，配置BLE射频相关参数。

(3) void switch_to_zb_context(void)

由BLE模式切换到Zigbee模式，射频切到Zigbee模式。

(4) void switch_to_ble_context(void)

由Zigbee模式切换到BLE模式，射频切到BLE模式。

(5) APP_BLE_STATE_IDLE()

判断BLE是否处于IDLE状态，如果处于IDLE状态不需要切换到BLE模式。

(6) u32 get_ble_event_state(void)

获得当前BLE rf状态，

  • 1：表示BLE事件处理完成，进入inactive状态；

  • 0：表示BLE处于active状态。

(7) bool zb_rfTxDoing(void)

Zigbee是否处于发送状态，为了保证Zigbee stack发送状态机的完整性，当处于发送状态时，不能切换到BLE模式。

(8) int is_switch_to_ble(void)

根据BLE下一个事件时间，判断是否需要切回到BLE模式，预留的提前量为4 ms。

(9) switch_to_ble

用于sampleSwitch示例，当处于Zigbee模式，并且Zigbee事件已经处理结束，不用等到BLE下次事件，直接转到BLE模式，在BLE模式中控制设备进入低功耗模式。

(10) int is_switch_to_zigbee(void)

根据BLE下一个事件时间，判断是否允许切换到Zigbee模式，预留的提前量为4 ms。

(11) void ble_task_stop(void)

关闭BLE功能，应用层可以根据实际应用，关闭BLE功能。

(12) void ble_task_restart(void)

重新打开BLE功能，应用层可以根据实际应用，重新打开BLE功能。