华为IoT平台NB编解码插件开发详细教程【上篇】

0、前言

一、环境搭建

1.1 安装JDK

1.2 安装eclipse

1.3 安装Maven

二、Profile说明

三、插件编写

3.1 源文件说明

3.2 修改文件路径（包含）

3.3 修改pom.xml

3.4 导入工程

3.5 代码实现

3.6 生成jar包

0、前言

本教程分为上、下篇，原作者是我的同事llb90，征得其同意后在这里再次发布，希望能帮到有需求的人，demo可在Github下载。

本文通过一个比较简单又不失全面的例子，说明一下华为IoT平台编解码插件线下开发的整个开发流程。对于环境的搭建尽量一笔带过，对核心编码部分做比较详细的讲解。第二章Profile部分会先出给一个小例子作为demo，编解码的编写按照该pfofile中定义的字段来解析，以方便大家理解编解码插件中的代码。本文编写过程中主要参考了“华为IoT平台NB-IoT设备集成开发指南.pdf”。

一、环境搭建

开发编解码插件使用的IDE是eclipse，语言是Java。本文尽量以简单的方式告诉你如何将华为提供的编解码样例修改为适合自己的编解码插件。即使你没有什么Java基础，只要懂得编程逻辑就好。跟着一起来吧！

1.1 安装JDK

JDK版本1.8以上。参考网络教程：https://blog.csdn.net/u010058695/article/details/100983213

1.2 安装eclipse

下载并安装eclipse。eclipse下载后解压缩到本地即可运行。

1.3 安装Maven

下载地址是： http://maven.apache.org/download.cgi 下载后的文件解压缩即可，然后添加环境变量。

在eclipse中配置maven插件。打开eclipse，点击window->Preferences，弹出如下窗口：

在弹出的窗口左侧栏中，依次找到并点击Maven->Installations，在右侧点击Add按钮，弹出如下图所示窗口：

点击Directory，选择Maven的路径，然后Finish。到此，Maven配置完成。

二、Profile说明

Profile实际上是一系列关于设备模型的描述文件，每个文件都使用JSON格式（键值对）。

Profile中首先需要说明设备的基本信息，包括厂商ID，厂商名称，设备类型，接入协议，以及设备可以提供的哪些服务等；其次，profile中要针对每一项服务，用一个独立的文件进行详细描述。服务，可以理解为是对设备消息（上下行）功能的一个分类，一个服务就代表一类功能；每个服务下包含若干属性和命令，每个属性对应上报消息中的某一个数据，每个命令字段则对应下行消息中的某些字段。比如，一个电表设备，会上报电池电量、功率、电能、电压等，可以将电池电量放在Battery服务中，属性值为batteryLevel，将功率、电能、电压都放在Transmission服务中，分别对应该服务下的Power、Energy、Voltage属性。可以在一条消息中上报所有服务的所有属性，也可以分开上报。

本例中提供的profile信息，基本信息如下：

设备类型： MyType
设备型号： MyModel
厂商ID  ： ThirdParty
厂商名称： ThirdParty
协议：     Coap

数据服务有两项：Battery，包含一个属性BatteryLevel，两个字节；Transmission，包含一个属性upData，不定长数组（profile中表示不定长数组，需将属性类型定义为string，长度设为一个比较大的数）；包含一条下行命令CLOUDREQ，有两个命令字段；cmdType，一个字节；downData，不定长数组。

profile采用在线开发的方式，如下图所示：

本例中，采用一条消息上报所有服务属性的方式。上报数据格式为：前两个字节表示batteryLevel属性，大端方式；第三个字节表示后续数据长度；第四个字节至最后，表示upData属性。下行命令数据格式为：第一个字节表示cmdType；第二个字节至最后，表示downData。（请仔细理解该数据格式，插件的编写就是按照数据格式解析出对应的属性值）。

三、插件编写

3.1 源文件说明

从华为资源中心下载编解码插件Demo，并解压到本地。文件结构如下图所示：

源代码在src文件夹下；编译生成的插件包在target文件夹下。src 文件夹包含 main 、test 两个子文件夹，main下存放源码，test下是单元测试代码。官网下载的Demo中，源码的路径是：src\main\java\com\Huawei\NBIoTDevice\WaterMeter，单元测试代码的路径是：src\test\java\com\Huawei\NBIoTDevice\WaterMeter。

插件源码文件有5个：

（a）ProtocolAdapterImpl.java 可以理解为是插件的入口文件，对外提供调用接口。该文件只需要修改两个字符串的定义即可：

// 厂商名称
private static final String MANU_FACTURERID = "Huawei";
// 设备型号
private static final String MODEL = "NBIoTDevice";

修改为profile当中定义的厂商ID和设备型号。

