# 离线开发插件
编解码插件实现二进制格式与JSON格式相互转换或JSON格式之间的转换，产品模型定义了该JSON格式的具体内容。因此，编解码插件开发前需要先编写设备的产品模型。
为了提高离线开发的集成效率，我们提供了编解码插件的[编解码插件样例](https://support.huaweicloud.com/devg-iothub/iot_02_1004.html#ZH-CN_TOPIC_0187644975__section1768205153119)，建议您基于DEMO工程进行二次开发。
![](https://support.huaweicloud.com/devg-iothub/public_sys-resources/note_3.0-zh-cn.png)
- 2023年8月1日后新用户不再提供离线插件功能。
- 由于插件离线开发较为复杂，且耗时比较长，推荐使用[图形化开发插件](https://support.huaweicloud.com/devg-iothub/iot_02_0008.html)。
 
#### 开发环境准备
- 前往[官网](https://www.eclipse.org/downloads)下载Eclipse安装包，直接解压缩到本地即可使用。
- 前往[官网](https://maven.apache.org/download.cgi)下载Maven插件包（zip格式），直接解压缩到本地。
- 安装JDK并配置Java的开发环境。
Maven的配置涉及Windows环境变量的配置与在Eclipse中的配置，环境变量的配置请参考网上资源，本节仅介绍Maven在Eclipse中的配置。
1. 选择Eclipse菜单"Windows"-\>"Preferences"，打开Preferences窗口，选择"Maven"-\>"Installations"-\>"Add"。 
   ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650576.jpg)
   
   
2. 选择maven插件包路径，单击"Finish"，导入Maven插件。 
   ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650577.jpg)
   
   
3. 选择导入的maven插件，单击"OK"。 
   ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650578.jpg)
   
   
 
#### 导入编解码插件Demo工程
1. 下载编解码插件DEMO工程，在"source_code"文件夹中获取"codecDemo.zip"，将其解压到本地。 
   ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650579.png)
   
   
2. 打开Eclipse，右击Eclipse左侧"Project Explorer"空白处，选择"Import \> Import..."。 
   ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650580.png)
   
   
3. 展开"Maven"，选择"Existing Maven Projects"，单击"Next"。 
   ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650581.jpg)
   
   
4. 单击"Browse"，选择步骤1解压获得的"codecDemo"文件夹，勾选"/pom.xml"，单击"Finish"。 
   ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650582.jpg)
   
   
 
