Z-Stack 概述：

Z-Stack 是德州儀器（Texas Instrument）的半開源 Zigbee 協議棧。Z-Stack 2.5.1a 是其發布的最后一個獨立發行版；所謂「獨立發行版」，即，提供的版本里，既包括了諸如智能家居的 Home Automation profile 相關內容，也包括了諸如集中抄表的 Smart Energy profile 相關內容，通俗地講，大雜燴。往后的 Z-Stack，則是捆綁在單獨的 profile 里，不再提供單獨下載。為何采取這種策略？（以下是個人理解）還得先說說 Zigbee 誕生的初衷。Zigbee 原本是為了解決低功耗局域網的互操作性問題，而誕生的一個基于 802.15.4 層的協議。假設，你家里的燈泡采取了 SmartBlub 協議（胡謅的名字），空氣凈化設備使用了私有 AirCleaner 協議，集中控制器則是 SmartController 協議，那么恭喜你，雞同鴨講的窘狀，在你家的「智能家居」之間發生了。遇上如此惱火的事情，你當然會把這群「智能設備」罵一遍。為了避免高素質的你受委屈，Zigbee 誕生了：燈泡們，空調們，大伙都使用 Zigbee 協議，大家好才是真的好！然而，世界是復雜的。除了智能家居，還有很多需要互聯互通互操作的領域，如能源管理，醫療，建筑自動化。你會問，如此多迥異的應用場景，彼此也會有不同的拓撲和通信需求，同一套 Zigbee 協議，可以滿足全部的場景嗎？Zigbee 響亮地吼道「五大受損一個對策」，Zigbee 為了應對這些不同的場景，其不得不折騰了若干不同的 profile（配置）。

Z-Stack的使用：

使用方法簡介：一般情況下用戶只需要額外添加三個文件就可以完成一個項目。一個是主文件，存放具體的任務事件處理函數；一個是這個主文件的頭文件；另外一個是以Osal開頭的操作系統接口文件，是專門存放任務處理函數數組tasksArr[]的文件。這樣就實現了Z-Stack代碼的公用，用戶只需要添加這幾個文件，編寫自己的任務處理函數就可以了。

1.學習ZigBee操作系統抽象層應用程序編程接口。

2.剖析一個簡單的例程學習使用Z-Stack。

下面工作一一弄明白：

（1）頭文件----參考例程添加頭文件。

（2）系統初始化和使用----函數Init和ProcessEvent。

（3）任務建立，調用，切換

（4）中斷配置----熟悉編程接口即可。

（5）定時器使用----熟悉編程接口即可。

（6）驅動文件編寫和調用

（7）網絡建立和加入-->組網

（8）電源管理----節能配置----熟悉編程接口即可。

（9）編寫程序----使用五向按鍵控制四個LED燈（先看懂Simple例程）。

有選擇的讀代碼：

需要讀的代碼：APP（全部代碼）；HAL和Zmain的全部或部分代碼。

其他：熟悉編程接口和使用方法。

一、Z-Stack 操作系統抽象層應用程序編程接口：

1、信息管理API：

信息管理 API 為任務和處理單元之間的信息交換提供了一種具有不同處理環境的機制（例如，在一個控制循環中調用中斷服務常規程序或函數）。這個 API 中的函數可以使任務分配或回收信息緩沖區，給其它任務發送命令信息以及接收回復信息。API包括四個函數：

（1） osal_msg_allocate ()：分配一個信息緩沖；

（2） osal_msg_deallocate()：回收一個信息緩沖區；

（3） osal_msg_send()：發送命令或數據信息；

（4） osal_msg_receive()：檢索/接收一條已收到的命令信息；

1、任務同步API：

這個 API 使得任務等待事件發生，并在等待期間返回控制。這個 API 中的函數可以用來為一個任務設置事件，并無論設置了什么事件都通知任務。僅有一個函數osal_set_event()：用來為一個任務設置事件標志。

2、定時器管理API：

這個API使得內部的（Z-Stack）任務和外部的（應用層）任務都可以使用定時器。API提供了啟動和停止一個定時器的功能，這定時器可設定遞增的一毫秒。

