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 );
ZDO邦定API
绑定机制允许一个应用服务在不知道目标地址的情况下向对方(的应用服务)发送数据包。发送时使用的目标地址将由应用支持子层从绑定表中自动获得,从而能使消息顺利被目标节点的一个或多个应用服务,乃至分组接收。
由于所有邦定信息都在Zigbee协调器中,所以只有协调器才能接收邦定请求。
ZDO Binding API ZDP Binding Service Command
ZDP_EndDeviceBindReq() End_Device_Bind_req
ZDP_EndDeviceBindRsp() End_Device_Bind_rsp
ZDP_BindReq() Bind_req
ZDP_BindRsp() Bind_rsp
ZDP_UnbindReq() Unbind_req
ZDP_UnbindRsp() Unbind_rsp
afStatus_t ZDP_EndDeviceBindReq( zAddrType_t *dstAddr,uint16 LocalCoordinator, byte epIntf,
uint16 ProfileID,byte NumInClusters, byte *InClusterList,
byte NumOutClusters, byte *OutClusterList,byte SecuritySuite );
构建并发送节点设备邦定请求(Hand Bingding)。
LocalCoordinator - 设备父协调器的16位网络地址
NumInClusters - 输入簇中的cluster ID数目
InClusterList - 输入cluster IDs的数组
afStatus_t ZDP_EndDeviceBindRsp( byte TranSeq, zAddrType_t *dstAddr,
byte Status, byte SecurityEnable );
Status - SUCCESS 0
NOT_SUPPORTED 1
TIMEOUT 2
NO_MATCH 3
afStatus_t ZDP_BindReq( zAddrType_t *dstAddr, byte *SourceAddr,
byte SrcEPIntf, byte ClusterID, byte *DestinationAddr, byte DstEPIntf,
byte SecuritySuite );
请求协调器利用cluster ID邦定应用
ClusterID – 要邦定的cluster ID
DestinationAddr – 接收消息的设备的64位地址
afStatus_t ZDP_BindRsp( byte TranSeq, zAddrType_t *dstAddr,byte Status, byte SecurityEnable );
Status - SUCCESS 0
NOT_SUPPORTED 1
TABLE_FULL 2
afStatus_t ZDP_UnbindReq( zAddrType_t *dstAddr,
byte *SourceAddr, byte SrcEPIntf,
byte ClusterID,
byte *DestinationAddr, byte DstEPIntf,
byte SecuritySuite );
请求Zigbee协调器移除邦定。
afStatus_t ZDP_UnbindRsp( byte TranSeq, zAddrType_t *dstAddr, byte Status,byte SecurityEnable );
Status - SUCCESS 0x00
NOT_SUPPORTED 1
NO_ENTRY 2
ZDO管理API
这些消息用来取得设备状态和更新表格
ZDP Management API ZDP Network Management Service Command
ZDP_MgmtNwkDiscReq() Mgmt_NWK_Disc_req
ZDP_MgmtNwkDiscRsp() Mgmt_NWK_Disc_rsp
ZDP_MgmtLqiReq() Mgmt_Lqi_req
ZDP_MgmtLqiRsp() Mgmt_Lqi_rsp
ZDP_MgmtRtgReq() Mgmt_Lqi_req
ZDP_MgmtRtgRsp() Mgmt_Rtg_rsp
ZDP_MgmtBindReq() Mgmt_Bind_req
ZDP_MgmtBindRsp() Mgmt_Bind_rsp
ZDP_MgmtLeaveReq() Mgmt_Leave_req
ZDP_MgmtLeaveRsp() Mgmt_Leave_rsp
ZDP_MgmtDirectJoinReq() Mgmt_Direct_Join_req
ZDP_MgmtDirectJoinRsp() Mgmt_Direct_Join_rsp
ZDP_MgmtPermitJoinReq() Mgmt_Permit_Join_req
ZDP_MgmtPermitJoinRsp() Mgmt_Permit_Join_rsp
afStatus_t ZDP_MgmtNwkDiscReq( zAddrType_t *dstAddr,
uint32 ScanChannels, byte StartIndex, byte SecurityEnable );
如果设备支持这个命令,调用此函数将为目标设备产生一个扫描网络的请求。只有设置ZDO_MGMT_NWKDISC_REQUEST编译选项(ZDConfig.h)才能调用此函数。
afStatus_t ZDP_MgmtNwkDiscRsp( byte TranSeq, zAddrType_t *dstAddr,byte Status,
byte NetworkCount, byte StartIndex, byte NetworkCountList,
networkDesc_t *NetworkList, byte SecurityEnable );
若设置ZDO_MGMT_NWKDISC_RESPONSE编译选项,当接收到“Management Network Discovery Request”消息后将自动产生这个消息。
afStatus_t ZDP_MgmtLqiReq ( zAddrType_t *dstAddr,byte StartIndex, byte SecurityEnable );
若设置ZDO_MGMT_LQI_REQUEST编译选项,调用此函数将为目标设备产生返回邻居列表的请求。
ZStatus_t ZDP_MgmtLqiRsp( byte TranSeq, zAddrType_t *dstAddr,
byte Status, byte NeighborLqiEntries,
byte StartIndex, byte NeighborLqiCount,
neighborLqiItem_t *NeighborLqiList,
byte SecurityEnable );
afStatus_t ZDP_MgmtRtgReq( zAddrType_t *dstAddr,
byte StartIndex, byte SecurityEnable );
若设置ZDO_MGMT_RTG_REQUEST编译选项,调用此函数将为目标设备产生返回路由列表的请求。
ZStatus_t –状态值,定义在ZComDef.h中的ZStatus_t
ZStatus_t ZDP_MgmtRtgRsp( byte TranSeq, zAddrType_t *dstAddr,
byte Status, byte RoutingTableEntries,
byte StartIndex, byte RoutingListCount,
rtgItem_t *RoutingTableList, byte SecurityEnable );
若设置ZDO_MGMT_RTG_REQUEST编译选项,当接收到“Management Routing Request”消息后将自动产生这个消息。
afStatus_t ZDP_MgmtBindReq( zAddrType_t *dstAddr,
byte StartIndex, byte SecurityEnable );
若设置ZDO_MGMT_BIND_REQUEST编译选项,调用此函数将为目标设备产生返回邦定表的请求。
ZStatus_t ZDP_MgmtBindRsp( byte TranSeq, zAddrType_t *dstAddr,
byte Status, byte BindingTableEntries,
byte StartIndex, byte BindingTableListCount,
apsBindingItem_t *BindingTableList,
byte SecurityEnable );
afStatus_t ZDP_MgmtLeaveReq( zAddrType_t *dstAddr,byte *IEEEAddr, byte SecurityEnable );
若设置ZDO_MGMT_LEAVE_REQUEST编译选项,调用此函数将请求目标设备脱离网络或者请求其他设备脱离网络
ZStatus_t ZDP_MgmtLeaveRsp( byte TranSeq, zAddrType_t *dstAddr,byte Status, byte SecurityEnable );
若设置ZDO_MGMT_LEAVE_REQUEST编译选项,当接收到“Management Leave Reques”消息后将自动产生这个消息。
afStatus_t ZDP_MgmtDirectJoinReq( zAddrType_t *dstAddr,byte *deviceAddr, byte capInfo, byte SecurityEnable );
若设置ZDO_MGMT_JOINDIRECT_REQUEST编译选项,调用此函数将请求目标设备直接加入其他设备。
deviceAddr – 要加入的设备的64位地址
capInfo – 要加入设备的性能
CAPINFO_ALTPANCOORD 0x01
CAPINFO_DEVICETYPE_FFD 0x02
CAPINFO_POWER_AC 0x04
CAPINFO_RCVR_ON_IDLE 0x08
CAPINFO_SECURITY_CAPABLE 0x40
CAPINFO_ALLOC_ADDR 0x80
ZStatus_t ZDP_MgmtDirectJoinRsp( byte TranSeq, zAddrType_t *dstAddr,byte Status, byte SecurityEnable);
afStatus_t ZDP_MgmtPermitJoinReq( zAddrType_t *dstAddr, byte duration,
byte TcSignificance, byte SecurityEnable );
实际是直接调用宏ZDP_SendData (),函数构建并发送Mgmt_Permit_Joining_req来请求远端设备允许或不允许关联。这个请求由调试工具或者网络管理设备产生,
duration -协调器或路由器允许关联的时间(单位为秒),0x00和0xff分别表示没有时间限制的禁止和允许。
TcSignificance -如果设为0x01且远端设备为真实中心设备的话,命令将影响中心设备的授权机制。
ZStatus_t ZDP_MgmtPermitJoinRsp( byte *TransSeq,zAddrType_t *dstAddr, byte *Statue, byte SecurityEnable);
ZDO解析函数
用来解析接收到的消息
ZDO_NwkIEEEAddrResp_t *ZDO_ParseAddrRsp( zdoIncomingMsg_t *inMsg );
解析NWK_addr_rsp和IEEE_addr_rsp消息
inMsg -指向接收到的消息的指针
ZDO_NwkIEEEAddrResp_t -指向解析后的结构的指针,结构体由osal_mem_alloc分配空间,所以需要调用osal_mem_free()来释放空间
void ZDO_ParseNodeDescRsp( zdoIncomingMsg_t *inMsg,ZDO_NodeDescRsp_t *pNDRsp );
解析Node_Desc_rsp消息
pNDRsp -解析消息存放的地方
void ZDO_ParsePowerDescRsp( zdoIncomingMsg_t *inMsg,ZDO_PowerRsp_t *pNPRsp );
解析Power_Desc_rsp消息
void ZDO_ParseSimpleDescRsp( zdoIncomingMsg_t *inMsg,ZDO_SimpleDescRsp_t *pSimpleDescRsp );
pSimpleDescRsp -存放解析后的消息
ZDO_ActiveEndpointRsp_t *ZDO_ParseEPListRsp( zdoIncomingMsg_t *inMsg );
解析Active_EP_rsp或者Match_Desc_rsp的消息
#define ZDO_ParseBindRsp(a) ((uint8)(*(a->asdu)))
解析Bind_rsp, Unbind_rsp或End_Device_Bind_rsp消息
a -指向要解析的消息的指针
ZDO_MgmNwkDiscRsp_t *ZDO_ParseMgmNwkDiscRsp( zdoIncomingMsg_t *inMsg );
解析Mgmt_NWK_Disc_rsp消息
ZDO_MgmtLqiRsp_t *ZDO_ParseMgmtLqiRsp( zdoIncomingMsg_t *inMsg );
ZDO_MgmtRtgRsp_t *ZDO_ParseMgmtRtgRsp( zdoIncomingMsg_t *inMsg );
ZDO_MgmtBindRsp_t *ZDO_ParseMgmtBindRsp( zdoIncomingMsg_t *inMsg );
#define ZDO_ParseMgmtDirectJoinRsp(a) ((uint8)(*(a->asdu)))
#define ZDO_ParseMgmtLeaveRsp(a) ((uint8)(*(a->asdu)))
#define ZDO_ParseMgmtPermitJoinRsp(a) ((uint8)(*(a->asdu)))
ZDO_UserDescRsp_t *ZDO_ParseUserDescRsp( zdoIncomingMsg_t *inMsg );
void ZDO_ParseServerDiscRsp( zdoIncomingMsg_t *inMsg,ZDO_ServerDiscRsp_t *pRsp );
解析Server_Discovery_rsp消息
void ZDO_ParseEndDeviceBindReq( zdoIncomingMsg_t *inMsg,ZDEndDeviceBind_t *bindReq );
void ZDO_ParseBindUnbindReq( zdoIncomingMsg_t *inMsg,ZDO_BindUnbindReq_t *pReq );
#define ZDO_ParseUserDescConf(a) ((uint8)(*(a->asdu)))
void ZDO_ParseDeviceAnnce( zdoIncomingMsg_t *inMsg, ZDO_DeviceAnnce_t *pAnnce );
ZDO_MgmtNwkUpdateNotify_t *ZDO_ParseMgmtNwkUpdateNotify(zdoIncomingMsg_t *inMsg );
应用框架(AF)
应用框架层是应用道APS层的OTA数据接口。此层也接收数据消息的终端多路复用器。AF为应用提供以下功能:
· 终端(Endpoint)管理
· 发送和接收数据
哈哈,这里的函数应该就是我们经常要用到的函数了。
终端管理
每个设备都是Zigbee中的节点,每个节点有长地址和短地址,短地址被其他设备用来发送数据。每个节点又241个终端(0保留,1-240 可分配给应用)。每个终端可以独立设置地址;当设备发送数据时必须指定目标设备的短地址和接收终端。一个应用必须注册一个或多个终端用来接收或者发送数据。
简单描述符-SimpleDescriptionFormat_t
每个终端都必须有一个Zigbee简单描述。这些描述对Zigbee网络刻画了这个终端,其他设备可以询问这个终端以知道这个设备的类型。
typedef struct
{
byte EndPoint;
uint16 AppProfId;
uint16 AppDeviceId;
byte AppDevVer:4;
byte Reserved:4; // AF_V1_SUPPORT uses for AppFlags:4.
byte AppNumInClusters;
cId_t *pAppInClusterList;
byte AppNumOutClusters;
cId_t *pAppOutClusterList;
} SimpleDescriptionFormat_t;
EndPoint – 终端号:1-240 这是节点的子地址,用来接收数据
AppProfId – 定义了这个终端上支持的Profile ID(剖面ID), ID最好遵循由ZigBee联盟的分配。
AppDeviceId –终端支持的设备ID,ID最好遵循ZigBee联盟的分配。
AppDevVer –此终端上设备执行的设备描述的版本:0x00为Version 1.0.
Reserved – 保留
AppNumInClusters – 终端支持的输入簇数目
pAppInClusterList – 指向输入Cluster ID列表的指针
AppNumOutClusters – 终端支持的输出簇数目
pAppOutClusterList – 指向输出Cluster ID列表的指针
终端描述符-endPointDesc_t
节点中的每一个终端都必须有一个终端描述符
typedef struct
{
byte endPoint;
byte *task_id; // Pointer to location of the Application task ID.
SimpleDescriptionFormat_t *simpleDesc;
afNetworkLatencyReq_t latencyReq;
} endPointDesc_t;
task_id -任务ID指针,当接收到消息时,此任务ID将指示消息传递目的。接收到的消息是以OSAL消息形式包装的,将发送到一个任务
simpleDesc -指向这个终端的ZigBee简单描述
latencyReq -必须用noLatencyReqs来填充
afStatus_t afRegister( endPointDesc_t *epDesc );
为设备注册一个新的终端
epDesc -指向终端描述符
返回值:afStatus_t -若成功则返回ZSuccess,否则返回ZComDef.h中定义的错误
epList_t *afRegisterExtended( endPointDesc_t *epDesc, pDescCB descFn );
在上面函数功能的基础上增加了回调函数,当终端的简单描述符被查询时将调用此回调函数。这样应有就可以动态改变简单描述符而不用RAM/ROM来储存描述符了。
descFn -回调函数指针。相关函数必须为简单描述符分配足够的空间,填充简单描述符,然后返回指向简单描述符的指针,调用者将释放为描述符分配空间。
epList -指向终端列表元件的指针,如果失败则为NULL
endPointDesc_t *afFindEndPointDesc( byte endPoint );
从一个终端找到终端描述符
endPoint -要寻找的终端描述符的终端号
endPointDesc_t -指向终端描述符的指针,若失败则为NULL
byte afFindSimpleDesc( SimpleDescriptionFormat_t **ppDesc, byte EP );
从一个终端找到终端描述符。若返回值非零则必须调用osal_mem_free()来释放描述符的内存占用。
ppDesc -指向指向简单描述符的指针。
EP –终端简单描述符需要
uint8 afGetMatch( uint8 ep );
默认情况下,设备将响应ZDO匹配描述符请求。用这个函数来获得ZDO匹配描述符应答的设置。
ep -用来获得ZDO匹配描述符响应行为的终端
返回值:TRUE-允许响应,FALSE-不允许或者终端未找到
uint8 afSetMatch( uint8 ep, uint8 action );
默认情况下,设备将响应ZDO匹配描述符。可以用这个函数来改变这个行为,比如ep为1,action为FALSE,ZDO将不响应终端1的ZDO匹配面述符请求。
ep -用来获得ZDO匹配描述符响应行为的终端
action -TRUE-允许响应,FALSE-不允许或者终端未找到
返回值:TRUE-成功,FALSE-失败或者终端未找到
byte afNumEndPoints( void );
查找已注册的终端数目,返回此设备上已注册的终端数目,包括终端0
void afEndPoints( byte *epBuf, byte skipZDO );
返回包含已注册的终端的一个数组。
epBuf – 指向存放终端的数组,每个终端占一个字节
skipZDO -设置为TRUE,则不包含ZDO终端(终端0)
发送数据
afStatus_t AF_DataRequest( afAddrType_t *dstAddr, endPointDesc_t *srcEP,
uint16 cID, uint16 len, uint8 *buf, uint8 *transID,
uint8 options, uint8 radius );
dstAddr -目标地址指针。
afAddrNotPresent 由反射器(邦定源,也即路由器或者协调器)指定
afAddrGroup 发送到组
afAddrBroadcast 发送广播消息
afAddr16Bit 直接发送到节点(单播)
srcEP -发送终端的终端描述符指针
cID -簇ID,cluster ID如同消息ID,并且在剖面(profile)中各不相同
len -要发送的字节数
buf -指向要发送的数据缓存的指针
transID -事务序列号指针。如果消息缓存发送,这个函数将增加这个数字
options -发送选项,可以由下面一项,或几项相或得到
AF_ACK_REQUEST 0x10 要求APS应答,这是应用层的应答,支在直接发送(单播)时使用。
AF_DISCV_ROUTE 0x20 总要包含这个选项
AF_SKIP_ROUTING 0x80 设置这个选项将导致设备跳过路由而直接发送消息。终点设备将不向其父亲发送消息。在直接发送(单播)和广播消息时很好用。
radius – 最大的跳数,用默认值AF_DEFAULT_RADIUS
afStatus_t – 成功则为ZSuccess(defined in ZComDef.h). 否则 Errors(defined in ZComDef.h)
uint8 afDataReqMTU( afDataReqMTU_t* fields );
找出基于输入参数的最大可发送字节数,返回能发送的最大字节数
fields -要发送的消息类型参数
typedef struct
{
uint8 kvp;
APSDE_DataReqMTU_t aps;
} afDataReqMTU_t;
kvp – 设为false.
typedef struct
{
uint8 secure;
} APSDE_DataReqMTU_t;
aps.secure – 设为false.如果在一个安全网络中此位将自动设置.