#### 实现样例讲解
导入的编解码插件Demo工程结构如下图所示。
![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650583.png)
本工程是一个Maven工程，您可在此样例工程的基础上修改如下部分，适配成自己需要的编解码插件。
1. 修改Maven的配置文件 
   ```
   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.thrid.party</groupId>
   <!-- 请修改为编解码插件的名字，命名规范：设备类型-厂商ID，例如：WaterMeter -Huawei -->
   <artifactId>WaterMeter-Huawei</artifactId>
   <version>1.0.0</version>
   <!-- 请检查这里的值为bundle，不能为jar -->
   <packaging>bundle</packaging>
   ......
   <dependencies>
   ......
       <!-- Huawei提供的编解码接口，必须引入 -->
       <!-- systemPath请替换成您本地的目录 \codecDemo\lib\com.huawei.m2m.cig.tup-1.3.1.jar -->
       <dependency>
           <groupId>com.huawei</groupId>
           <artifactId>protocol-jar</artifactId>
           <version>1.3.1</version>
           <scope>system</scope>
           <systemPath>${basedir}/lib/com.huawei.m2m.cig.tup-1.3.1.jar</systemPath>
       </dependency>
   ......
   </dependencies>
   <build>
   <plugins>
       <!-- OSGI规范打包配置 -->
       <plugin>
           <configuration>
               <instructions>
                   <!-- 请修改为编解码插件的名字，命名规范：设备类型-厂商ID，例如：WaterMeter-Huawei -->
                   <Bundle-SymbolicName>WaterMeter-Huawei</Bundle-SymbolicName>
                   <Import-Package></Import-Package>
               </instructions>
           </configuration>
       </plugin>
   </plugins>
   </build>
   </project>
   ```
   ![](https://support.huaweicloud.com/devg-iothub/public_sys-resources/note_3.0-zh-cn.png)
   Maven的配置文件中，"Import-Package"标签中只能引用如下八个包：
   - org.slf4j
   
   - org.slf4j.spi
   
   - org.apache.log4j.spi
   
   - com.huawei.m2m.cig.tup.modules.protocol_adapter
   
   - com.fasterxml.jackson.databind
   
   - com.fasterxml.jackson.databind.node
   
   - org.osgi.framework
   
   - org.osgi.util.tracker
    
   
   
2. 在ProtocolAdapterImpl.java中，修改厂商ID（MANU_FACTURERID）的取值。 
   ```
   private static final Logger logger = LoggerFactory.getLogger(ProtocolAdapterImpl.class);
   // 厂商名称
   private static final String MANU_FACTURERID = "Huawei";
   ```
   
   
3. 修改CmdProcess.java中的代码，实现插件对下发命令和上报数据响应的编码能力。 
   ```
   package com.Huawei.NBIoTDevice.WaterMeter;
   import com.fasterxml.jackson.databind.JsonNode;
   import com.fasterxml.jackson.databind.node.ObjectNode;
   public class CmdProcess {
       //private String identifier = "123";
       private String msgType = "deviceReq";
       private String serviceId = "Brightness";
       private String cmd = "SET_DEVICE_LEVEL";
       private int hasMore = 0;
       private int errcode = 0;
       private int mid = 0;
       private JsonNode paras;
       public CmdProcess() {
       }
       public CmdProcess(ObjectNode input) {
           try {
               // this.identifier = input.get("identifier").asText();
               this.msgType = input.get("msgType").asText();
               /*
               平台收到设备上报消息，编码ACK
               {
                   "identifier":"0",
                   "msgType":"cloudRsp",
                   "request": ***,//设备上报的码流
                   "errcode":0,
                   "hasMore":0
               }
               * */
               if (msgType.equals("cloudRsp")) {
                   //在此组装ACK的值
                   this.errcode = input.get("errcode").asInt();
                   this.hasMore = input.get("hasMore").asInt();
               } else {
               /*
               平台下发命令到设备，输入
               {
                   "identifier":0,
                   "msgType":"cloudReq",
                   "serviceId":"WaterMeter",
                   "cmd":"SET_DEVICE_LEVEL",
                   "paras":{"value":"20"},
                   "hasMore":0
               }
               * */
                   //此处需要考虑兼容性，如果没有传mId，则不对其进行编码
                   if (input.get("mid") != null) {
                       this.mid = input.get("mid").intValue();
                   }
                   this.cmd = input.get("cmd").asText();
                   this.paras = input.get("paras");
                   this.hasMore = input.get("hasMore").asInt();
               }
           } catch (Exception e) {
               e.printStackTrace();
           }
       }
       public byte[] toByte() {
           try {
               if (this.msgType.equals("cloudReq")) {
                   /*
                   应用服务器下发的控制命令，本例只有一条控制命令：SET_DEVICE_LEVEL
                   如果有其他控制命令，增加判断即可。
                   * */
                   if (this.cmd.equals("SET_DEVICE_LEVEL")) {
                       int brightlevel = paras.get("value").asInt();
                       byte[] byteRead = new byte[5];
                       ByteBufUtils buf = new ByteBufUtils(byteRead);
                       buf.writeByte((byte) 0xAA);
                       buf.writeByte((byte) 0x72);
                       buf.writeByte((byte) brightlevel);
                       //此处需要考虑兼容性，如果没有传mId，则不对其进行编码
                       if (Utilty.getInstance().isValidofMid(mid)) {
                           byte[] byteMid = new byte[2];
                           byteMid = Utilty.getInstance().int2Bytes(mid, 2);
                           buf.writeByte(byteMid[0]);
                           buf.writeByte(byteMid[1]);
                       }
                       return byteRead;
                   }
               }
               /*
               平台收到设备的上报数据，根据需要编码ACK，对设备进行响应，如果此处返回null，表示不需要对设备响应。
               * */
               else if (this.msgType.equals("cloudRsp")) {
                   byte[] ack = new byte[4];
                   ByteBufUtils buf = new ByteBufUtils(ack);
                   buf.writeByte((byte) 0xAA);
                   buf.writeByte((byte) 0xAA);
                   buf.writeByte((byte) this.errcode);
                   buf.writeByte((byte) this.hasMore)
                   return ack;
               }
               return null;
           } catch (Exception e) {
               // TODO: handle exception
               e.printStackTrace();
               return null;
           }
       }
   }
   ```
   
   
4. 修改ReportProcess.java中的代码，实现插件对设备上报数据和命令执行结果的解码能力。 
   ```
   package com.Huawei.NBIoTDevice.WaterMeter;
   import com.fasterxml.jackson.databind.ObjectMapper;
   import com.fasterxml.jackson.databind.node.ArrayNode;
   import com.fasterxml.jackson.databind.node.ObjectNode;
   public class ReportProcess {
       //private String identifier;
       private String msgType = "deviceReq";
       private int hasMore = 0;
       private int errcode = 0;
       private byte bDeviceReq = 0x00;
       private byte bDeviceRsp = 0x01;
       //serviceId=Brightness字段
       private int brightness = 0;
       //serviceId=Electricity字段
       private double voltage = 0.0;
       private int current = 0;
       private double frequency = 0.0;
       private double powerfactor = 0.0;
       //serviceId=Temperature字段
       private int temperature = 0;
       private byte noMid = 0x00;
       private byte hasMid = 0x01;
       private boolean isContainMid = false;
       private int mid = 0;
       /**
        * @param binaryData 设备发送给平台coap报文的payload部分
        *                   本例入参：AA 72 00 00 32 08 8D 03 20 62 33 99
        *                   byte[0]--byte[1]:  AA 72 命令头
        *                   byte[2]:   00 mstType 00表示设备上报数据deviceReq
        *                   byte[3]:   00 hasMore  0表示没有后续数据，1表示有后续数据，不带按照0处理
        *                   byte[4]--byte[11]:服务数据，根据需要解析//如果是deviceRsp,byte[4]表示是否携带mid, byte[5]--byte[6]表示短命令Id
        * @return
        */
       public ReportProcess(byte[] binaryData) {
           // identifier参数可以根据入参的码流获得，本例指定默认值123
           // identifier = "123";
           /*
           如果是设备上报数据，返回格式为
           {
               "identifier":"123",
               "msgType":"deviceReq",
               "hasMore":0,
               "data":[{"serviceId":"Brightness",
                         "serviceData":{"brightness":50},
                         {
                         "serviceId":"Electricity",
                         "serviceData":{"voltage":218.9,"current":800,"frequency":50.1,"powerfactor":0.98},
                         {
                         "serviceId":"Temperature",
                         "serviceData":{"temperature":25},
                         ]
       }
       */
           if (binaryData[2] == bDeviceReq) {
               msgType = "deviceReq";
               hasMore = binaryData[3];
               //serviceId=Brightness 数据解析
               brightness = binaryData[4];
               //serviceId=Electricity 数据解析
               voltage = (double) (((binaryData[5] << 8) + (binaryData[6] & 0xFF)) * 0.1f);
               current = (binaryData[7] << 8) + binaryData[8];
               powerfactor = (double) (binaryData[9] * 0.01);
               frequency = (double) binaryData[10] * 0.1f + 45;
               //serviceId=Temperature 数据解析
               temperature = (int) binaryData[11] & 0xFF - 128;
           }
           /*
           如果是设备对平台命令的应答，返回格式为：
          {
               "identifier":"123",
               "msgType":"deviceRsp",
               "errcode":0,
               "body" :{****} 特别注意该body体为一层json结构。
           }
       */
           else if (binaryData[2] == bDeviceRsp) {
               msgType = "deviceRsp";
               errcode = binaryData[3];
               //此处需要考虑兼容性，如果没有传mId，则不对其进行解码
               if (binaryData[4] == hasMid) {
                   mid = Utilty.getInstance().bytes2Int(binaryData, 5, 2);
                   if (Utilty.getInstance().isValidofMid(mid)) {
                       isContainMid = true;
                   }
               }
           } else {
               return;
           }
       }
       public ObjectNode toJsonNode() {
           try {
               //组装body体
               ObjectMapper mapper = new ObjectMapper();
               ObjectNode root = mapper.createObjectNode();
               // root.put("identifier", this.identifier);
               root.put("msgType", this.msgType);
               //根据msgType字段组装消息体
               if (this.msgType.equals("deviceReq")) {
                   root.put("hasMore", this.hasMore);
                   ArrayNode arrynode = mapper.createArrayNode();
                   //serviceId=Brightness 数据组装
                   ObjectNode brightNode = mapper.createObjectNode();
                   brightNode.put("serviceId", "Brightness");
                   ObjectNode brightData = mapper.createObjectNode();
                   brightData.put("brightness", this.brightness);
                   brightNode.put("serviceData", brightData);
                   arrynode.add(brightNode);
                   //serviceId=Electricity 数据组装
                   ObjectNode electricityNode = mapper.createObjectNode();
                   electricityNode.put("serviceId", "Electricity");
                   ObjectNode electricityData = mapper.createObjectNode();
                   electricityData.put("voltage", this.voltage);
                   electricityData.put("current", this.current);
                   electricityData.put("frequency", this.frequency);
                   electricityData.put("powerfactor", this.powerfactor);
                   electricityNode.put("serviceData", electricityData);
                   arrynode.add(electricityNode);
                   //serviceId=Temperature 数据组装
                   ObjectNode temperatureNode = mapper.createObjectNode();
                   temperatureNode.put("serviceId", "Temperature");
                   ObjectNode temperatureData = mapper.createObjectNode();
                   temperatureData.put("temperature", this.temperature);
                   temperatureNode.put("serviceData", temperatureData);
                   arrynode.add(temperatureNode);
                   //serviceId=Connectivity 数据组装
                   ObjectNode ConnectivityNode = mapper.createObjectNode();
                   ConnectivityNode.put("serviceId", "Connectivity");
                   ObjectNode  ConnectivityData = mapper.createObjectNode();
                   ConnectivityData.put("signalStrength", 5);
                   ConnectivityData.put("linkQuality", 10);
                   ConnectivityData.put("cellId", 9);
                   ConnectivityNode.put("serviceData", ConnectivityData);
                   arrynode.add(ConnectivityNode);
                   //serviceId=battery 数据组装
                   ObjectNode batteryNode = mapper.createObjectNode();
                   batteryNode.put("serviceId", "battery");
                   ObjectNode batteryData = mapper.createObjectNode();
                   batteryData.put("batteryVoltage", 25);
                   batteryData.put("battervLevel", 12);
                   batteryNode.put("serviceData", batteryData);
                   arrynode.add(batteryNode);
                   root.put("data", arrynode);
               } else {
                   root.put("errcode", this.errcode);
                   //此处需要考虑兼容性，如果没有传mid，则不对其进行解码
                   if (isContainMid) {
                       root.put("mid", this.mid);//mid
                   }
                   //组装body体，只能为ObjectNode对象
                   ObjectNode body = mapper.createObjectNode();
                   body.put("result", 0);
                   root.put("body", body);
               }
               return root;
           } catch (Exception e) {
               e.printStackTrace();
               return null;
           }
       }
   }
   ```
   
   
 
#### decode接口说明
decode接口的入参binaryData为设备发过来的CoAP报文的payload部分。
![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650584.png "点击放大")
设备的上行报文有两种情况需要插件处理（消息**④**是模组回复的协议ACK，无需插件处理）：
- 设备上报数据（对应图中的消息**①** ）
  
  | 字段名         | 类型         | 是否必填 | 参数描述                                                                                                                                                                                                                                                         |
  |:---|:---|:---|:---|
  | identifier | String     | 否     | 设备在应用协议里的标识，物联网平台通过decode接口解析码流时获取该参数，通过encode接口编码时将该参数放入码流。                                                                                                                                                                                                |
  | msgType      | String      | 是      | 固定值"deviceReq"，表示设备上报数据。                                                                                                                                                                                                                                    |
  | hasMore    | Int        | 否     | 表示设备是否还有后续数据上报，0表示没有，1表示有。 后续数据是指，设备上报的某条数据可能分成多次上报，在本次上报数据后，物联网平台以hasMore字段判断后续是否还有消息。hasMore字段仅在PSM模式下生效，当上报数据的hasMore字段为1时，物联网平台暂时不下发缓存命令，直到收到hasMore字段为0的上报数据，才下发缓存命令。如上报数据不携带hasMore字段，则物联网平台按照hasMore字段为0处理。 |
  | data        | ArrayNode | 是     | 设备上报数据的内容。                                                                                                                                                                                                                                                   |
     
  表1ArrayNode定义 
  | 字段名        | 类型         | 是否必填 | 参数描述                                                                                          |
  |:---|:---|:---|:---|
  | serviceId  | String      | 是    | 服务的id。                                                                                        |
  | serviceData | ObjectNode | 是  | 一个服务的数据，具体字段在产品模型里定义。                                                                         |
  | eventTime  | String    | 否 | 设备采集数据时间（格式：yyyyMMddTHHmmssZ）。 如：20161219T114920Z。 |
     
  **示例**：
  ```
  {
      "identifier": "123",
      "msgType": "deviceReq",
      "hasMore": 0,
      "data": [{
  "serviceId": "NBWaterMeterCommon",
  "serviceData": {
      "meterId": "xxxx",
      "dailyActivityTime": 120,
      "flow": "565656",
      "cellId": "5656",
      "signalStrength": "99",
      "batteryVoltage": "3.5"
  },
  "eventTime": "20160503T121540Z"
      },
      {
  "serviceId": "waterMeter",
  "serviceData": {
  "internalTemperature": 256
  },
  "eventTime": "20160503T121540Z"
      }]
  }
  ```
  ![](https://support.huaweicloud.com/devg-iothub/public_sys-resources/note_3.0-zh-cn.png)
  LwM2M协议的数据格式跟MQTT的数据格式不同。
  
- 设备对平台命令的应答（对应图中的消息**⑤** ）
  
  | 字段名       | 类型         | 参数描述                                                                                                                                                                                                                                                                                 | 是否必填 |
  |:---|:---|:---|:---|
  | identifier | String   | 设备在应用协议里的标识，物联网平台通过decode接口解析码流时获取该参数，通过encode接口编码时将该参数放入码流。                                                                                                                                                                                                                         | 否     |
  | msgType   | String      | 固定值"deviceRsp"，表示设备的应答消息。                                                                                                                                                                                                                                                           | 是   |
  | mid         | Int        | 2字节无符号的命令id。在设备需要返回命令执行结果（deviceRsp）时，用于将命令执行结果（deviceRsp）与对应的命令进行关联。 物联网平台在通过encode接口下发命令时，把物联网平台分配的mid放入码流，和命令一起下发给设备；设备在上报命令执行结果（deviceRsp）时，再将此mid返回给物联网平台。否则物联网平台无法将下发命令和命令执行结果（deviceRsp）进行关联，也就无法根据命令执行结果（deviceRsp）更新命令下发的状态（成功或失败）。 | 是      |
  | errcode     | Int      | 请求处理的结果码，物联网平台根据该参数判断命令下发的状态。 0表示成功，1表示失败。                                                                                                                                                                                                    | 是   |
  | body       | ObjectNode | 命令的应答，具体字段由产品模型定义。 **注**：body体不是数组。                                                                                                                                                                                                        | 否     |
     
  **示例**：
  ```
  { 
      "identifier": "123", 
      "msgType": "deviceRsp", 
      "mid": 2016, 
      "errcode": 0, 
      "body": { 
          "result": 0 
      } 
  }
  ```
  
 
#### encode接口说明
encode接口的入参是JSON格式的数据，是平台下发的命令或应答。
![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650586.png "点击放大")
平台的下行报文可以分为两种情况：
- 平台对设备上报数据的应答（对应图中的消息**②** ）
  表2平台收到设备的上报数据后对设备的应答encode接口的入参结构定义 
  | 字段名        | 类型         | 参数描述                                                                                                                                        | 是否必填 |
  |:---|:---|:---|:---|
  | identifier | String    | 设备在应用协议里的标识，物联网平台通过decode接口解析码流时获取该参数，通过encode接口编码时将该参数放入码流。                                                                                | 否     |
  | msgType   | String     | 固定值"cloudRsp"，表示平台收到设备的数据后对设备的应答。                                                                                                              | 是     |
  | request   | byte\[\] | 设备上报的数据。                                                                                                                                    | 是     |
  | errcode  | int       | 请求处理的结果码，物联网平台根据该参数判断命令下发的状态。 0表示成功，1表示失败。                                                       | 是     |
  | hasMore    | int      | 表示平台是否还有后续消息下发，0表示没有，1表示有。 后续消息是指，平台还有待下发的消息，以hasMore字段告知设备不要休眠。hasMore字段仅在PSM模式下生效，且需要"下行消息指示"开启。 | 是   |
     
  ![](https://support.huaweicloud.com/devg-iothub/public_sys-resources/note_3.0-zh-cn.png)
  LwM2M协议的命令下发格式和MQTT协议的命令下发格式不一样。
  **注**：在cloudRsp场景下编解码插件检测工具显示返回null时，表示插件未定义上报数据的应答，设备侧不需要物联网平台给予响应。
  **示例**：
  ```
  { 
      "identifier": "123", 
      "msgType": "cloudRsp", 
      "request": [ 
          1, 
          2 
      ], 
      "errcode": 0, 
      "hasMore": 0 
  }
  ```
  
- 平台命令下发（对应图中的消息**③** ）
  表3平台下发命令encode接口的入参结构定义 
  | 字段名         | 类型         | 参数描述                                                                                                                                                                                                                                             | 是否必填 |
  |:---|:---|:---|:---|
  | identifier | String       | 设备在应用协议里的标识，物联网平台通过decode接口解析码流时获取该参数，通过encode接口编码时将该参数放入码流。                                                                                                                                                                                       | 否       |
  | msgType       | String     | 固定值"cloudReq"，表示平台下发的请求。                                                                                                                                                                                                                        | 是     |
  | serviceId    | String     | 服务的id。                                                                                                                                                                                                                                          | 是       |
  | cmd          | String       | 服务的命令名，参见产品模型的服务命令定义。                                                                                                                                                                                                                             | 是     |
  | paras       | ObjectNode | 命令的参数，具体字段由产品模型定义。                                                                                                                                                                                                                              | 是     |
  | hasMore       | Int         | 表示平台是否还有后续命令下发，0表示没有，1表示有。 后续命令是指，平台还有待下发的消息，以hasMore字段告知设备不要休眠。hasMore字段仅在PSM模式下生效，且需要"下行消息指示"开启。                                                                                                       | 是     |
  | mid       | Int       | 2字节无符号的命令id，由物联网平台内部分配（范围1-65535）。 物联网平台在通过encode接口下发命令时，把物联网平台分配的mid放入码流，和命令一起下发给设备；设备在上报命令执行结果（deviceRsp）时，再将此mid返回物联网平台。否则物联网平台无法将下发命令和命令执行结果（deviceRsp）进行关联，也就无法根据命令执行结果（deviceRsp）更新命令下发的状态（成功或失败）。 | 是    |
     
  **示例**：
  ```
  { 
      "identifier": "123", 
      "msgType": "cloudReq", 
      "serviceId": "NBWaterMeterCommon", 
      "mid": 2016, 
      "cmd": "SET_TEMPERATURE_READ_PERIOD", 
      "paras": { 
          "value": 4 
      }, 
      "hasMore": 0} 
  }
  ```
  
 
#### getManufacturerId接口说明
返回厂商ID字符串。物联网平台通过调用该接口获取厂商ID。
示例：
```
@Override 
public String getManufacturerId() { 
    return "TestUtf8ManuId"; 
}
```
#### 接口实现注意事项
**接口需要支持线程安全**
decode和encode函数需要支持线程安全，不得添加成员变量或静态变量来缓存过程数据。
- 错误示例：多线程并发时A线程将status设置为"Failed"，B线程可能会同时设置为"Success"，从而导致**status** 不正确，引起程序运行异常。
  ```
  public class ProtocolAdapter {
  private String status;
  @Override
  public ObjectNode decode(finalbyte[] binaryData) throws Exception {
      if (binaryData == null) {
          status = "Failed";
          return null;
      }
      ObjectNode node;
      ...;
      status = "Success";// 线程不安全
      return node;
  }
  }
  ```
  
- 正确示例：直接使用入参编解码，编解码库不做业务处理。
**mid字段的解释**
物联网平台是依次进行命令下发的，但物联网平台收到命令执行结果响应的次数未必和命令下发的次序相同，mid就是用来将命令执行结果响应和下发的命令进行关联的。在物联网平台，是否实现mid，消息流程也有所不同：
- **实现mid**
  ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650588.png "点击放大")
  若实现了mid，并且命令执行结果已上报成功，则：
  1. 命令执行结果响应中的状态（SUCCESSFUL/FAILED）会刷新到平台数据库中该命令的记录；
  
  2. 平台推送给应用服务器的命令执行结果通知中携带commandId；
  
  3. 应用服务器查询会得到该命令的状态为SUCCESSFUL/FAILED。
   
- **不实现mid**
  ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0237650589.png "点击放大")
  若不实现mid，并且命令执行结果已上报成功，则：
  1. 命令执行结果响应中的状态（SUCCESSFUL/FAILED）不会刷新到平台数据库中该命令的记录；
  
  2. 平台推送给应用服务器的命令执行结果通知中不携带commandId；
  
  3. 应用服务器查询会得到该命令的最终状态为DELIVERED。
   
![](https://support.huaweicloud.com/devg-iothub/public_sys-resources/note_3.0-zh-cn.png)
上述两个消息流程旨在解释mid字段的作用，部分消息流程在图中简化处理。
针对只关注命令是否送达设备，不关注设备对命令执行情况的场景，设备和编解码插件不需要实现对mid的处理。
如果不实现mid，则应用服务器不能在物联网平台获取命令的执行结果，需要应用服务器自行实现解决方案。比如应用服务器在收到命令执行结果响应（不带commandId）后，可以根据如下方法来进行响应匹配：
- 根据命令下发的顺序。使用此方法，平台在对同一设备同时下发多条命令时，一旦发生丢包，将会导致命令执行结果和已下发的命令匹配错误。因此，建议应用服务器每次对同一设备仅下发一条命令，在收到命令执行结果响应后，再下发下一条命令。
- 编解码插件可以在命令响应消息的resultDetail里加上命令的相关信息来帮助识别命令，比如命令码。应用服务器根据resultDetail里的信息来识别命令执行结果响应和已下发命令的对应关系。
 
**禁止使用DirectMemory**
DirectMemory是直接调用操作系统接口申请内存，不受JVM的控制，使用不当很容易造成操作系统内存不足，因此编解码插件代码中禁止使用DirectMemory。
错误示例：使用UNSAFE.allocateMemory申请直接内存
```
if ((maybeDirectBufferConstructor instanceof Constructor))
{
      address = UNSAFE.allocateMemory(1L);
      Constructor<?> directBufferConstructor;
      ...
}
else
{
      ...
}
```
#### 编解码插件的输入/输出格式样例
假定某款水表支持的服务定义如下：
| 服务类型    | 属性名称              | 属性说明        | 属性类型（数据类型） |
|:---|:---|:---|:---|
| Battery | -                 | -           | -          |
| -       | batteryLevel      | 电量(0--100)% | int        |
| Meter   | -                 | -           | -          |
| -       | signalStrength    | 信号强度        | int        |
| -       | currentReading    | 当前读数        | int        |
| -       | dailyActivityTime | 日激活通讯时长     | string     |
   
那么数据上报时decode接口的输出：
```
{
    "identifier": "12345678",
    "msgType": "deviceReq",
    "data": [
        {
            "serviceId": "Meter",
            "serviceData": {
                "currentReading": "46.3",
                "signalStrength": 16,
                "dailyActivityTime": 5706
            },
            "eventTime": "20160503T121540Z"
        },
        {
            "serviceId": "Battery",
            "serviceData": {
                "batteryLevel": 10
            },
            "eventTime": "20160503T121540Z"
        }
    ]
}
```
收到数据上报后，平台对设备的应答响应，调用encode接口编码，输入为
```
{
    "identifier": "123",
    "msgType": "cloudRsp",
    "request"：[
        1,
        2
    ],
    "errcode": 0,
    "hasMore": 0
}
```
假定某款水表支持的命令定义如下：
| 基本功能名称     | 分类  | 名称                              | 命令参数   | 数据类型 | 枚举值                   |
|:---|:---|:---|:---|:---|:---|
| WaterMeter | 水表  | -                               | -      | -    | -                     |
| -          | CMD | SET_TEMPERATURE_READ_PERIOD     | -      | -    | -                     |
| -          | -   | -                               | value  | int  | -                     |
| -          | RSP | SET_TEMPERATURE_READ_PERIOD_RSP | -      | -    | -                     |
| -          | -   | -                               | result | int  | 0表示成功，1表示输入非法，2表示执行失败 |
   
那么命令下发调用encode接口时，输入为
```
{
    "identifier": "12345678",
    "msgType": "cloudReq",
    "serviceId": "WaterMeter",
    "cmd": "SET_TEMPERATURE_READ_PERIOD",
    "paras": {
        "value": 4
    },
    "hasMore": 0
}
```
收到设备的命令应答后，调用decode接口解码，解码的输出
```
{
    "identifier": "123",
    "msgType": "deviceRsp",
    "errcode": 0,
    "body": {
        "result": 0
    }
}
```
#### 编解码插件打包
插件编程完成后，需要使用Maven打包成jar包，并制作成插件包。
**Maven打包**
1. 打开DOS窗口，进入"pom.xml"所在的目录。
2. 输入maven打包命令：mvn package。
3. DOS窗口中显示"BUILD SUCCESS"后，打开与"pom.xml"目录同级的target文件夹，获取打包好的jar包。 
   jar包命名规范为：设备类型-厂商ID-版本.jar，例如：WaterMeter-Huawei-version.jar。
   ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0241376547.png)
   - com目录存放的是class文件。
   
   - META-INF下存放的是OSGI框架下的jar的描述文件（根据pom.xml配置生成的）。
   
   - OSGI-INF下存放的是服务配置文件，把编解码注册为服务，供平台调用（只能有一个xml文件）。
   
   - 其他jar是编解码引用到的jar包。
   
   
   
   
**制作插件包**
1. 新建文件夹命名为"package"，包含一个"preload/"子文件夹。
2. 将打包好的jar包放到"preload/"文件夹。 
   ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0241516870.png)
   
   
