3.1 简单描述符
Z-Stack 3.0 中利用简单描述符来描述一个设备的某一方面的服务,这种服务也可以称为功能或者应用等。例如,ZigBee温湿度传感器具备温湿度监测的服务,可以利用简单描述来描述这个温湿度监测服务的具体内容。
结构分析
简单描述符本质上就是一个结构体,它在Z-Stack 3.0 中的定义是这样的:
typedef struct{
uint8 EndPoint;//端点号
uint16 AppProfId;//描述所在应用场景,例如家居自动化
uint16 AppDeviceId;//设备ID
uint8 AppDevVer:4;//由开发者自定义,表示版本号
uint8 Reserved:4;//保留字段
uint8 AppNumInClusters;//端点支持的输入簇个数
cId_t *pAppInClusterList;//指向输入簇列表的指针
uint8 AppNumOutClusters;//端点支持的输出簇个数
cId_t *pAppOutClusterList;//指向输出簇列表的指针
}SimpleDescriptionFormat_t;
下面简单讲解一下各个元素的意义。
- 端点号:EndPoint,可以理解为简单描述符的编号,取值范围是0~255。在同一个ZigBee设备中,每一个简单描述符都有一个不同的端点号,可以利用端点号来找到对应的简单描述符。
- AppProfId:Profile ID,表示这个简单描述符所属的应用场景。这个应用场景可以是家居自动化、智能照明和智慧零售等。ZigBee联盟为不同的场景定义了对应的ID值,称为Profile ID。
- AppDeviceId:Device ID,表示这个简单描述符所属的设备类型。这个设备类型可以是插座、灯或者传感器等。类似地,ZigBee联盟为不同类型的设备定义了对应的ID值,称为Device ID。
- AppDevVer:这个值可以由开发者自定义,用来表示版本号。
- Reserved:保留字段,暂时可以忽略。
- Cluster:簇,或者集群,可以划分为输入簇(In Cluseter)和输出簇(Out Cluster),用来描述这个服务的具体内容。一个简单描述符中可以包含多个Cluster,这些Cluster共同描述了这个服务的具体内容,后续章节将会详细讲解。
应用示例
刚才讲解了简单描述的定义,那么接下来就是为设备创建一个简单描述符。设备的简单描述符在zcl_samplesw_data.c文件中创建,这个文件所在的位置如图所示。
可以在这个文件中找到设备所包含的简单描述符,代码如下:
SimpleDescriptionFormat_t zclSampleSw_SimpleDesc =
{
SAMPLESW_ENDPOINT, // int Endpoint;
ZCL_HA_PROFILE_ID, // uint16 AppProfId[2];
ZCL_HA_DEVICEID_ON_OFF_LIGHT_SWITCH,// uint16 AppDeviceId[2];
SAMPLESW_DEVICE_VERSION, // int AppDevVer:4;
SAMPLESW_FLAGS, // int AppFlags:4;
ZCLSAMPLESW_MAX_INCLUSTERS, // byte AppNumInClusters;
(cId_t *)zclSampleSw_InClusterList, // byte *pAppInClusterList;
ZCLSAMPLESW_MAX_OUTCLUSTERS, // byte AppNumInClusters;
(cId_t *)zclSampleSw_OutClusterList // byte *pAppInClusterList;
};
详细地讲一下各个元素的含义。
SAMPLESW_ENDPOINT是在zcl_samplesw.h文件中定义的端点号,定义如下:
#define SAMPLESW_ENDPOINT 8
ZCL_HA_PROFILE_ID是由ZigBee联盟定义的,表示智能家居领域的Profile ID。
- ZCL_HA_DEVICEID_ON_OFF_LIGHT_SWITCH是一个设备类型ID,表示这是一个智能插座,它的值是由ZigBee联盟定义的。不同的公司在开发这个类型的智能插座的时候,必须要使用这个设备类型ID,这是互联互通的基础。
SAMPLESW_DEVICE_VERSION是在zcl_samplesw_data.c文件中定义的版本号,定义如下:
#define SAMPLESW_DEVICE_VERSION 1
SAMPLESW_FLAGS是在zcl_samplesw_data.c文件中定义的保留字段,可以暂时忽略,定义如下:
#define SAMPLESW_FLAGS 0
ZCLSAMPLESW_MAX_INCLUSTERS是在zcl_samplesw_data.c文件中定义的,表示支持的最大输入簇数量。
- (cId_t *)zclSampleSw_InClusterList表示输入簇列表。
- ZCLSAMPLESW_MAX_OUTCLUSTERS是在zcl_samplesw_data.c文件中定义的,表示支持的最大输出簇数量。
- (cId_t *)zclSampleSw_OutClusterList表示输出簇列表。
3.2 通信原理
AF的全称是Application Framework,中文意思是应用框架,AF层也就是应用框架层,它在ZigBee协议层次中位置如图所示。
开发者可以基于这个层次编写代码,实现ZigBee设备之间的数据通信。
AF层的通信原理
网络地址
前述章节已讲解过网络地址了,处于网络中的ZigBee设备都会被分配一个网络地址,用于标识设备所处的位置。通过这个网络地址就可以找到对应的设备了。
端点号
读者已经知道ZigBee 3.0是利用简单描述符来描述特定的服务的,并且设备上的每个简单描述符都配有一个唯一的端点号。实际上,ZigBee 3.0通信最终是发送到设备的特定的服务的,也就是端点号,举个例子说明其中的原理。
假设现在ZigBee网络中有一个协调器和一个智能插座终端,这个智能插座的网络地址为0x0EF1,并且配有一个简单描述符描述这个插座具备的一些功能,这个简单描述符的端点号是8。
如果协调器要向这个插座发送一个打开指令,不能简单地使用网络地址0x0EF1来说明把命令发送给这个插座,还需要利用端点号8来说明把命令发送给端点号8对应的服务。
如果读者了解过远程服务器的端口号,那么会发现它们之间其实是类似的,例如这个网址http://www.sxf-iot.com:80中,既包含了域名,也包含一个80端口号。
端点号的分类
端点号的取值范围是0~255,其中:
- 端点号0被分配给了ZDO(ZigBee Device Object)。
- 端点号255是广播,也就是向这个端点号发送数据时,设备的所有服务(简单描述符)都会收到这个数据。
- 端点号241~254是暂时保留起来的端点号,暂时不能使用。
- 剩下的端点号1~240可以供开发者自由地使用,例如读者一直学习的SampleSwitch这个工程所使用的端点号可以在工程中找到,如图所示。
通信方式
ZigBee支持3种通信方式,分别是点对点、广播和组播。
- 点对点通信(P2P,Peer to Peer):顾名思义,就是两个设备之间一对一通信。
- 广播:给其他的所有设备发送数据。
- 组播:给一部分的设备发送数据,这里的“一部分”说的就是一个特定的组。
注册简单描述符
在使用AF通信前,需要先注册简单描述符并且让对应的端点号生效,或者说让这个简单描述符对应的服务生效。这个流程是:
(1)创建一个简单描述符。在讲解简单描述符的章节中,我们已经看到相关的定义了。
(2)注册这个简单描述符。打开配套的工程,在zcl_samplesw.c文件中的zclSampleSw_Init()这个函数中可以找到以下代码,如图所示。
在应用层初始化函数zclSampleSw_Init()中,有两种注册简单描述符的方法:
(1)可以调用bdb_RegisterSimpleDescriptor()来在BDB中注册简单描述符。
(2)也可以直接调用afRegister()直接在AF中注册简单描述符。
在注册完简单描述符之后,就可以使用AF层的通信API来收发数据了。
3.3 数据发送API简介
数据发送API
打开配套的工程,可以在Profile中找到一个AF.h文件,如图所示。
在这个文件中可以找到一个名为AF_DataRequest()的数据发送API,如图所示。
这就是AF层的数据发送API,它的参数说明如下:
/*
* @param dstAddr 目标设备地址,包含网络地址和端点号
* @param srcEP 发送设备的简单描述符
* @param cID Cluster ID,后续章节将会详细讲解
* @param len 待发送数据的长度
* @param buf 待发送的数据
* @param transID 传输ID,可以用来给每一次发送的数据包编一个号
* @param options 附加选项,可以用来给这次数据发送添加一些说明
* @param radius 最大的路由跳转级数
*/
afStatus_t AF_DataRequest(
afAddrType_t *dstAddr,
endPointDesc_t *srcEP,
uint16 cID,
uint16 len,
uint8 *buf,
uint8 *transID,
uint8 options,
uint8 radius );
协议栈里面的SampleSwitch这个例程基于这个API封装出了点对点通信API、广播通信API和组播通信API。
点对点通信API
在zcl_samplesw.c文件中可以找到一个点对点通信API,代码如下:
/*
* @param destNwkAddr 目标设备的网络地址
* @param cid Cluster ID,后续课程将会详细讲解
* @param len 数据长度
* @param data 数据内容
*/
static void zclSampleSw_AF_P2P(
uint16 destNwkAddr,
uint16 cid,
uint8 len,
uint8 *data)
{
afAddrType_t dstAddr; //寻址信息配置
static uint8 transferId = 0;//传输ID,是数据包的标识符
/* Destination */
dstAddr.addrMode = afAddr16Bit;// 设置目标地址模式为16位网络地址,表示使用P2P的通信方式
dstAddr.addr.shortAddr = destNwkAddr;//目标设备的网络地址
dstAddr.endPoint = SAMPLESW_ENDPOINT;//目标设备的端点号
transferId++;
AF_DataRequest(&dstAddr,
&sampleSw_TestEp,//已经创建好的简单描述符
cid,
len,
data,
&transferId,
AF_DISCV_ROUTE,//进行路由扫描操作,用于建立发送数据报文的通信路径。关于这个参数,暂时保持例程默认的代码就可以了
AF_DEFAULT_RADIUS);//指定最大的路由跳转级数
}
这个API中使用了一个afAddrType_t类型变量,用于配置寻址信息。这个变量定义如下:
这个API中也使用了一个afAddrMode_t变量,表示地址模式(类型),用于说明使用的是点对点、广播还是组播的通信方式。同样地,可以查看其定义,代码如下:
可以看到,afAddrMode_t是一个枚举类型变量。
在zclSampleSw_AF_P2P()函数的的最后,可以看到最终就是调用AF_DataRequest()来发送数据的。开发者也可以基于AF_DataRequest()来编写自己的点对点通信API,而不使用这个工程中的默认的这个zclSampleSw_AF_P2P()。
广播通信API
在zcl_samplesw.c文件中可以找到广播通信API,代码如下:
/*
* @param cid Cluster ID
* @param len 待发送数据的长度
* @param *data 待发送数据的内容
*/
static void zclSampleSw_AF_Broadcast(
uint16 cid,
uint8 len,
uint8 *data)
{
afAddrType_t dstAddr;
static uint8 transferId = 0;
/* Destination */
dstAddr.addrMode = afAddrBroadcast; // 使用广播模式
dstAddr.addr.shortAddr = 0xFFFF; // 广播地址
dstAddr.endPoint = SAMPLESW_ENDPOINT; // 目标设备的端点号
/* Transfer id */
transferId++;
/* Send */
AF_DataRequest(
&dstAddr,
&sampleSw_TestEp,//已经创建好的简单描述符
cid,
len,
data,
&transferId,
AF_TX_OPTIONS_NONE,
AF_DEFAULT_RADIUS );//指定了最大的路由跳转级数
}
从广播通信API的定义可以发现,它和点对点通信API是相似的。广播通信API中使用了网络地址0xFFFF,这表示把数据发送到该网络上的所有设备中。但其实ZigBee的广播地址一共有3个,如下所示:
0xFFFF:广播给该网络中的所有设备
0xFFFD:只广播给该网络中打开收听功能的设备
0xFFFC:只广播给该网络中的协调器和路由设备
同样地,开发者也可以基于AF_DataRequest()来编写自己的广播通信API,而不使用这个工程中的默认的这个zclSampleSw_AF_Broadcast()。
组播通信API
使用组播通信API,可以只给指定的一组设备发送数据。在zcl_samplesw.c文件中可以找到组播通信API,代码如下:
/*
* @param groupId 组ID
* @param cid ClusterID,后续章节将会详细讲解
* @param len 待发送数据的长度
* @param data 待发送数据的内容
*/
static void zclSampleSw_AF_Groupcast(
uint16 groupId,
uint16 cid,
uint8 len,
uint8 *data)
{
afAddrType_t dstAddr;
static uint8 transferId = 0;
/* Destination */
dstAddr.addrMode = afAddrGroup;//使用组播通信模式
dstAddr.addr.shortAddr = groupId;
dstAddr.endPoint = SAMPLESW_ENDPOINT;//组中的设备的端点号
/* Transfer id */
transferId++;
/* Send */
AF_DataRequest(&dstAddr,
&sampleSw_TestEp,//已经创建好的简单描述符
cid,
len,
data,
&transferId,
AF_TX_OPTIONS_NONE,
AF_DEFAULT_RADIUS );//指定最大的路由跳转级数,暂时可忽略
}
上述代码还是比较简单的,就是给指定的组ID发送数据。后续章节将会以实验的方式讲解如何让设备加入到指定的组中。
3.4 ZigBee 3.0 通信实验
实验简介
在学习完AF层通信API后,本章将以实验的方式讲解如何使用这些API,实验设备包含一个协调器和一个路由器(或终端),内容是:
- 路由器(或终端)定时地通过点对点的方式向协调器发送数据。
- 让路由器(或终端)加入到一个组中。
- 协调器定时地发送广播数据和组播数据。
设备初始化
打开配套的SampleSwitch工程代码,在zcl_samplesw.c文件中的应用层初始化函数zclSampleSw_Init()的末尾,添加以下代码:
#ifdef ZDO_COORDINATOR
bdb_StartCommissioning( BDB_COMMISSIONING_MODE_NWK_FORMATION |
BDB_COMMISSIONING_MODE_FINDING_BINDING );
NLME_PermitJoiningRequest(255);
// Broadcast
osal_start_timerEx(zclSampleSw_TaskID,
SAMPLEAPP_BROADCAST_EVT,
SAMPLEAPP_BROADCAST_PERIOD);
// groupcast
osal_start_timerEx(zclSampleSw_TaskID,
SAMPLEAPP_GROUPCAST_EVT,
SAMPLEAPP_GROUPCAST_PERIOD);
#else
bdb_StartCommissioning( BDB_COMMISSIONING_MODE_NWK_STEERING |
BDB_COMMISSIONING_MODE_FINDING_BINDING );
// Add group
aps_Group_t group = {
.ID = GROUP_ID,
.name = "",
};
aps_AddGroup(SAMPLESW_ENDPOINT, &group);
// P2P
osal_start_timerEx(zclSampleSw_TaskID,
SAMPLEAPP_P2P_EVT,
SAMPLEAPP_P2P_PERIOD);
#endif
添加后如图所示。
协调器角色初始化
在协调器角色下,首先调用了bdb_StartCommissioning()创建一个ZigBee网络,然后调用NLME_PermitJoiningRequest(255)允许其他设备加入到这个网络中。接着调用osal_start_timerEx()产生了一个广播事件和组播事件。其中的事件和对应的事件周期的定义在zcl_samplesw.h文件中,代码如下:
//广播事件
#define SAMPLEAPP_BROADCAST_EVT 0x0080
#define SAMPLEAPP_BROADCAST_PERIOD 1000
//组播事件
#define SAMPLEAPP_GROUPCAST_EVT 0x0100
#define SAMPLEAPP_GROUPCAST_PERIOD 1000
终端(或路由器角色)初始化
在终端(或路由器)角色下,首先调用了bdb_StartCommissioning()加入ZigBee网络,然后创建一个组,创建一个组的代码如下:
// Add group
aps_Group_t group = {
.ID = GROUP_ID,
.name = "",
};
其中的GROUP_ID的定义同样在zcl_samplesw.c文件中,代码如下:
// GroupId
#define GROUP_ID 21
接着调用aps_AddGroup()加入到这个组中,代码如下:
aps_AddGroup(
SAMPLESW_ENDPOINT,//端点号
&group);//待加入的组
最后,调用osal_start_timerEx()启动一个点对点通信事件,这个事件和事件周期的定义在zcl_samplesw.h文件中,代码如下:
// P2P
#define SAMPLEAPP_P2P_EVT 0x0100
#define SAMPLEAPP_P2P_PERIOD 1000
协调器的事件处理
应用层初始化函数zclSampleSw_Init()中,协调器角色设备产生了一个广播事件SAMPLEAPP_BROADCAST_EVT 和一个组播事件SAMPLEAPP_GROUPCAST_EVT,因此需要编写对应的事件处理代码。
在zcl_samplesw.c文件中的应用层事件处理函数zclSampleSw_event_loop()添加对应的事件处理代码:
// Broadcast event
if ( events & SAMPLEAPP_BROADCAST_EVT )
{
zclSampleSw_AF_Broadcast(CLUSTER_BROADCAST,
10, "Broadcast");
osal_start_timerEx(zclSampleSw_TaskID,
SAMPLEAPP_BROADCAST_EVT,
SAMPLEAPP_BROADCAST_PERIOD);
return ( events ^ SAMPLEAPP_BROADCAST_EVT );
}
// Groupcast event
if ( events & SAMPLEAPP_GROUPCAST_EVT )
{
zclSampleSw_AF_Groupcast(GROUP_ID,
CLUSTER_GROUPCAST,
10, "Groupcast");
osal_start_timerEx(zclSampleSw_TaskID,
SAMPLEAPP_GROUPCAST_EVT,
SAMPLEAPP_GROUPCAST_PERIOD);
return ( events ^ SAMPLEAPP_GROUPCAST_EVT );
}
添加后如图所示。
在广播事件处理中,首先调用了zclSampleSw_AF_Broadcast()发送一个广播信息,代码如下:
zclSampleSw_AF_Broadcast(
CLUSTER_BROADCAST,//Cluster ID
10,//待发送数据的长度
"Broadcast");//待发送数据的内容
接着再次调用osal_start_timerEx()重新产生一个广播事件。
组播事件的处理也是类似的,同样是调用zclSampleSw_AF_Broadcast()发送一个组播,然后调用osal_start_timerEx()重新产生一个组播事件。
其中的CLUSTER_BROADCAST和CLUSTER_GROUPCAST,再加上在下文将会讲到的CLUSTER_P2P都是Cluster ID,是由笔者自定义的,代码如下:
#define CLUSTER_P2P 0
#define CLUSTER_BROADCAST 1
#define CLUSTER_GROUPCAST 2
可以看到这3个Cluster ID本质上就是一个宏定义,并且它的值就是0、1和2。
终端(或路由器)的事件处理
应用层初始化函数zclSampleSw_Init()中,终端(或路由器)角色设备产生了一个点对点通信事件,因此需要编写对应的事件处理代码。
在zcl_samplesw.c文件中的应用层事件处理函数zclSampleSw_event_loop()添加对应的事件处理代码。
// P2P Event
if ( events & SAMPLEAPP_P2P_EVT )
{
zclSampleSw_AF_P2P(0x0000,
CLUSTER_P2P,
4, "P2P");
osal_start_timerEx(zclSampleSw_TaskID,
SAMPLEAPP_P2P_EVT,
SAMPLEAPP_P2P_PERIOD);
return ( events ^ SAMPLEAPP_P2P_EVT );
}
添加后如图所示。
在点对点通信事件处理中,首先调用了zclSampleSw_AF_Broadcast()发送一个点对点信息,代码如下:
zclSampleSw_AF_P2P(
0x0000,//目标设备的网络地址
CLUSTER_P2P,//Cluster ID
4,//待发送数据的长度
"P2P");//待发送数据的内容
其中的网络地址0x0000是协调器的网络地址。跟广播和组播事件处理类似,在发送数据之后,调用osal_start_timerEx()重新产生一个点对点通信事件。
接收和处理数据
前面讲解了如何发送数据,接下来讲解如何接收数据。ZigBee设备在组网成功之后,接收到数据时会产生一个系统事件AF_INCOMING_MSG_CMD表示现在接收到数据了。
打开zcl_samplesw.c文件,可以找到一个应用层事件处理函数zclSampleSw_event_loop(),如图所示。
可以看到,系统事件处理代码中已经包含了对系统事件AF_INCOMING_MSG_CMD的识别了,开发者只需要在接收到这个事件后进行相应的处理就可以了。
笔者已经定义一个数据处理函数zclSampleSw_AF_RxProc()来处理接收到的数据了,代码如下:
/*
* @param MSGpkt 接收到数据
*/
static void zclSampleSw_AF_RxProc(afIncomingMSGPacket_t *MSGpkt)
{
/*计数器,记录接收到的点对点通信数据包个数*/
static uint8 p2pCnt = 0;
/*计数器,记录接收到的广播通信数据包个数*/
static uint8 bcCnt = 0;
/*计数器,记录接收到的组播通信数据包个数*/
static uint8 gcCnt = 0;
switch( MSGpkt->clusterId ) // 判断接收到的数据包的Cluster ID,后续章节将会详细讲解Cluster ID
{
case CLUSTER_P2P:
p2pCnt++; // 接收到P2P数据包,进行计数
// 把接收到的数据和计数器的值显示在屏幕上
HalLcdWriteStringValue((char *)MSGpkt->cmd.Data,p2pCnt,10,3);
break;
case CLUSTER_BROADCAST:
bcCnt++; // 接收到广播数据包,进行计数
HalLcdWriteStringValue((char *)MSGpkt->cmd.Data,bcCnt,10,3);
break;
case CLUSTER_GROUPCAST:
gcCnt++; // 接收到组播数据包,进行计数
HalLcdWriteStringValue((char *)MSGpkt->cmd.Data,gcCnt,10,4);
break;
default:
break;
}
}
代码中用到了之前定义的3个Cluster ID,它们可以用来标识利用不同的通信方式发送过来的数据包,含义如下: