1、ZigBee2007協議棧API函數使用說明第一章第二章 介紹 . 4 應用函數接口（API）. 52.1設備對象（ZDO） . 52.1.1 概述 . 52.1.2 ZDO網絡設備啟動 . 52.1.3 ZDO信息回調函數 . 72.1.3 .1 ZDO_RegisterForZDOMsg() . 72.1.3 .2 ZDO_RemoveRegistedCB() . 92.1.4 ZDO發現API . 102.1.4.1 ZDP_NwkAddrReq() . 112.1.4.2 ZDP_NWKAddrRsp() . 122.1.4.3 網絡地址請求和響應應用舉例分析 . 132.1.4.4

2、ZDP_IEEEAddrReq() . 142.1.4.5 ZDP_IEEEAddrRsp() . 152.1.4.6 IEEE地址請求和響應應用舉例分析 . 162.1.4.7 ZDP_NodeDescReq() . 172.1.4.8 ZDP_NodeDescMsg() . 182.1.4.9節點描述符請求和響應應用舉例分析 . 182.1.4.10 ZDP_PowerDescReq() . 202.1.4.11 ZDP_PowerDescMsg() . 202.1.4.12電源描述符請求和響應應用舉例分析 . 212.1.4.13 ZDP_SimpleDescReq() . 222.1.

3、4.14 ZDP_SimpleDescMsg() . 232.1.4.15簡單描述符請求和響應應用舉例分析 . 232.1.4.16 ZDP_ActiveEPIFReq () . 242.1.4.17 ZDP_ActiveEPIFRsp() . 252.1.4.18活動端點請求和響應應用舉例分析 . 262.1.4.20 ZDP_MatchDescRsp() . 272.1.4.21匹配描述符請求和響應應用舉例分析 . 282.1.4.22 ZDP_DeviceAnnce () . 292.1.5 ZDO綁定API . 302.1.5.1 ZDP_EndDeviceBindReq () . 3

4、12.1.5.2 ZDP_EndDeviceBindRsp () . 322.1.5.3 終端設備綁定請求和響應應用舉例分析 . 322.1.5.4 ZDP_BindReq () . 332.1.5.5 ZDP_BindRsp () . 342.1.5.6綁定請求和響應應用舉例分析 . 342.2應用框架（AF） . 362.2.1概述 . 362.2.2 端點管理 . 362.2.2.1 afRegister() . 362.2.2.2 afFindEndPointDesc() . 372.2.2.3 afFindSimpleDesc(). 382.2.2.4 afGetMatch() .

5、382.2.2.4 afSetMatch() . 392.2.3 發送數據 . 392.2.3.1 AF_DataRequest() . 392.2.4 接收數據 . 402.3應用支持子層（APS） . 422.3.1 綁定表管理. 422.3.2 組表管理 . 422.3.2.1 aps_AddGroup( ) . 432.3.2.2 aps_RemoveGroup( ). 432.3.2.3 aps_FindGroup( ) . 442.4網絡層（NWK） . 442.4.1 網絡管理 . 442.4.1.1 NLME_NetworkFormationRequest() . 442.4.

6、1.2 網絡層-組建網絡請求舉例分析 . 452.4.1.3 NLME_NetworkDiscoveryRequest() . 462.4.1.4網絡層-發現網絡請求舉例分析 . 472.4.1.5 NLME_JoinRequest(). 492.4.1.6網絡層-加入網絡請求舉例分析 . 492.4.1.7 NLME_ReJoinRequest() . 502.4.1.8網絡層-重新加入網絡請求舉例分析 . 512.4.1.9 NLME_OrphanJoinRequest() . 512.4.1.10網絡層-孤立節點連接父節點請求舉例分析 . 522.4.1.11 NLME_StartRou

