设备接入 IoTDA设备接入 IoTDA

计算
弹性云服务器 ECS
裸金属服务器 BMS
云手机 CPH
专属主机 DeH
弹性伸缩 AS
镜像服务 IMS
函数工作流 FunctionGraph
云耀云服务器 HECS
VR云渲游平台 CVR
特惠算力专区
存储
对象存储服务 OBS
云硬盘 EVS
云备份 CBR
弹性文件服务 SFS
存储容灾服务 SDRS
云硬盘备份 VBS
云服务器备份 CSBS
数据快递服务 DES
专属企业存储服务
云存储网关 CSG
专属分布式存储服务 DSS
CDN与智能边缘
内容分发网络 CDN
智能边缘云 IEC
智能边缘小站 IES
智能边缘平台 IEF
人工智能
AI开发平台ModelArts
华为HiLens
图引擎服务 GES
图像识别 Image
文字识别 OCR
自然语言处理 NLP
内容审核 Moderation
图像搜索 ImageSearch
医疗智能体 EIHealth
园区智能体 CampusGo
企业级AI应用开发专业套件 ModelArts Pro
人脸识别服务 FRS
对话机器人服务 CBS
视频分析服务 VAS
语音交互服务 SIS
知识图谱 KG
人证核身服务 IVS
IoT物联网
设备接入 IoTDA
设备管理 IoTDM(联通用户专用)
全球SIM联接 GSL
IoT数据分析 IoTA
路网数字化服务 DRIS
IoT边缘 IoTEdge
设备发放 IoTDP
开发与运维
软件开发平台 DevCloud
项目管理 ProjectMan
代码托管 CodeHub
流水线 CloudPipeline
代码检查 CodeCheck
编译构建 CloudBuild
部署 CloudDeploy
云测 CloudTest
发布 CloudRelease
移动应用测试 MobileAPPTest
CloudIDE
Classroom
开源镜像站 Mirrors
应用魔方 AppCube
云性能测试服务 CPTS
应用管理与运维平台 ServiceStage
云应用引擎 CAE
视频
实时音视频 SparkRTC
视频直播 Live
视频点播 VOD
媒体处理 MPC
视频接入服务 VIS
管理与监管
统一身份认证服务 IAM
消息通知服务 SMN
云监控服务 CES
应用运维管理 AOM
应用性能管理 APM
云日志服务 LTS
云审计服务 CTS
标签管理服务 TMS
资源管理服务 RMS
应用身份管理服务 OneAccess
区块链
区块链服务 BCS
可信跨链服务 TCS
可信分布式身份服务
智能协作
IdeaHub
开发者工具
SDK开发指南
API签名指南
DevStar
HCloud CLI
Terraform
Ansible
云生态
云市场
合作伙伴中心
华为云培训中心
其他
管理控制台
消息中心
产品价格详情
系统权限
我的凭证
客户关联华为云合作伙伴须知
公共问题
宽限期保留期
奖励推广计划
活动
容器
云容器引擎 CCE
云容器实例 CCI
容器镜像服务 SWR
应用编排服务 AOS
多云容器平台 MCP
基因容器 GCS
容器洞察引擎 CIE
云原生服务中心 OSC
容器批量计算 BCE
容器交付流水线 ContainerOps
应用服务网格 ASM
网络
虚拟私有云 VPC
弹性公网IP EIP
弹性负载均衡 ELB
NAT网关 NAT
云专线 DC
虚拟专用网络 VPN
云连接 CC
VPC终端节点 VPCEP
数据库
云数据库 RDS
数据复制服务 DRS
文档数据库服务 DDS
分布式数据库中间件 DDM
云数据库 GaussDB (for openGauss)
云数据库 GaussDB(for MySQL)
云数据库 GaussDB NoSQL
数据管理服务 DAS
数据库和应用迁移 UGO
大数据
MapReduce服务 MRS
数据湖探索 DLI
表格存储服务 CloudTable
可信智能计算服务 TICS
推荐系统 RES
云搜索服务 CSS
数据可视化 DLV
数据湖治理中心 DGC
数据接入服务 DIS
数据仓库服务 GaussDB(DWS)
应用中间件
微服务引擎 CSE
分布式消息服务Kafka版
分布式消息服务RabbitMQ版
API网关 APIG
分布式缓存服务 DCS
分布式消息服务RocketMQ版
企业应用
域名注册服务 Domains
云解析服务 DNS
云速建站 CloudSite
网站备案
商标注册
华为云WeLink
会议
隐私保护通话 PrivateNumber
语音通话 VoiceCall
消息&短信 MSGSMS
云管理网络
SD-WAN 云服务
边缘数据中心管理 EDCM
云桌面 Workspace
应用与数据集成平台 ROMA Connect
ROMA资产中心 ROMAExchange
API全生命周期管理 ROMA API
安全与合规
安全技术与应用
DDoS防护 ADS
Web应用防火墙 WAF
云防火墙 CFW
应用信任中心 ATC
企业主机安全 HSS
容器安全服务 CGS
云堡垒机 CBH
数据库安全服务 DBSS
数据加密服务 DEW
数据安全中心 DSC
云证书管理服务 CCM
SSL证书管理 SCM
漏洞扫描服务 VSS
态势感知 SA
威胁检测服务 MTD
管理检测与响应 MDR
安全治理云图 Compass
认证测试中心 CTC
迁移
主机迁移服务 SMS
对象存储迁移服务 OMS
云数据迁移 CDM
专属云
专属计算集群 DCC
解决方案
高性能计算 HPC
SAP
混合云灾备
华为工业云平台 IMC
价格
成本优化最佳实践
专属云商业逻辑
用户服务
帐号中心
费用中心
成本中心
资源中心
企业管理
工单管理
客户运营能力
国际站常见问题
支持计划
专业服务
合作伙伴支持计划
更新时间:2021-12-24 GMT+08:00
分享

离线开发插件

编解码插件实现二进制消息转JSON格式的功能,产品模型定义了该JSON格式的具体内容。因此,编解码插件开发前需要先编写设备的产品模型。

为了提高离线开发的集成效率,我们提供了编解码插件的编解码插件样例,建议您基于DEMO工程进行二次开发。

:由于插件离线开发较为复杂,且耗时比较长,我们推荐图形化开发

开发环境准备

  • 前往官网下载Eclipse安装包,直接解压缩到本地即可使用。
  • 前往官网下载Maven插件包(zip格式),直接解压缩到本地。
  • 安装JDK并配置Java的开发环境。

Maven的配置涉及Windows环境变量的配置与在Eclipse中的配置,环境变量的配置请参考网上资源,本节仅介绍Maven在Eclipse中的配置。

  1. 选择Eclipse菜单“Windows”->“Preferences”,打开Preferences窗口,选择“Maven”->“Installations”->“Add”。

  2. 选择maven插件包路径,单击“Finish”,导入Maven插件。

  3. 选择导入的maven插件,单击“OK”。

导入编解码插件Demo工程

  1. 下载编解码插件DEMO工程,在“source_code”文件夹中获取“codecDemo.zip”,将其解压到本地。

  2. 打开Eclipse,右击Eclipse左侧“Project Explorer”空白处,选择“Import > Import...”。

  3. 展开“Maven”,选择“Existing Maven Projects”,单击“Next”。

  4. 单击“Browse”,选择步骤1解压获得的“codecDemo”文件夹,勾选“/pom.xml”,单击“Finish”。

实现样例讲解

导入的编解码插件Demo工程结构如下图所示。

本工程是一个Maven工程,您可在此样例工程的基础上修改如下部分,适配成自己需要的编解码插件。

  1. 修改Maven的配置文件

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    <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>protocal-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>
    

    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)的取值。

    1
    2
    3
    private static final Logger logger = LoggerFactory.getLogger(ProtocolAdapterImpl.class);
    // 厂商名称
    private static final String MANU_FACTURERID = "Huawei";
    

  3. 修改CmdProcess.java中的代码,实现插件对下发命令和上报数据响应的编码能力。

      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    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中的代码,实现插件对设备上报数据和命令执行结果的解码能力。

      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    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部分。

设备的上行报文有两种情况需要插件处理(消息是模组回复的协议ACK,无需插件处理):

  • 设备上报数据(对应图中的消息

    字段名

    类型

    是否必填

    参数描述

    identifier

    String

    设备在应用协议里的标识,物联网平台通过decode接口解析码流时获取该参数,通过encode接口编码时将该参数放入码流。

    msgType

    String

    固定值"deviceReq",表示设备上报数据。

    hasMore

    Int

    表示设备是否还有后续数据上报,0表示没有,1表示有。

    后续数据是指,设备上报的某条数据可能分成多次上报,在本次上报数据后,物联网平台以hasMore字段判定后续是否还有消息。hasMore字段仅在PSM模式下生效,当上报数据的hasMore字段为1时,物联网平台暂时不下发缓存命令,直到收到hasMore字段为0的上报数据,才下发缓存命令。如上报数据不携带hasMore字段,则物联网平台按照hasMore字段为0处理。

    data

    ArrayNode

    设备上报数据的内容。

    表1 ArrayNode定义

    字段名

    类型

    是否必填

    参数描述

    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"
        }]
    }
  • 设备对平台命令的应答(对应图中的消息

    字段名

    类型

    参数描述

    是否必填

    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格式的数据,是平台下发的命令或应答。

平台的下行报文可以分为两种情况:

  • 平台对设备上报数据的应答(对应图中的消息
    表2 平台收到设备的上报数据后对设备的应答encode接口的入参结构定义

    字段名

    类型

    参数描述

    是否必填

    identifier

    String

    设备在应用协议里的标识,物联网平台通过decode接口解析码流时获取该参数,通过encode接口编码时将该参数放入码流。

    msgType

    String

    固定值"cloudRsp",表示平台收到设备的数据后对设备的应答。

    request

    byte[]

    设备上报的数据。

    errcode

    int

    请求处理的结果码,物联网平台根据该参数判断命令下发的状态。

    0表示成功,1表示失败。

    hasMore

    int

    表示平台是否还有后续消息下发,0表示没有,1表示有。

    后续消息是指,平台还有待下发的消息,以hasMore字段告知设备不要休眠。hasMore字段仅在PSM模式下生效,且需要“下行消息指示”开启。

    :在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

    若实现了mid,并且命令执行结果已上报成功,则:

    1. 命令执行结果响应中的状态(SUCCESSFUL/FAILED)会刷新到平台数据库中该命令的记录;
    2. 平台推送给应用服务器的命令执行结果通知中携带commandId;
    3. 应用服务器查询会得到该命令的状态为SUCCESSFUL/FAILED。
  • 不实现mid

    若不实现mid,并且命令执行结果已上报成功,则:

    1. 命令执行结果响应中的状态(SUCCESSFUL/FAILED)不会刷新到平台数据库中该命令的记录;
    2. 平台推送给应用服务器的命令执行结果通知中不携带commandId;
    3. 应用服务器查询会得到该命令的最终状态为DELIVERED。

上述两个消息流程旨在解释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。

    • com目录存放的是class文件。
    • META-INF下存放的是OSGI框架下的jar的描述文件(根据pom.xml配置生成的)。
    • OSGI-INF下存放的是服务配置文件,把编解码注册为服务,供平台调用(只能有一个xml文件)。
    • 其他jar是编解码引用到的jar包。

制作插件包

  1. 新建文件夹命名为“package”,包含一个“preload/”子文件夹。
  2. 将打包好的jar包放到“preload/”文件夹。

  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。

    表5 bundles的字段说明

    字段名

    字段描述

    是否必填

    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”这层目录。

分享:

    相关文档

    相关产品

关闭导读