当前位置:中国高校自动化网 >> RIFI >> 浏览文章

原创ZigBee学习之13——ZStack API解读

文章来源:EDN博客 作者:佚名 访问次数:


本文来自佚名的博客,讲述了原创ZigBee学习之13——ZStack API解读的原理和应用, 作者博客:http://blog.ednchina.com/佚名

Z-Stack API[Z-Stack API _F8W-2006-0021_.pdf]

这个文档是一个关键了,Z-Stack的应用程序接口。我们在程序中基本上应该调用的是这些API吧。

ZDO层API

实现了所有ZDP(ZigBee Device Profile)定义的命令和回应所需要的函数。ZDP描述了ZDO如何实现普通ZigBee设备的特性,它定义了设备描述和簇,ZDP为ZDO和应用提供一下功能:

·                     设备网络建立

·                     设备和服务发现

·                     节点设备邦定和解邦定服务

·                     网络管理服务

设备发现是ZigBee设备发现其他ZigBee设备的过程。比如将已知的IEEE地址作为数据载荷广播到网络的NWK地址请求,相关设备必须回应并告知其网络地址。服务发现提供了PAN中一个设备发现其他设备提供的服务的能力。它利用多种描述符去指定设备的能力。

当用户需要邦定控制器与被控设备(比如开关和灯)时,将用到邦定和解邦定服务。特别是终端设备邦定支持利用用户的输入来定义控制/被控设备对的简单邦定方法。邦定和解邦服务可以创建和删除邦定表入口。

网络管理服务主要提供给用户和调试工具网络管理的能力,它能够从设备重新获得管理信息,包括网络发现结果,路由表的内容,邻居节点链路质量,邦定表内容。也可以通过解关联将设备从PAN中脱离来控制网络关联。

ZDO设备网络建立

在ZigBee网络中默认ZDApp_Init()[in ZDApp.c]开始器件的启动,但是应用能覆盖整个默认行为,为了使应用接管网络的启动,必须在编译选项中包含HOLD_AUTO_START,推荐同时包含NV_RESTORE(储存ZigBee网络状态到NV)编译选项,包含这个两个编译选项后就需要调用ZDOInitDevice() 来启动网络中的设备。

uint8 ZDOInitDevice( uint16 startDelay )

启动网络中的设备。如果应用想要强制一个“新的”加入(即不恢复网络状态),则应该先调用zgWriteStartupOptions(ZG_STARTUP_SET, ZCD_STARTOPT_DEFAULT_NETWORK_STATE)来设置ZCD_NV_STARTUP_OPTION 中的ZCD_STARTOPT_DEFAULT_NETWORK_STATE 位。

startDelay  -启动设备的延时。这个延时有一个抖动:

(NWK_START_DELAY + startDelay) + (osal_rand() & EXTENDED_JOINING_RANDOM_MASK)

返回值:

ZDO_INITDEV_RESTORED_NETWORK_STATE      设备的网络状态恢复

ZDO_INITDEV_NEW_NETWORK_STATE       网络状态被初始化。即一个强制“新的”加入,或者没有可供恢复的状态

ZDO_INITDEV_LEAVE_NOT_STARTED       重置前,发送了网络脱离并且重加入被设置为TRUE。因此器件没有启动,但是下次调用此函数将启动。

ZDO消息回馈

通过ZDO_RegisterForZDOMsg()注册消息,应用就能接收任何空中(over the air)消息。

ZStatus_t ZDO_RegisterForZDOMsg( uint8 taskID, uint16 clusterID )

调用此函数请求over-the-air消息,此消息的备份将以OSAL消息发送到任务,接收到消息的任务可以自己解析消息,也可以调用ZDO解析函数来解析消息。只有响应消息有ZDO解析函数。

消息注册并被接收后(OTA),将作为ZDO_CB_MSG (OSAL Msg)发送到应用/任务。消息体(zdoIncomingMsg_t – defined in ZDProfile.h)包含有OTA消息。

taskID      -用来发送OSAL消息的应用任务ID;

clusterID   -想要接收的OTA消息的clusterID。如:NWK_addr_rsp。这些ID定义在ZDProfile.h

返回值:ZStatus_t    -ZComDef.h中ZStatus_t定义的状态值

ZStatus_t ZDO_RemoveRegisteredCB( uint8 taskID, uint16 clusterID )

为OTA消息移除一个请求。

参数必须和ZDO_RegisterForZDOMsg()中的参数相同

ZDO发现API

这些API用来建立和发送ZDO设备和服务发现请求和回复。ZDO API和ZDP命令一一对应,ZDP命令可以在ZigBee协议规范中找到更详细的介绍。

ZDO API Function    ZDP Discovery Command

ZDP_NwkAddrReq()    NWK_addr_req

ZDP_NWKAddrRsp()    NWK_addr_rsp

ZDP_IEEEAddrReq()   IEEE_addr_req

ZDP_IEEEAddrRsp()   IEEE_addr_rsp

ZDP_NodeDescReq()   Node_Desc_req

ZDP_NodeDescRsp()   Node_Desc_rsp

ZDP_PowerDescReq() Power_Desc_req

ZDP_PowerDescRsp() Power_Desc_rsp

ZDP_SimpleDescReq()     Simple_Desc_req

ZDP_SimpleDescRsp()     Simple_Desc_rsp

ZDP_ComplexDescReq()    Complex_Desc_req

ZDP_ActiveEPIFReq()     Active_EP_req

ZDP_ActiveEPIFRsp()     Active_EP_rsp

ZDP_MatchDescReq() Match_Desc_req

ZDP_MatchDescRsp() Match_Desc_rsp

ZDP_UserDescSet()   User_Desc_set

ZDP_UserDescConf() User_Desc_conf

ZDP_UserDescReq()   User_Desc_req

ZDP_UserDescRsp()   User_Desc_rsp

ZDP_EndDeviceAnnce() Device_annce

ZDP_ServerDiscReq()     System_Server_Discovery_req

ZDP_ServerDiscRsp()     System_Server_Discovery_rsp

afStatus_t ZDP_NwkAddrReq( byte *IEEEAddress, byte ReqType,byte StartIndex, byte SecuritySuite )

发送为一个IEEE地址已知的设备请求16位短地址的消息,消息将以广播的形式发送。

IEEEAddress     -发送请求的设备的IEEE地址

ReqType     -希望收到的答复类型

    ZDP_NWKADDR_REQTYPE_SINGLE      返回设备的短地址和扩展地址

    ZDP_NWKADDR_REQTYPE_EXTENDED    返回设备的短地址和扩展地址,以及所有关联设备的短地址

StartIndex      -应答设备可能含有多条符合应答消息的应答条目,此参数指定请求开始检索的应答条目

SecuritySuite       -消息的安全类型

返回值:afStatus_t   -次函数用AF来发送消息,所以状态值为ZComDef.h中ZStatus_t定义的AF状态值

afStatus_t ZDP_NWKAddrRsp( byte TranSeq, zAddrType_t *dstAddr, 

                  byte Status, byte *IEEEAddrRemoteDev, 

                  byte ReqType, uint16 nwkAddr,

                  byte NumAssocDev, byte StartIndex,

                  uint16 *NWKAddrAssocDevList,

                  byte SecuritySuite );

这个函数实际上是调用ZDP_AddrRsp()的宏,用来建立和发送网络地址应答

TranSeq –   报文序号

DstAddr -   目标地址

Status –    ZDP_SUCCESS             0

        ZDP_INVALID_REQTYPE         1

        ZDP_DEVICE_NOT_FOUND    2

        Reserved            0x03-0xff

IEEEAddrRemoteDev - 远端设备的64位地址

ReqType –   请求类型

nwkAddr –   远端设备的16位地址

NumAssocDev - 和远端设备相关联的设备及其16位短地址的数目

StartIndex  - 应答消息的开始序号

NWKAddrAssocDevList -相关联的16位地址列表

SecuritySuite - 消息安全类型

afStatus_t ZDP_IEEEAddrReq( uint16 shortAddr, byte ReqType, 

                            byte StartIndex, byte SecuritySuite )

已知设备的16位短地址请求64位IEEE地址。

呵呵好多参数都是一看就知道是什么了呢,那就不写出来了,下面的函数也一样的处理了。

afStatus_t ZDP_IEEEAddrRsp( byte TranSeq, zAddrType_t *dstAddr, 

                        byte Status, byte *IEEEAddrRemoteDev, 

                        byte ReqType, uint16 nwkAddr,

                        byte NumAssocDev, byte StartIndex,

                        uint16 *NWKAddrAssocDevList,

                        byte SecuritySuite );

这个函数实际上是调用ZDP_AddrRsp()的宏,用来建立和发送IEEE地址应答

afStatus_t ZDP_NodeDescReq( zAddrType_t *dstAddr, uint16 NWKAddrOfInterest, byte SecuritySuite );

构建并向目标地址域发送节点描述请求

afStatus_t ZDP_NodeDescMsg( byte TransSeq, zAddrType_t *dstAddr, byte Status, 

                        uint16 nwkAddr, NodeDescriptorFormat_t *pNodeDesc, 

                        byte SecuritySuite );

DstAddr - 目标地址

NWKAddrOfInterest - 要搜寻的16位短地址

SecuritySuite - 消息的安全类型

afStatus_t ZDP_NodeDescMsg( byte TransSeq, zAddrType_t *dstAddr, byte Status, 

                        uint16 nwkAddr, NodeDescriptorFormat_t *pNodeDesc, 

                        byte SecuritySuite );

回应节点描述(Node Descriptor)请求。

Status      -   SUCCESS         0

            DEVICE_NOT_FOUND    1

pNodeDesc   -指向节点描述的指针(定义在AF.h中)

afStatus_t ZDP_PowerDescReq( zAddrType_t *dstAddr, int16 NWKAddrOfInterest,byte SecuritySuite );

构建和发送电源描述请求。实际是调用宏ZDP_NWKAddrOfInterestReq()

afStatus_t ZDP_PowerDescMsg( byte TranSeq, zAddrType_t *dstAddr, byte Status,

                int16 nwkAddr, NodePowerDescriptorFormat_t *pPowerDesc, 

                byte SecuritySuite );

回应电源描述请求。

Status      -   SUCCESS         0

            DEVICE_NOT_FOUND    1

pPowerDesc  -指向电源描述的指针(定义在AF.h中)

afStatus_t ZDP_SimpleDescReq(  zAddrType_t *dstAddr, uint16 nwkAddr, byte epIntf, byte SecuritySuite );

构建和发送简单描述请求。

epIntf      -希望的应用终端/接口

afStatus_t ZDP_SimpleDescRsp( byte TranSeq, zAddrType_t *dstAddr,  

            byte Status,  SimpleDescriptionFormat_t *pSimpleDesc, 

            byte SecuritySuite );

 

回应简单描述请求。

Status      -   SUCCESS         0

            INVALID_EP      1

            NOT_ACTIVE      2

            DEVICE_NOT_FOUND    3

afStatus_t ZDP_ComplexDescReq(  zAddrType_t *dstAddr, uint16 nwkAddr, byte SecuritySuite );

构建和发送复杂描述请求。实际是调用宏ZDP_NWKAddrOfInterestReq()

zigbee设备以描述项数据结构刻画自己,包含在描述项中的具体数据在描述中定义,有5种描述:节点,电源,简化,复杂和用户。

afStatus_t ZDP_ActiveEPIFReq( zAddrType_t *dstAddr, uint16 NWKAddrOfInterest,byte SecuritySuite );

构建和发送活动终端/接口请求,实际是调用宏ZDP_NWKAddrOfInterestReq(),用来请求远端设备上所有活动的终端/接口

NWKAddrOfInterest - 搜寻的16位短地址

afStatus_t ZDP_ActiveEPIFRsp( byte TranSeq, zAddrType_t  *dstAddr, 

            byte Status, uint16 nwkAddr, byte Count, byte *pEPIntfList, 

            byte SecuritySuite );

回应发送的活动终端/接口请求,实际是调用宏ZDP_EPIFRsp()

Status      -   SUCCESS         0

            DEVICE_NOT_FOUND    1

Count – pEPIntfList中活动终端(endpoint)/接口数目

pEPIntfList – 包含器件上终端(endpoint)/接口的数组

afStatus_t ZDP_MatchDescReq( zAddrType_t *dstAddr, uint16 nwkAddr, uint16 ProfileID,

                byte NumInClusters, byte *InClusterList,

                byte NumOutClusters, byte *OutClusterList,

                byte SecuritySuite );

 

构建并发送匹配描述请求,用来搜寻符合应用列表中某些输入输出簇得器件/接口

ProfileID       - cluster ID相关的ProfileID

NumInClusters       - 输入簇中的cluster ID数目

InClusterList       - 输入cluster IDs的数组

afStatus_t ZDP_MatchDescRsp( byte TranSeq, zAddrType_t *dstAddr, byte Status,

            uint16 nwkAddr, byte Count, byte *pEPIntfList, byte SecuritySuite );

Status      -   SUCCESS         0

            DEVICE_NOT_FOUND    1

Count – pEPIntfList中活动终端(endpoint)/接口数目

pEPIntfList – 包含器件上终端(endpoint)/接口的数组

afStatus_t ZDP_UserDescSet( zAddrType_t *dstAddr,uint16 nwkAddr,

                 UserDescriptorFormat_t *UserDescriptor,

                 byte SecurityEnable );

构建并发送User_Desc_set消息来设置远端设备的用户描述,这个请求单播到包含有发现信息的远端设备。远端设备需要定义NV_RESTORE来使能整个函数。

UserDescriptor –配制的用户描述,包含最多16个字符的ASCII字符串,若不足16个字符,则用空字符(0x20)填充到16个

afStatus_t ZDP_UserDescConf( byte TranSeq, zAddrType_t *dstAddr, byte Status, byte SecurityEnable );

调用这个函数来回应User_Desc_Conf

Status      -   SUCCESS         0x00

            INV_REQUESTTYPE     0x80

            DEVICE_NOT_FOUND    0x81

            NOT_SUPPORTED   0x84

afStatus_t ZDP_UserDescReq( zAddrType_t *dstAddr, uint16 nwkAddr, byte SecurityEnable );

构建并发送User_Desc_Req

ZStatus_t ZDP_UserDescRsp( byte TransSeq, zAddrType_t *dstAddr, 

                uint16 nwkAddrOfInterest, UserDescriptorFormat_t *userDesc, 

                byte SecurityEnable );

userDesc        -本地设备的用户描述

afStatus_t ZDP_EndDeviceAnnce( uint16 nwkAddr, byte *IEEEAddr,byte capabilities, byte SecurityEnable );

为ZigBee节点设备构建并发送End_Device_annce命令,通知其他ZigBee设备,此设备已加入或者已重新加入网络。此命令包含节点设备的新16位网络地址和64位IEEE地址,即以节点设备的功能。此消息已广播式发送。

afStatus_t ZDP_ServerDiscReq( uint16 serverMask, byte SecurityEnable );

构建并发送包含16位服务器掩码的System_Server_Discovery_req请求消息,以发现特殊系统服务器的位置或者服务器掩码指示的服务器。消息包含RxOnWhenIdle,以广播式发送。

ZStatus_t ZDP_ServerDiscRsp( byte transID, zAddrType_t *dstAddr, byte status,

                uint16 aoi, uint16 serverMask, byte SecurityEnable );

 

上一篇:ZigBee_对ZDO的初步理解
下一篇:原创ZigBee学习之14——ZStack API解读2
最近更新