7、terRequest() . 532.4.1.12網絡層-路由器啟動請求舉例分析. 532.4.2 地址管理 . 542.4.2.1 NLME_GetExtAddr() . 542.4.2.2 NLME_GetShortAddr() . 552.4.2.3 NLME_GetCoordShortAddr() . 552.4.2.4 NLME_GetCoordExtAddr() . 562.4.2.5 NLME_IsAddressBroadcast() . 562.4.2.6 NLME_SetBroadCastFilter() . 56第一章 介紹這份文檔為目前發布的ZigBee 2007協議棧提

8、供了應用程序接口函數（API）的使用說明。為使得我們更好地開發和理解ZigBee項目，這份文檔詳細的講述了協議棧中的數據結構和函數調用。首先，我們來了解一下在ZigBee 2007協議棧中使用的各個層次：l ZDO設備對象層，即ZDO（ZigBee Device Object）層，提供了管理一個ZigBee節點所要使用的功能函數。ZDO API為協調器、路由器和終端設備提供了應用端點的管理函數，其中包括：建立、發現和加入一個ZigBee網絡，綁定應用端點和安全管理。l AF應用框架層，即AF（Application Framework），提供了針對協議棧的應用端點（EndPoint1240）和

9、設備對象端點（EndPoint0）接口，其中主要包含：設備描述數據結構和數據收、發函數。 l APS應用支持子層，即APS（Application Support Sublayer），為設備對象和應用實體提供了一系列的支持服務。l NWK網絡層，即NWK（ZigBee network），為上層提供了管理服務和數據服務。l ZMAC介質訪問層，即ZMAC，在802.15.4 MAC 與 網絡層之間提供接口。第二章 應用函數接口（API）接下來我們講述的應用函數接口主要包含一些經常使用的數據結構和各層提供的關鍵性函數。2.1設備對象（ZDO）本節列舉出了在ZigBee設備規范，即ZigBee De

10、vice Profile（ZDP），所定義的相關命令和響應函數。2.1.1 概述ZDP描述了ZDO內部一般性的ZigBee設備功能是如何實現的。它定義了使用命令和響應對的設備描述和簇。ZDP為ZDO和應用程序提供如下功能：l 設備網絡啟動l 設備和服務發現l 終端設備綁定、綁定和取消綁定服務l 網絡管理服務 2.1.2 ZDO網絡設備啟動通過默認的ZDApp_Init()（在ZDApp.c中）啟動ZigBee網絡中的設備。但是一個應用程序可以跳過這個默認行為：ZDApp.c其中HOLD_AUTO_START在IAR ->Project->Option->C/C+ Compil

11、e->Preprocess->Defined symbols中定義。如果預編譯選擇HOLD_AUTO_START，則ZDO不啟動網絡設備，只是閃爍LED4。交由應用程序啟動網絡設備。ZDApp.cZDOInitDevice()具體描述如下：函數原型：uint8 ZDOInitDevice( uint16 startDelay );參數：startDelay 設備啟動延時（毫秒）返回值：ZDO_INITDEV_RESTORED_NETWORK_STATE（網絡狀態為恢復）ZDO_INITDEV_NEW_NETWORK_STATE （網絡狀態為初始化）ZDO_INITDEV_LEAVE

12、_NOT_STARTED （網絡狀態為未啟動）舉例分析：2.1.3 ZDO信息回調函數通過函數ZDO_RegisterForZDOMsg()注冊請求或響應消息，這樣就可以接收其他設備無線傳輸的消息。2.1.3 .1 ZDO_RegisterForZDOMsg()調用該函數可以將接收到的無線傳輸信息復制一份到OSAL層的某個任務。該任務接收到消息后可以自行解析此消息或者通過ZDO解析函數解析此消息。只有響應消息需要使用ZDO解析函數。 函數原型：ZStatus_t ZDO_RegisterForZDOMsg( uint8 taskID, uint16 clusterID );參數：taskID