（1）osal_start_timer()：啟動一個定時器；

（2）osal_start_timerEx()：增加了taskID參數。它允許訪問者調用程序為另一個任務設置定時器；

（3）osal_stop_timer()：調用函數用來停止一個已啟動的定時器；

（4）osal_stop_timerEx()：用來停止一個已啟動的定時器；

（5）osal_GetSystemClock()：讀取系統時鐘。

4、中斷管理 API：

此API使得一個任務可以與外部中斷相互交流。API 中的函數允許和每個中斷去聯絡一個具體的服務例程。中斷可以啟用或禁用。在服務例程內部，可以為其它任務設置事件。

（1）osal_int_enable()：啟用一個中斷；

（2）osal_int_disable()：禁用一個中斷。

5、任務管理 API：

在OSAL系統中，API常用于添加和管理任務。每個任務由初始化函數和事件處理函數組成。OSAL調用osalInitTasks()(應用程序提供)去初始化這任務且 OSAL 運用一個任務列表(const pTaskEventHandlerFntasksArr[])去為每個任務(也是應用程序提供)調用事件處理程序。

（1）osal_init_system()：初始化OSAL系統，在使用任何其它OSAL函數之前必須先調用此函數啟動OSAL系統。

（2）osal_start_system()：任務系統中的主循環函數。它將檢查所有的任務事件且為含有該事件的任務調用任務事件處理函數。假如有特定任務的事件，這個函數將為該任務調用事件處理例程來處理事件。相應任務的事件處理例程一次處理一個事件。一個事件被服務后，剩余的事件將等待下一次循環。如果這沒有事件(服務與所有任務)，這個函數使處理器程序處于睡眠模式。

6、內存管理 API：

該API 代表一個簡單的內存分配系統。這些函數允許動態存儲內存分配。

（1） osal_mem_alloc()：一個簡單的內存分配函數，如果分配成功則返回一個指向緩沖區的指針；

（2） osal_mem_free()：釋放存儲空間便于再次運用。

7、電源管理 API：

當它安全關閉接收器和外部硬件時，這個系統為應用程序或任務提供了一種告知OSAL的方法。接著使處理器轉入睡眠。

（1）osal_pwrmgr_device()：當升高電源或需要改變電源時（例如電池支持的協調器）這個函數應由中心控制實體（比如ZDO）調用。

（2）osal_pwrmgr_task_state()：無論這個任務是否想要保護電源，每個任務都將調用此函數。任務將調用此函數來表決是否需要OSAL保護電源或推遲電源保護。默認情況下，當一個任務被創建時，它自己的電源狀態設置為保護模式。如果該任務一直想要保護電源，就根本不必調用此函數。

8、非易失性存儲器（NV）的 API：

描述了OSAL非易失性存儲器系統。該系統為應用程序提供了一種把信息永久保存到設備內存的方法。它還能用于ZigBee規范要求的把某些項目永久保存到協議棧。NV函數的職能是讀寫任意數據類型的用戶自定義項目，比如結構體和數組。用戶能通過設置適當的偏移和長度來讀和寫一個整體的項目或元素。API獨立于NV存儲介質，并且能用于實現閃存或EEPROM。

每個易失性的項目都僅有一個ID，當一些ID值由棧或平臺保留或運用時，應用程序中有特定一系列的ID值。假如應用程序創建自己的易失性項目，它必須從應用范圍的值內選擇一個標識符。參考下面的列表：

（1）osal_nv_item_init()：初始化NV項目，這個函數檢查存在NV的項目，假如不存在，它將通過這個函數去創建或初始化。

（2）osal_nv_read()：從NV中讀出數據。這個函數能用來從NV 中帶有偏移的索引指向的項目讀出整個項目或一個元素。讀出的數據復制到*buf中。

（3）osal_nv_write()：寫入數據到NV，這個函數用來通過帶有偏移的索引指向項目的偏移量來寫入整個NV項目。

（4）osal_offsetof()：計算一個結構體內元素的內存偏移量，以字節為單位。

二、Zigbee啟動過程：

1、Zigbee啟動過程詳見前面Page3。

2、Zigbee啟動過程總結：

（1）Zmain.c文件中包含程序入口main()函數。

（2）main()函數主要做了做了兩件工作，一個是系統初始化，即有啟動代碼來初始化硬件系統和軟件架構需要的各個模塊，另一個作用是執行操作系統實體---main函數最后調用函數Osal_start_system()來啟動操作系統。

（3）用戶如何編寫應用程序：

一般用戶只需額外添加三個文件即可完成一個項目：主文件---SampleApp.c，存放具體的任務事件處理函數；主文件的頭文件---SampleApp.h；第三個是以Osal開頭的操作系統接口文件---OSAL_SampleApp.c，是專門存放任務處理函數數組tasksArr[]的文件。這樣就實現了Z-Stack代碼的公用，用戶只需要添加這幾個文件，編寫自己的任務處理函數就可以了。

（4）SampleApp例程中分為四個部分：DemoEB、CoordinatorEB、RouterEB和EndDeviceEB，在按鍵發送閃爍試驗中僅僅使用了DemoEB。

3、一個完整的初始化過程（按鍵發送閃爍實驗）：

main()-->osal_init_system()-->osalInitTasks()-->SampleApp_Init(task_id)

涉及的文件為：ZMain.c、OSAL.c、OSAL_SampleApp.c和SampleApp.c，也就是啟動文件-->系統文件-->系統接口文件-->應用程序。

4、一個完整的任務/事件處理過程（按鍵發送閃爍實驗）：

main() --> osal_start_system() --> osal_run_system() --> tasksArr --> SampleApp_ProcessEvent()；同樣是：啟動文件-->系統文件-->系統接口文件-->應用程序；其中osal_start_system是個無限循環：for(;;)。

1、操作系統接口文件---OSAL_SampleApp.c（按鍵發送閃爍實驗）：

主要是定義了結構體：函數指針數組tasksArr（包含SampleApp_ProcessEvent）和任務初始化函數osalInitTasks；其中tasksArr在OSAL.c中被調用：events=(tasksArr[idx])(idx,events)à此語句就是調用了函數指針數組中的一個函數，(tasksArr[idx])為函數名，(idx,events)位函數的參數（任務號和事件），events為返回值。

2、SampleApp_Init()---按鍵發送閃爍實驗：

（1）通用應用程序任務初始化函數，這個函數在初始化過程中被調用，該函數應該包含任何特定于應用程序的初始化（即硬件初始化/設置，表的初始化，電源初始化等等）。

（2）自己編寫應用初始化函數可以在這個函數基礎上添加其他初始化函數。

3、SampleApp_ProcessEvent()---按鍵發送閃爍實驗：

（1）通用應用程序任務事件處理函數。這個函數被調用處理任務的所有事件。事件類型包括定時器、信息和其他用戶定義的事件（如Key事件）。

（2）自己編寫事件處理函數可以在這個函數基礎上添加其他用到的事件。

7、SimpleApp：

（1）分為四部分：ControllerEB、CollectorEB、SensorEB和SwitchEB；其中按鍵控制LED例程使用了ControllerEB（協調器）和SwitchEB（終端節點）；無線測溫實驗使用了SensorEB（終端節點）和CollectorEB（協調器）；

（2）sapi.c和sapi.h：相當于操作系統接口文件---OSAL_SampleApp.c；

（3）按鍵控制LED全過程：

按下SimpleControllerEB的up鍵建立zigbee網絡-->按下SimpleControllerEB的up鍵允許別的模塊對其綁定-->按下SimpleSwitchEB的up鍵搜索網絡并加入到網絡-->再次按下SimpleSwitchEB的up鍵與SimpleControllerEB建立綁定-->交替按下SimpleSwitchEB的right鍵來控制SimpleControllerEB模塊的LED1的交替亮滅。

（4）按鍵控制LED程序解讀：

---SimpleControllerEB的zb_AllowBind(myAllowBindTimeout ) -->允許綁定

---SimpleSwitchEB的zb_BindDevice()-->建立綁定