3. 在"package"文件夹中，新建"package-info.json"文件。该文件的字段说明和模板如下： 
   **注：** "package-info.json"需要以UTF-8无BOM格式编码。仅支持英文字符。
   表4"package-info.json"字段说明 
   | 字段名            | 字段描述                                                                                       | 是否必填 |
   |:---|:---|:---|
   | specVersion    | 描述文件版本号，填写固定值："1.0"。                                                                        | 是    |
   | fileName        | 软件包文件名，填写固定值："codec-demo"                                                                     | 是    |
   | version      | 软件包版本号。描述package.zip的版本，请与下面的bundleVersion取值保持一致。                                            | 是     |
   | deviceType      | 设备类型，与产品模型文件中的定义保持一致。                                                                         | 是    |
   | manufacturerName | 制造商名称，与产品模型文件中的定义保持一致，否则无法上传到平台。                                                               | 是    |
   | platform      | 平台类型，本插件包运行的物联网平台的操作系统，填写固定值："linux"。                                                        | 是     |
   | packageType     | 软件包类型，该字段用来描述本插件最终部署的平台模块，填写固定值："CIGPlugin"。                                                 | 是     |
   | date           | 出包时间，格式为："yyyy-MM-dd HH-mm-ss"，如"2017-05-06 20:48:59"。                                       | 否   |
   | description   | 对软件包的自定义描述。                                                                                 | 否   |
   | ignoreList     | 忽略列表，默认为空值。                                                                                 | 是   |
   | bundles       | 一组bundle的描述信息。 **注**：bundle就是压缩包中的jar包，只需要写一个bundle。 | 是    |
      
   表5bundles的字段说明 
   | 字段名          | 字段描述                                      | 是否必填 |
   |:---|:---|:---|
   | bundleName  | 插件名称，和上文中pom.xml的Bundle-SymbolicName保持一致。 | 是   |
   | bundleVersion | 插件版本，与上面的version取值保持一致。                   | 是 |
   | priority     | 插件优先级，可赋值默认值：5。                         | 是 |
   | fileName   | 插件jar的文件名称。                               | 是    |
   | bundleDesc  | 插件描述，用来介绍bundle功能。                       | 是  |
   | versionDesc | 插件版本描述，用来介绍版本更迭时的功能特性。                  | 是  |
      
   **package-info.json**文件模板：
   ```
   { 
       "specVersion":"1.0", 
       "fileName":"codec-demo", 
       "version":"1.0.0", 
       "deviceType":"WaterMeter", 
       "manufacturerName":"Huawei", 
       "description":"codec", 
       "platform":"linux", 
       "packageType":"CIGPlugin", 
       "date":"2017-02-06 12:16:59", 
       "ignoreList":[], 
       "bundles":[ 
       { 
           "bundleName": "WaterMeter-Huawei", 
           "bundleVersion": "1.0.0", 
           "priority":5, 
           "fileName": "WaterMeter-Huawei-1.0.0.jar", 
           "bundleDesc":"", 
           "versionDesc":"" 
       }] 
   }
   ```
   
   
4. 选中"package"文件夹中的全部文件，打包成zip格式（"package.zip"）。 
   **注：**"package.zip"中不能包含"package"这层目录。
   
   
![](https://support.huaweicloud.com/devg-iothub/public_sys-resources/note_3.0-zh-cn.png)
离线插件包最大限制为4M，如果超出4M，请自行分析并将包大小裁剪到4M以内。