13、-任務ID，該任務發送OSAL 消息；clustered-簇ID (例如: NWK_addr_rsp)，在 ZDProfile.h定義了相關的簇.返回值：ZStatus_t-狀態消息接收到之后作為ZDO_CB_Msg（一種系統消息）發送至應用或者任務,消息結構體zdoIncomingMsg_t 定義在ZDProfile.h中：消息結構體zdoIncomingMsg_t：在應用層使用該函數注冊的消息有：調用ZDO_RegisterForZDOMsg()在應用層注冊后，應用層處理接收到的消息方式如下：在ZDO層使用該函數注冊的消息有：調用ZDO_RegisterForZDOMsg()在ZDO層注冊

14、后，ZDO層處理接收到的消息方式如下： 2.1.3 .2 ZDO_RemoveRegistedCB()調用此函數取消請求無線傳輸的消息。函數原型：ZStatus_t ZDO_RemoveRegistedCB ( uint8 taskID, uint16 clusterID );參數：taskID -任務ID，該任務ID必須與ZDO_RegisterForZDOMsg()所注冊的任務ID相同；clustered-簇ID，該簇ID必須與ZDO_RegisterForZDOMsg()所使用的簇ID相同。返回值：ZStatus_t-狀態2.1.4 ZDO發現APIZDO發現API包含建立和發送ZDO設

15、備和服務發現請求和響應。所有這些API函數和ZDP命令（ZigBee Device Profile Command）如下表：2.1.4.1 ZDP_NwkAddrReq()調用此函數將生成一個根據已知IEEE地址詢問遠程節點16位網絡地址的消息。這個消息作為一個廣播消息發送至網絡中的所有節點。函數原型：afStatus_t ZDP_NwkAddrReq( byte *IEEEAddress, byte ReqType, byte StartIndex, byte SecuritySuite ); 參數：IEEEAddress-遠程節點的IEEE地址ReqType- ZDP_NWKADDR_RE

16、QTYPE_SINGLE（只返回節點的短地址和擴展地址）、ZDP_NWKADDR_REQTYPE_EXTENDED（返回節點的短地址和擴展地址以及所有相關節點的短地址）StartIndex-響應節點的響應信息可以有很多的響應選項，請求程序可以指定一個起始索引號，索引從0開始SecuritySuite 安全要求返回值：ZStatus_t-狀態2.1.4.2 ZDP_NWKAddrRsp()ZDP_NWKAddrRsp()實際上是調用ZDP_ADDRRsp()這個宏定義，用于建立和發送16位網絡地址響應。函數原型：afStatus_t ZDP_NWKAddrRsp( byte TranSeq, z

17、AddrType_t *dstAddr, byte Status,byte *IEEEAddrRemoteDev, byte ReqType, uint16 nwkAddr, byte NumAssocDev, byte StartIndex, uint16 *NWKAddrAssocDevList, byte SecuritySuite );參數：TranSeq-傳輸序號DstAddr-目的地址Status - ZDP_SUCCESS=0，ZDP_INVALID_REQTYPE=1，ZDP_DEVICE_NOT_FOUND=2 IEEEAddrRemoteDev 遠程節點的64位IEEE地址

18、ReqType 請求的類型nwkAddr 遠程節點的16位網絡地址NumAssocDev 與遠程節點關聯的節點數目StartIndex 響應節點的響應信息可以有很多的響應選項，請求程序可以指定一個起始索引號，該索引號是響應信息的起始索引號NWKAddrAssocDevList 與遠程節點關聯的節點16位網絡地址列表 SecuritySuite 安全要求返回值：ZStatus_t-狀態2.1.4.3 網絡地址請求和響應應用舉例分析本地節點首先需要在應用層或ZDO層注冊響應信息，本例中在sapi.c中注冊了NWK_addr_rsp信息。然后調用ZDP_NwkAddrReq()請求遠程節點的網絡地址

19、。遠程節點接收到該請求信息（該信息從屬于AF_DATA_CONFIRM_CMD），則根據Cluster ID選擇處理函數，本例中使用zdpProcessAddrReq()來處理網絡地址請求。當處理完之后，通過調用fillAndSend()將響應信息發送至本地節點。由于在應用層中注冊了該響應信息，因此調用SAPI_ProcessZDOMsgs()來處理響應信息。詳細流程如下圖所示：2.1.4.4 ZDP_IEEEAddrReq()調用此函數將生成一個根據已知16位網絡地址詢問遠程節點64位IEEE地址的消息。這個消息直接單播發送至該遠程節點。函數原型：afStatus_t ZDP_IEEEAdd

