Z-Stack Home Developer's Guide—2. Overview中文翻译【Z-Stack Home 1.2.0开发文档】
下面是Z-Stack Home 1.2.0開發資料中的Z-Stack Home Developer’s Guide—2. Overview的中文翻譯
2.1 簡介
這章節將介紹 Z-Stack協議棧的示例程序。 每一個Z-Stack協議棧的示例程序都是為了實現一個特定的應用程序 使用zigbee協議?？梢苑浅：唵蔚拈_始。
這個章節將作為一個通用的概述。 需要一個動手的用戶指南， 請參閱Z-Stack Home Sample Application User’s Guide [3]。
每個樣本應用程序都使用ZDO公共接口的最小子集，以使設備在ZigBee網絡中具有相當的可行性。 另外， 所有的樣例程序都利用基本的OSAL API 函數： 網絡和內部任務之間的交流， 通過發送和接受消息， 設置和接受任務事件， 設置和接受定時器回調， 使用動態內存， 以及其他的。 除此之外， 每個示例程序會使用HAL API 函數， 例如。 為了控制 LED’s。 因此， 任何樣例應用程序都是復制和粘貼的一個很好的例子， 或者作為用戶應用程序的基本代碼 可以添加額外的應用程序對象。
任何應用程序對象都一定是位于唯一端點的頂部; 任何端點都是由一個簡單的描述符定義的。
示例應用程序中的簡單描述符中用于端點的數字可以任意選擇的。
每個示例應用程序實例化一個應用程序對象， 因此， 僅支持相應的Profile。 但是請注意，2個或者更多的應用程序對象可以在相同的設備上實例化。 當在同一個設備中實例化多個應用程序對象時，每個應用程序對象必須實現一個唯一的Profile Id，并在頂部設置唯一的端點編號。 示例應用程序滿足唯一Id和端點編號需求并且能組成到一個設備中只要比較小的修改。
以下段落描述了OSAL 任務：
2.1.1 Initialization
OSAL是有意的作為分配源，這樣通過Z-Stack用戶整個OSAL的功能就可以被修改了。
設計的目標是為使用Z-Stack as distributed修改OSAL并不是必須的。 有一個除外—OSAL Task 初始化函數， osalInitTasks()， 一定要被用戶實現。 示例程序在專用的文件中已經實現， 名字的命名規則： OSAL_”Application Name”.c (比如 OSAL_SampleLight.c)。 BSP將調用osalInitTasks()函數 作為開發板上電的一部分和Z-Stack初始化過程。
2.1.2 Organization
詳細的描述在 Z-Stack OSAL API [5] 文檔中， OSAL實現了一個合作， 循環任務服務循環。每一個Z-Stack主子系統運行作為一個OSAL任務。 用戶運行的應用程序必須創建至少一個OSAL任務。 添加他們的任務到任務數組[tasksArr 定義在 OSAL_”Application Name”.c] 文件中，調用他們的應用程序的初始化函數在osalInitTask()中。
樣例程序很清晰的展示了用戶如何添加一個任務到OSAL系統中。
2.1.3 Task Priority
這些任務執行的順序是根據他們在任務數組中的位置[tasksArr in OSAL_”Application Name”.c]。 任務數組的第一個任務擁有最高優先級。
2.1.4 System Services
OSAL 和 HAL 系統服務 是 鍵盤 (按下開關) 通知 和 串口活動通知。系統服務是專一的， 也就是說，每一個都可以被注冊為一個單一的OSAL任務。 不同的系統服務可以通過相同的OSAL任務注冊， 或者不同的OSAL 任務。 默認，任何的系統服務都沒有注冊Z-Stack任務 – 他們都是留給用戶自己注冊。
2.1.5 Application Design
用戶可以一個應用程序實例創建一個任務也可以所有的應用程序實例創建一個任務。 以下是在進行上述設計選擇時的一些考慮事項。
2.1.5.1 One OSAL Task per many Application Objects
以下是一個任務對應多個App實例的優點和缺點：
優點： 在接收單一的任務事件（開關或串行端口）時所采取的操作被簡化了。
優點： 許多OSAL任務結構所需的堆空間被保存
缺點： 當接收到傳入的AF消息或AF數據確認時所采取的操作是復雜的。
– 多路復用的負擔是在單個用戶任務上的。
缺點： 匹配描述符請求（即自動匹配）的服務發現過程更加復雜
–必須維護一個靜態的本地標志，以便在ZDO_NEW_DSTADDR消息時正確地執行
2.1.5.2 One OSAL Task per one Application Object
這個一個task對應一個App對象的優缺點剛好和上面的一個task對應許多的App對象相反：
- 優點： 傳入的AF消息或AF數據確認已經取消多路復用靠協議棧的底層， 因此接收應用程序對象是預期接收方。
- 缺點： 許多OSAL任務結構所需的堆空間發生了
- 缺點： 如果兩個或更多應用程序對象使用相同的獨占資源時，當接收到一個單獨的任務事件時所采取的操作可能會更加復雜。
2.1.6 Mandatory Methods
任何的OSAL任務都必須實現2個方法：一個是任務初始化函數另一個是處理任務事件的函數。
2.1.6.1 Task Initialization
在樣例程序中，任務初始化的函數命名規則：zcl“Application Name”_Init (比如 zclSampleLight_Init())。任務初始化函數應該完成以下：
- 初始化本地變量或相應的應用程序對象。 任何長期在堆內存的變量應該在這里分配空間，為了讓OSAL更高效的管理堆空間。
- 通過在AF層注冊來實例化相應的應用程序對象（比如 afRegister()）。
- 使用可適用的OSAL或HAL系統服務注冊 (比如 RegisterForKeys())。
2.1.6.2 Task Event Handler
在示例程序中，事件處理函數的命名規則：zcl“Application Name”_event_loop (比如 zclSampleLight_event_loop())。任何OSAL任務都可以除了強制性事件之外，還可以定義15個事件。
2.1.7 Mandatory Events
一個任務事件，SYS_EVENT_MSG (0x8000)，被保留，是OSAL 任務設計的。
2.1.7.1 SYS_EVENT_MSG (0x8000)
全局的系統消息發送通過SYS_EVENT_MSG，具體指定在ZComDef.h文件中。任務事件處理程序應該處理以下這些全局系統消息的最小子集。建議處理以下消息應該直接從樣例程序代碼學習或者研究樣例程序的程序流程。
2.1.7.1.1 AF_DATA_CONFIRM_CMD
這表明 每個over-the-air數據請求成功，通過調用AF_DataRequest()。ZSuccess確認數據請求成功地通過無線傳輸。數據請求是用AF_ACK_REQUEST標志設置的，然后ZSuccess確認消息是在最終目的地成功接收。否則，ZSuccess只會確認消息是成功地傳送到下一站。
2.1.7.1.2 AF_INCOMING_MSG_CMD
這是一個傳入的AF消息的指示
2.1.7.1.3 KEY_CHANGE
表明有按鍵活動
2.1.7.1.4 ZDO_STATE_CHANGE
表明網絡狀態發生改變
2.1.7.1.5 ZDO_CB_MSG
這是發送到示例應用程序的每一個注冊的ZDO響應消息[ZDO_RegisterForZDOMsg]
2.2 Network Formation
作為一個協調器編譯的樣例應用程序將在一個通道上形成一個網絡，通過指定DEFAULT_CHANLIST。協調器將建立一個隨機的Pan ID基于自己的own IEEE地址或者通過ZDAPP_CONFIG_PAN_ID，如果它沒有定義為0xFFFF。作為路由器或終端編譯的樣例應用程序設備將嘗試在DEFAULT_CHANLIST指定的一個通道上加入一個網絡。路由器將被限制只加入Pan ID定義。注意，獲得的結果是不確定的，由于 當ZDAPP_CONFIG_PAN_ID沒有定義為0xFFFF，協調器和路由或終端設備 之間的行為是不同的。如果ZDAPP_CONFIG_PAN_ID定義為一個有效的值小于等于0xFFFE，那么協調器只會嘗試建立一個帶指定Pan ID的網絡。因此，如果協調器被限制為一個通道，指定的Pan Id已經在該通道上建立了，新開始的協調員將會連續的變化，直到它達到一個惟一的Pan Id。新加入的路由器或終端設備將無法知道建立PanID的值，因此只會加入指定的Pan Id。同樣具有挑戰性的場景出現在 當允許的信道掩碼允許多個通道，協調器不能使用第一個通道由于Pan ID沖突 — 路由器或終端設備將加入指定的Pan ID 在第一個channel 被scan，如果被允許的話。
2.2.1 Auto Start
一個設備將自動開始嘗試形成或加入一個網絡作為BSP 啟動序列的一部分。如果在連接之前，設備應該等待計時器或其他外部事件，HOLD_AUTO_START一定要被定義。為了在以后的時間手動啟動連接過程，調用ZDOInitDevice()。
2.2.2 Network Restore
成功加入網絡的設備可以“恢復網絡”（而不是重置通過OTA信息）即使在失去電源或電池之后。這種自動恢復可以通過定義NV_RESTORE或NV_INIT實現。
2.2.3 Join Notification
該設備被告知網絡形成或連接（或網絡狀態的任何變化）的狀態，通過前面提到的ZDO_STATE_CHANGE消息。
2.3 Common Application Framework / Program Flow
本節描述所有樣本應用程序通用的初始化和主任務處理概念。在 轉到樣例程序之前，應該先閱讀本部分內容。對于本節中的代碼示例，我們將使用SampleLightApp，在 Z-Stack Home已經提供了。
2.3.1 Initialization
在系統啟動和初始化期間，任務的初始化函數將被調用。這個函數的結構如下所示，加上一些代碼示例：
zclSampleLight_TaskID = task_id;
任務ID由OSAL分配，并通過任務的init函數的參數賦予任務。應用程序必須記住這個任務id，因為它會在以后進行自我觸發 通過使用OSAL定時器，事件，消息（比如 當任務給它自己發送一個消息）。這種自我觸發通常是將長時間處理分割成更小的塊，然后在他們之間延期調用。這種“合作”行為允許其他任務共享CPU時間并防止“饑餓”.
zclHA_Init( & zclSampleLight_SimpleDesc );
這個SampleLightApp程序對象實例化通過上面的代碼，這允許Af層知道如何路由到目標profile/endpoint的數據包 — 它將通過發送一個OSAL SYS_EVENT_MSG 消息(AF_INCOMING_MSG_CMD)到任務來做到這一點。
RegisterForKeys( zclSampleLight_TaskID );
示例程序用上面的代碼注冊 按鍵通知的系統服務。
2.3.2 Event Processing
當樣例應用程序發生OSAL事件時，事件處理函數，將從OSAL任務處理循環中調用。任務事件處理程序的參數是一個16位位掩碼；在任何對函數的調用中都可以設置一個或多個位。如果設置了多個事件，那么它強烈建議一個任務只對其中一個事件采取行動（可能最關鍵的一個，幾乎總是，SYS_EVENT_MSG時優先級最高的一個）。未處理的事件將導致新的調用這個任務事件處理程序在所有其他處理程序之后都有機會處理它們的事件。
if ( events & SYS_EVENT_MSG )
{
MSGpkt = (afIncomingMSGPacket_t*)osal_msg_receive(zclSampleLight_TaskID );
while ( MSGpkt )
{
…
請注意，盡管建議一個任務只在可能的多個未決事件中的一個上執行任務處理功能的調用，它也被推薦（并在示例應用程序中實現）處理所有可能出現的SYS_EVENT_MSG消息，所有這些消息都位于OSAL的“時間片”中。
switch ( MSGpkt->hdr。event )
建議一個任務實現SYS_EVENT_MSG消息可能類型的最小子集，這個推薦的子集如下所述：
case KEY_CHANGE：
zclSampleLight_HandleKeys ( ((keyChange_t *)MSGpkt)->state，
((keyChange_t *)MSGpkt)->keys );
break;
如果一個OSAL任務已經注冊了按鍵通知，所有的按鍵將受到一個 KEY_CHANGE系統事件消息。程序流程有兩種可能的路徑，它會導致一個任務接收到這個KEY_CHANGE消息。
從物理按鍵上產生的程序流如下所列：
- HAL發現了按鍵狀態（通過H/W中斷或者 H/W輪休 ）
- HAL 的OSAL任務發現了 按鍵狀態改變然后調用 OSAL 按鍵改變的回調函數。
- OSAL 按鍵改變回調函數將發送 OSAL 系統事件消息（KEY_CHANGE）到這個注冊 接受key change event(RegisterForKeys)通知 的Task ID。
case AF_DATA_CONFIRM_CMD：
// The status is of ZStatus_t type [defined in ZComDef.h]
// The message fields are defined in AF.h
afDataConfirm = (afDataConfirm_t *)MSGpkt;
sentEP = afDataConfirm->endpoint;
sentStatus = afDataConfirm->hdr。status;
sentTransID = afDataConfirm->transID;
任何對AF_DataRequest（）的調用都會返回ZSuccess，這將導致“回調”
AF_DATA_CONFIRM_CMD系統事件消息。
發送的事務Id（sentTransID）是識別消息的一種方法。盡管示例應用程序只會使用單個事務Id計數器，為每個不同的短點保留一個單獨的Transaction Id計數器可能是有用的 或者 即使是為了消息確認，端點中的每個集群ID也是如此，重試，拆開，在組裝，等。注意任何事務ID狀態變量（counter）通過調用AF_DataRequest()增長當這個函數調用成功（因此，它是一個傳入參數 通過引用，而不是值傳遞）。
AF_DataRequest()的返回值是ZSuccess表示，這條信息已經被網絡層接受，網絡層試圖將它發送到Mac層，Mac試圖將通過OTA發送。
發送的狀態（句子狀態）是OTA這個消息的結果。ZSuccess表示 消息被傳送到網絡中下一跳的ZigBee設備。如果AF_DataRequest() 調用使用AF_ACK_REQUEST標志，然后ZSuccess表示消息被遞送到目標地址。除非消息的尋址模式是間接的（比如 消息被發送到網絡反射器來執行
綁定表格查找并將消息重新發送到匹配設備），在這種情況下，ZSuccess表示消息被傳送到網絡反射器。有幾種可能的發送狀態值表示失敗。
case ZDO_STATE_CHANGE：
zclSampleLight_NwkState = (devStates_t)(MSGpkt->hdr。status);
if ( (zclSampleLight_NwkState == DEV_ZB_COORD) ||
(zclSampleLight_NwkState == DEV_ROUTER) ||
(zclSampleLight_NwkState == DEV_END_DEVICE) )
{
giLightScreenMode = LIGHT_MAINMODE;
。。。
}
break;
每當網絡狀態發生變化時，所有任務都會被通知系統事件消息ZDO_STATE_CHANGE
// Release the memory
osal_msg_deallocate( (uint8 *)MSGpkt );
請注意，OSAL消息系統的設計要求任務接受者釋放 為消息分配的內存。
任務的事件處理函數應該嘗試獲取下一個未決的SYS_EVENT_MSG消息：
// Get the next message
MSGpkt = (afIncomingMSGPacket_t*)osal_msg_receive(zclSampleLight_TaskID);
}
處理完一個事件后，處理函數應該返回未處理的事件，比如 在處理完SYS_EVENT_MSG事件后，應該返回以下內容：
// Return unprocessed events
return ( events ^ SYS_EVENT_MSG);
}
總結
以上是生活随笔為你收集整理的Z-Stack Home Developer's Guide—2. Overview中文翻译【Z-Stack Home 1.2.0开发文档】的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： linux centOS基本配置搭建
- 下一篇： Android Studio 3.1.4