OceanConnect編解碼外掛開發教程
概述
本文共分為四個章節，第一章介紹書寫本文的意圖，編解碼概述，以及書寫編解碼外掛所需的前期準備。
編解碼概述
書寫編解碼外掛之前首先需要書寫Profile檔案，定義如下。
Profile檔案用於描述一款裝置的能力特性。Lot平臺通過解析Profile檔案，獲取該裝置支援的服務（通訊協議裡面的一條完整報文）、屬性（報文中的一個欄位）、命令（報文中的一個欄位）等資訊。
Lot平臺通過編解碼外掛，對NB裝置上報的資料和下發給NB裝置的命令進行格式轉換，即將裝置上報的16進位制格式的報文轉換成json，json資料的具體屬性名稱將由Profile檔案來確定。
前期準備
知識儲備
熟悉javase基礎程式設計，maven專案管理工具基本命令，jackson類庫。
開發工具
Eclipse，jdk1.8，maven，NB裝置通訊協議。
編解碼結構解析
Profile結構
Profile檔案是一個深度為四級的資料夾如圖3‑4所示。
紅色方框中為第一級目錄，目錄名稱為當前專案的名稱，命名規則為：裝置型別-廠商ID-裝置型號，例如WellMonitor_Chinastar_CSiTWLM05，對應圖3‑4功能結構中的Product模組。
綠色方框中為第二級目錄，包含兩個資料夾profile和service。profile資料夾下放置一個devicetype-capability.json，被用來描述一款裝置的能力特徵，包括裝置型別、廠商、型號、協議型別以及提供的服務型別。相當於對當前整個Profile專案資訊的一個概述。service資料夾下則包含裝置具備的服務能力，每個服務具備的屬性、命令以及命令的引數，對應圖3‑4中Service模組。
藍色方框中代表三級目錄，代表具體的服務，每個服務中又包含了屬性和命令，屬性用於描述裝置上報資料，命令用於下發指令給裝置，分別對應圖3‑4中的Property模組和Command模組。
此外只有紅色與藍色方框中檔案的命名可以改動，其他名稱固定不變。
例如圖2‑1service中包含了WellWaterCommand代表井蓋+水位裝置所有的下行命令；WellWaterDeviceInfo代表該裝置上報的裝置資訊；WellWaterTiming代表該裝置定時上報的資訊，共計三個服務。關於如何根據裝置的通訊協議劃分服務，將在第三章中詳細介紹。
圖2‑1 Profile檔案結構
圖2‑2 Profile功能結構
編解碼外掛結構
編解碼外掛使用java開發且jdk版本必須為1.8，maven進行專案管理，建議使用eclipse開發工具。其工程目錄結構如圖3‑4所示。工程的命名建議和Profile專案相同，即採用：裝置型別-廠商ID-裝置型號的格式。其餘包名類名無需更改，即使用華為提供的名稱。
其中下行資料編碼表示該類將平臺下發的json格式的命令轉化為位元組陣列。
上行資料解碼則表示該類將裝置上報的位元組陣列轉化為json格式資料。
主類則負責呼叫下行資料編碼或者上行資料解碼。
工具類中包含了不同資料型別之間轉換的方法。
圖2‑3 編解碼外掛工程結構
編解碼外掛開發
Profile開發
新建工程
新建名稱為：裝置型別-廠商ID-裝置型號的資料夾，例如WellMonitor_Chinastar_CSiTWLM05，開啟該資料夾新建profile和service兩個子資料夾，如圖3‑4所示。注意profile和service這兩個資料夾名稱是固定不變的。
圖3‑1 Profile資料夾
建立概述檔案
開啟profile資料夾新建devicetype-capability.json檔案，編輯該json檔案如圖3‑4所示。其中每個欄位所代表的含義如圖3‑4所示。serviceTypeCapabilities
Json陣列包含了該Profile檔案所有的服務模組，即每增加一個service都需要在這個陣列中新增一個對應的json物件。例如Chinstar公司採用CoAP協議，裝置型號為CSiTWLM05的井蓋裝置包含三個服務（功能）模組，井蓋命令、井蓋開機資訊，井蓋定時上報資訊。
Service劃分
關於一個裝置service的劃分，可以採用根據裝置通訊協議中上報報文的功能碼進行劃分的方法，即協議中一條上報報文對應一個service（通常一條報文佔用一個功能碼）。
Service劃分步驟：
-
將通訊協議中的報文區分為上行資料和下行資料兩類。
-
將下行資料（命令）寫在一個service裡面。
-
將上行資料根據功能碼的不同，分成若干個不同的service。
圖3‑2 Profile概述檔案
圖3‑3 Profile檔案欄位含義
建立service
開啟第二級目錄的service資料夾，根據步驟二devicetype-capability.json檔案中serviceTypeCapabilities陣列中定義的service建立對應的資料夾，資料夾名稱為serviceId對應的值。每個資料夾下分別建立profile資料夾，profile資料夾下建立servicetype-capability.json檔案，用來描述具體服務的功能，如圖3‑4所示。
圖3‑4 service檔案結構
接下來編寫每個service對應的servicetype-capability.json，如圖3‑4所示的Profile，將井蓋水位裝置的所有命令下發模組單獨寫在了一個service中，即WellWaterCommand模組；將裝置的上報資料資訊按照通訊協議中每個報文的功能碼區分為不同的service，即WellWaterDeviceInfo（開機資訊）模組與WellWaterTiming（定時上報）模組。
編寫下行service
下行命令在service中的書寫格式如圖3‑5所示。Commands數組裡面存放若干個命令物件，每個命令物件包含CommandName命令的名稱和paras命令攜帶的引數陣列，以及responses命令迴應陣列。paras數組裡麵包含若干個引數物件。引數物件包含paraName等一系列屬性。這每一個引數物件都對應通訊協議報文中的一個屬性。serviceType的值一定要與當前服務資料夾名稱保持一致。
圖3‑5 命令service
編寫上行service
上行屬性service比命令service要簡單，properties陣列中存放的是裝置上報上來的資料，每一個json物件對應通訊協議報文中的一個屬性。propertyName的值可以隨意定義，dataType的值如不能根據通訊協議中的預設引數值明顯的判斷該屬性的資料型別，應找相關人員確認，否則解析將會出現資料錯誤。
打包Profile
將WellMonitor_Chinastar_CSiTWLM05資料夾下的profile和service檔案打包為zip格式，命名為WellMonitor_Chinastar_CSiTWLM05，並且壓縮包內不能包含WellMonitor_Chinastar_CSiTWLM05資料夾這一層目錄。
編解碼開發
使用eclipse配置本地maven倉庫，並匯入華為提供的demo工程。
修改pom.xml中的<artifactId>XXX</artifactId>和<Bundle-SymbolicName>XXX</Bundle-SymbolicName>命名規範：裝置型別-廠商ID-裝置型號，與Profile檔案保持一致。如圖3‑6、圖3‑7所示。
圖3‑6 pom修改廠商名稱
圖3‑7 pom修改廠商名稱
修改ProtocolAdapterImpl.java中的廠商名稱與裝置型號，注意與Profile保持一致。如圖3‑8所示。
圖3‑8 修改Protocol檔案
編寫下行編碼
資料下行編碼流程如圖3‑9所示，通過獲取OC平臺傳送過來的json資料，首先根據serviceId將對應資料儲存到全域性變數中，然後呼叫toByte方法，將各種型別的資料裝換為16進位制的位元陣列。拼裝成一條完整的報文並返回。其中mid為訊息序號，根據通訊協議中是否使用訊息序號來決定程式碼中是否使用。詳情請參照文末樣例程式碼。
圖3‑9 資料下行編碼流程圖
編寫上行解碼
資料上行解碼流程如圖3‑10所示。通過獲取OC平臺傳送過來的16進位制位元陣列格式資料，首先根據位元陣列中的功能碼（功能碼在資料哪個位置，請從通訊協議中檢視），將不同服務對應的不同資料，根據通訊協議將byte型別的屬性轉換為所需型別，儲存到全域性變數中，然後呼叫toJsonNode方法，拼裝成一個Json物件並返回。其中mid為訊息序號，根據通訊協議中是否使用訊息序號來決定程式碼中是否使用。詳情請參照文末樣例程式碼。
圖3‑10 資料上行解碼流程圖
打包編解碼
打包編解碼，即將該maven工程打包成jar檔案。檢查pom.xml中的<packaging>bundle</packaging>值是否為bundle，不能為jar。以eclipse為例，在工程上右鍵選擇Run
As然後選擇Maven build…如圖3‑11所示。
圖3‑11 Mavenbuild
在Goals中輸入clean package點選Run按鈕，如圖3‑12所示。
圖3‑12 Mavenpackage
等待控制檯出現BUILD
SUCCESS，即可在當前專案的target目錄下找到打包好的jar檔案，如圖3‑13所示，打包編解碼完成。
圖3‑13 Build