20、rReq( uint16 shortAddr, byte ReqType, byte StartIndex, byte SecuritySuite ); 參數：shortAddr-遠程節點的16位網絡地址ReqType- ZDP_NWKADDR_REQTYPE_SINGLE（只返回節點的短地址和擴展地址）、ZDP_NWKADDR_REQTYPE_EXTENDED（返回節點的短地址和擴展地址以及所有相關節點的短地址）StartIndex-響應節點的響應信息可以有很多的響應選項，請求程序可以指定一個起始索引號，索引從0開始SecuritySuite 安全要求返回值：ZStatus_t-狀態2.1.

21、4.5 ZDP_IEEEAddrRsp()ZDP_IEEEAddrRsp()實際上是調用ZDP_ADDRRsp()這個宏定義，用于建立和發送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

22、 );參數：TranSeq-傳輸序號DstAddr-目的地址Status - ZDP_SUCCESS=0，ZDP_INVALID_REQTYPE=1，ZDP_DEVICE_NOT_FOUND=2 IEEEAddrRemoteDev 遠程節點的64位IEEE地址ReqType 請求的類型nwkAddr 遠程節點的16位網絡地址NumAssocDev 與遠程節點關聯的節點數目StartIndex 響應節點的響應信息可以有很多的響應選項，請求程序可以指定一個起始索引號，該索引號是響應信息的起始索引號NWKAddrAssocDevList 與遠程節點關聯的節點16位網絡地址列表 SecuritySui

23、te 安全要求返回值：ZStatus_t-狀態2.1.4.6 IEEE地址請求和響應應用舉例分析本地節點首先需要在應用層或ZDO層注冊響應信息，本例中在ZDApp.c中注冊了IEEE_addr_rsp信息。然后調用ZDP_IEEEAddrReq()請求遠程節點的網絡地址。遠程節點接收到該請求信息（該信息從屬于AF_DATA_CONFIRM_CMD），則根據Cluster ID選擇處理函數，本例中使用zdpProcessAddrReq()來處理IEEE地址請求。當處理完之后，通過調用fillAndSend()將響應信息發送至本地節點。由于在ZDO中注冊了該響應信息，因此調用ZDApp_Proce

24、ssMsgCBs()來處理響應信息。詳細流程如下圖所示：2.1.4.7 ZDP_NodeDescReq()ZDP_NodeDescReq()實際上是調用宏定義ZDP_NWKAddrOfInterestReq()。這個函數建立和發送一個節點描述符（Node Descriptor）請求至已明確網絡地址的遠程節點。函數原型：afStatus_t ZDP_NodeDescReq( zAddrType_t *dstAddr, uint16 NWKAddrOfInterest, byte SecuritySuite ); 參數：DstAddr-目的地址NWKAddrOfInterest -遠程節點的16位

25、網絡地址SecuritySuite -安全要求返回值：ZStatus_t-狀態2.1.4.8 ZDP_NodeDescMsg()調用此函數響應節點描述符的請求。函數原型：afStatus_t ZDP_NodeDescMsg( byte TransSeq, zAddrType_t *dstAddr, byte Status, uint16 nwkAddr, NodeDescriptorFormat_t *pNodeDesc, byte SecuritySuite );參數：TranSeq-傳輸序號DstAddr-目的地址Status - ZDP_SUCCESS=0， ZDP_DEVICE_NOT_FOUND=1nwkAddr已明確的遠程節點的16位網絡地址pNodeDesc 節點描述符SecuritySuite 安全要求返回值：ZStatus_t-狀態2.1.4.9節點描述符請求和響應應用舉例分析節點描述符包含ZigBee節點的功能信息，每個節點