（b）CmdProcess.java 实现下行命令的编码工作，将从收到的服务器报文中提取出命令字段对应的内容，并将其转换成字节流。需要实现的函数是：

public byte[] toByte()

（c）ReportProcess.java 实现将收到的二进制码流按照格式解码出对应profile中的属性值，并生成JSON格式。需要实现的函数是：

//根据二进制码流的格式，从中取出对应字节，转换成profile中对应属性的值
public ReportProcess(byte[] binaryData)
//将解码出来的属性值封装成JSON格式
public ObjectNode toJsonNode()

（d）ByteBufUtils.java 和 Utilty.java文件封装了一些公共方法，不用做修改。也不会使用到。

3.2 修改文件路径（包含）

插件包名的要求是：com.厂商名称.设备型号.设备类型。因此下载下来的代码，要根据自己的设备修改下文件路径。即将Huawei文件夹重命名为profile中定义的厂商名称，NBIoTDevice文件夹重命名为profile中定义的设备型号，WaterMeter文件夹重命名为profile中定义的设备类型。注意：src\main 和src\test 下都要修改。在本例中，需要修改为：

src\main\java\com\ThirdParty\MyModel\MyTyp，
src\test\java\com\ThirdParty\MyModel\MyType

3.3 修改pom.xml

打开pom.xml文件，修改第7行“artifactId”和第88行“Bundle-SymbolicName”的值为：设备类型-厂商ID-设备型号。在本例中，需要修改为：MyType-ThirdParty-MyModel。

3.4 导入工程

打开eclipse，点击file->import，在弹出窗口中选择maven工程，如下图所示：

之后在弹出的窗口中，点击Browse，选择工程路径（pom.xml文件所在路径）。工程导入后如下图所示：

从图8可以看到首次导入工程后是有错误的。这是因为我们在第2节中将文件路径修改了，与代码里面的包路径不一致引起的。解决方法为：依次打开源文件，将第一行的

package com.Huawei.NBIoTDevice.WaterMeter;

修改为

package com.ThirdParty.MyModel.MyType;

打开OSGI_INF目录下的CodeProvideHandler.xml 文件：

打开后，文件内容如下图所示：

将Name 、 Class* 内的路径也修改为对应的包路径：

3.5 代码实现

前面说明了各个源文件要修改的地方，本节中具体讲解实现的方法。

（a）修改ProtocolAdatpterImpl.java文件

在文件中找到如下两行：

// 厂商名称
private static final String MANU_FACTURERID = "Huawei";
// 设备型号
private static final String MODEL = "NBIoTDevice";

将MANU_FACTURERID 和 MODEL定义修改为profile中定义的厂商ID和设备型号，本例中需要修改为：

// 厂商名称
private static final String MANU_FACTURERID = "ThirdParty";
// 设备型号
private static final String MODEL = "MyModel";

（b）解码实现

解码，是将NB模组上报的二进制码流按格式解析出对应字段的过程。解码的代码在ReportProcess.java 文件中。

第一个函数：public ReportProcess(byte[] binaryData) 入参 byte[] binaryData就是NB模组上报的二进制码流。解码得到数据存储在成员变量当中。本例中的代码实现如下：

NB上报二进制数据的格式为：前两个字节表示batteryLevel，大端，整型；第三个字节表示后边还有多少字节；第四个字节往后表示不定长字段upData。因此，解码的思路便是：

首先判断数据长度是否合法，至少应为3个字节，对应第37行代码；数据长度应不小于第3个字节的值加上3，对应第42行代码。该部分代码属于保护性代码。
将前两个字节拼成一个16位的整型数据，表示batteryLevel，对应第47行代码。
根据第三个字节的值，创建一个Byte数组，将第四个字节往后的内容拷贝至该数组内，得到upData。对应第50~53行代码。

System.arraycopy 是JDK提供的数组拷贝函数:第一个参数是源数组，第二个参数是偏移，表示从源数组的第几个字节开始拷贝，第三个参数是目的数组，第四个参数是目的数组的偏移，第5个参数表示拷贝的长度。

第二个函数：public ObjectNode toJsonNode() 返回一个ObjectNode对象（JSON）。该函数的功能，是将解码后得到的数据，按照规定格式填入一个JSON对象中。本例中，生成的JSON对象的内容格式如下图所示：

JSON对象的内容格式要求是："msgType": "deviceReq", 表示设备上报数据，固定不动；“data”：数组对象，数组中的每个元素分别对应profile中的一个服务；“serviceID”的值是profile中定义的服务名称；“serviceData”的值是该服务下所有的属性值。（本例中，profile定义了两个服务，Battery服务中有一个BatteryLevel属性;Transmission服务中有一个upData属性）。由图13的“upData”的值可以看出，数组类型的值，需要将二进制流转成base64编码的格式。

该函数的代码实现如下图所示：