---SimpleSwitchEB的zb_SendDataRequest（0xFFFE, TOGGLE_LIGHT_CMD_ID, ******）-->發送閃燈指令

---sapi.c中的SAPI_ProcessEvent調用osal_msg_receive-->接收指令并執行

---SAPI_ProcessEvent函數位于函數數組tasksArr中被輪詢調用。

---AF_INCOMING_MSG_CMD-->SAPI_ReceiveDataIndication-->zb_ReceiveDataIndication-->最終調用HalLedSet(HAL_LED_1, HAL_LED_MODE_TOGGLE)使LED1閃爍

8、網絡建立（組網—建立網絡和節點加入網絡）：

osal_init_system()-->osalInitTasks()-->ZDApp_Init(taskID++)--> ZDOInitDevice(0)--> ZDApp_NetworkInit( extendedDelay )用于啟動連接網絡 --> osal_start_timerEx --> osal_start_system() --> osal_run_system()--> tasksArr --> ZDApp_event_loop(位于函數數組tasksArr中)--> ZDO_StartDevice --> NLME_NetworkFormationRequest（路由器或終端節點請求）--> ZDO_NetworkFormationConfirmCB（協調器確認）--> osal_set_event --> 回到ZDApp_event_loop--> ZDO_UpdateNwkStatus -->網絡已建立。

9、按鍵發送閃爍實驗---先看懂再改寫：

（1） SampleApp_Init：初始化讀跳線（IO口電平）判斷節點/設備類型。

（2） SampleApp_ProcessEvent：事件處理函數，會被循環調用；功能是接收其他節點發來的消息或指令，其中包括按鍵指令（有按鍵按下），然后調用按鍵處理函數進行相應的操作；接收消息事件是指接收到消息或者指令。

（3） SampleApp_HandleKeys：按鍵操作函數，處理所有的按鍵事件（按鍵是指本節點的按鍵）。

（4） SampleApp_SendFlashMessage(SAMPLEAPP_FLASH_DURATION)：此函數發送閃爍命令（組播），調用函數AF_DataRequest發送數據。

（5） aps_FindGroup ( SAMPLEAPP_ENDPOINT,SAMPLEAPP_FLASH_GROUP )：該節點是否位于本組之中；

aps_RemoveGroup(SAMPLEAPP_ENDPOINT, SAMPLEAPP_FLASH_GROUP )：如果節點位于本組，則從本組中移除。

（6）SampleApp_MessageMSGCB：調用HalLedBlink函數實現閃燈，閃爍四次，周期為250ms，占空比50%。

（7）按鍵操作總結：

KEY_CHANGE事件：按鍵按下也被封裝成一條消息，但并非是其他節點發送的消息；消息不代表無線通信接收到數據。

10、無線測溫實驗---先看懂再改寫：

（1）發送流程：main() --> osal_start_system() --> osal_run_system() --> tasksArr -->SAPI_ProcessEvent --> zb_HandleOsalEvent --> myApp_ReadTemperature --> zb_SendDataRequest --> AF_DataRequest。

（2）接收流程：main() --> osal_start_system() --> osal_run_system() --> tasksArr -->SAPI_ProcessEvent --> AF_INCOMING_MSG_CMD --> SAPI_ReceiveDataIndication --> zb_ReceiveDataIndication --> osal_memcpy --> MT_ProcessEvent --> MT_ProcessIncomingCommand --> 串口發送函數HalUARTWrite。

（3）函數解讀：

11、透明傳輸實驗---先看懂再改寫：

（1）初始化：

main() --> osal_init_system() --> osalInitTasks() --> SerialApp_Init()

（2）發送流程：

main() --> osal_start_system() --> osal_run_system() --> tasksArr --> SerialApp_ProcessEvent -->SerialApp_Send()--> HalUARTRead--> AF_DataRequest

（3）接收流程：

main() --> osal_start_system() --> osal_run_system() --> tasksArr --> SerialApp_ProcessEvent --> AF_INCOMING_MSG_CMD --> SerialApp_ProcessMSGCmd

編輯：黃飛