华为云用户手册

初始化 在发起业务前，需要先初始化Agent Lite相关资源，调用API接口BaseService.init()，初始化Agent Lite资源，具体API的参数使用参考Agent Lite API接口文档。 调用BaseService.init(String workPath, String logPath)初始化AgentLite资源。 1 res = BaseService.init("./workdir", null);

使用必读 开发环境要求： 使用的SDK版本为jdk1.8.0_45，适用的操作系统为Windows系统。 工程目录结构及文件说明： 目录结构 目录 说明 AgentLiteDemo │ ├─src │ └─com │ └─huawei │ └─agentlitedemo ├─libs │ └─agentlite-0.0.1-SNAPSHOT │ └─usp_agentlite.jar │ └─.dll └─workdir │ └─conf src 存放Agentlite Demo代码。 libs 存放Agentlite提供的jar包和第三方jar包，以及.dll动态库（工程必须的三个文件，“agentlite-0.0.1-SNAPSHOT”，“usp_agentlite.jar”，“.dll”文件）。 workdir 存放工程日志文件，由agentlite初始化资源设置。 conf 存放TLS证书文件。 如果开发者没有设备，可以直接在X86 Linux系统进行开发。

制作软件升级版本包 设备升级的软件包文件由各设备厂商提供，在物联网平台上传设备的软件升级包前，需要制作软件升级的版本包，用于修改软件包的描述文件，如软件版本、厂商名称、设备类型、产品模型等信息。下面将详细介绍版本包的制作方法。 新建文件夹命名为“DM”，在DM文件夹下新建文件夹，命名为“linux”。 使用Notepad++文本工具新建一个文本文件，拷贝如下内容到文本中，在Notepad++工具的“编码”菜单中选择“使用UTF-8编码”，然后将文本进行存储，存储路径选择步骤1中的“linux”文件夹，文件名称命名为“UpgradeDesc”，保存类型选择“.json”。 { "specVersion": "", "fileName": "", "packageType": "", "version": "", "deviceType": "", "manufacturerName": "", "model": "", "protocolType":"", "description":"", "versionCheckCode":"", "deviceShard":"", "platform":"", "supportSourceVersionList":[], "date":""} 打开创建的“UpgradeDesc.json”文件，修改软件升级描述文件，相关字段如下表所示。 字段名 字段描述 是否必填 specVersion 描述文件版本号，固定值：“1.0”。 是 fileName 软件包文件名，例如：“ExamplePackage_V1.0.10.xx”。 是 packageType 软件包类型，必须设置为：“softwarePackage”。 是 version 软件包版本号长度不超过16个字节，例如：“V1.0.10” 是 deviceType 设备类型，需要与产品模型保持一致。例如：“WaterMeter”。 是 manufacturerName 制造商名称，需要与产品模型保持一致。例如：“TestUtf8ManuName”。 是 model 产品型号，需要与产品模型保持一致。例如：“TestUtf8ModelM2M”。 是 protocolType 设备接入协议类型，需要与产品模型保持一致。例如：“CoAP”。 说明： 设备接入的协议类型有三种：“CoAP”、“LWM2M”、“MQTT”。 是 description 对软件包的自定义描述。 是 versionCheckCode 软件升级包校验码，长度为4个字符。软件包下载时支持断点续传，根据该字段标识前后两次下载的软件包分片是否为同一个软件包。 否 deviceShard 终端下载软件包的每个分片的大小，单位为byte，如果不设置默认为500byte。大小为32~500之间。 否 platform 标识设备的操作系统，如linux。 否 supportSourceVersionList 支持用于升级此版本包的设备源版本列表。 支持通配符配置，*代表匹配任意0~n个字符，?代表匹配单个任意字符，如果存在多个版本，请使用英文“;”隔开。 否 date 出包时间，格式为：“yyyy-MM-dd”。 否 在与“DM”同级目录下创建文件夹，命名为“linux”，该文件夹名称必须同步骤1中的文件夹命令保持一致，将厂商软件包（软件包格式无限制）置于该文件中。 选中“DM”和“linux”文件夹，使用压缩工具打包成ZIP格式的压缩包，建议命令为“xx_package.zip”。 文件“DM”和“linux”的命名是固定的。 “xx_package.zip”下不能包含package这层目录。 仅支持ZIP格式的压缩包，不能压缩成其他格式后，例如rar，再手动修改文件类型为zip。

业务概览 当用户在开通设备管理服务时，系统默认一起开通设备接入服务，即用户在使用设备管理服务时，包含设备接入服务的能力。使用设备管理服务的完整流程如下图所示，主要分为在开发中心（测试环境）进行产品开发、在控制台（商用环境）进行上线和日常管理。 产品开发：开发者在进行设备接入前，基于开发中心进行相应的开发工作，包括平台侧开发、设备侧开发、应用侧开发，是真实设备接入到设备管理服务的前提条件。 上线（转商用）：基于设备管理服务提供的控制台，将真实设备接入到设备管理服务中，并对接用户开发的应用服务器，实现设备的远程监控和控制。 日常管理：真实设备接入后，基于控制台或者API接口，进行日常的应用管理和设备管理。 远端开发 转商用 设备侧开发 云端日常管理 创建项目 创建产品 开发Profile 开发编解码插件 设备侧开发 应用侧开发 API使用指导 使用SDK对接 调测产品 自助测试 产品发布 创建应用 导入产品 注册设备 接入设备 应用接入 对接验证 使用MQTTS协议接入（联通用户专用） 使用Modbus协议接入（联通用户专用） 使用Agent SDK接入 使用模组接入 软固件升级调测 应用管理 订阅推送 授权访问 设备管理 设备注册鉴权 数据上报 命令下发 设备配置更新 设备影子 规则引擎 群组与标签 设备监控 远程诊断 固件升级 软件升级 网关与子设备

方案概述 基于设备管理服务去实现一个物联网解决方案时，需要完成以下开发操作： 开发操作 开发说明 平台侧的开发 主要包括Profile的开发和编解码插件的开发。编解码插件的开发仅针对上报数据为二进制码流格式的设备，对于上报数据为JSON格式的设备不需要开发编解码插件。 设备侧的开发 主要为设备与物联网平台的集成对接开发，包括设备接入物联网平台、业务数据上报和对平台下发控制命令的处理。 应用侧的开发 主要为业务应用与物联网平台的集成对接开发，包括API接口的调用、业务数据的获取和HTTPS证书的管理。 基于物联网平台开发一个物联网解决方案的工作流程请参考从这里开始。

开发中心与设备管理服务的差异 了解开发中心 开发中心是基于设备管理服务提供的物联网一站式开发工具，帮助开发者快速进行Profile（产品模型）和编解码插件的开发，同时提供在线自助测试、产品发布等多种能力，端到端指引物联网开发，帮助开发者提升集成开发效率、缩短物联网解决方案建设周期。 产品开发：提供产品开发向导，端到端引导开发者完成Profile开发、插件开发以及产品调测，助力物联网产品快速上线。 应用开发：支持对接信息、订阅调试、应用调试等能力，帮助开发者进行应用侧开发和调试，助力物联网应用便捷开发。 自助测试：支持对设备、应用进行自动化测试，并生成测试报告，检验产品是否达到发布标准。 产品发布：产品在开发中心完成自助测试后，开发者可以一键申请发布到产品中心，已发布的产品可直接应用于商用环境。 了解设备管理服务 请前往平台简介查看设备管理服务的介绍。 开发中心和设备管理服务有哪些差异？ 两者所在的物联网平台环境不一样 开发中心所在的平台环境为测试环境，设备管理服务所在的平台环境为商用环境。两个环境的设备数据不能互通，已对接测试环境的设备/应用要迁移商用环境，需要在商用环境重新创建应用和注册设备，并修改设备/应用中平台的接入信息。 两者的设备数量限制不一样 开发中心单个项目（应用）下最多可注册20个设备，设备管理服务单个应用下最多可注册1000万个设备。在其他的平台能力上，两者保持一致，例如开发中心和设备管理服务使用同样的API，更多的平台能力使用限制请查看使用限制。 两者的计费策略不一样 开发中心为免费使用，设备管理为付费使用，设备管理服务的具体计费策略请查看计费详情。 开发中心和设备接入服务是否有联系？ 开发中心是基于设备管理服务的物联网开发工具，在开发中心上开发的产品（Profile文件和编解码插件）只适用于设备管理服务，不能在设备接入服务中导入和使用。

使用在线模拟器调试 模拟器在线调测具备设备模拟和应用模拟功能，可以对定义的Profile文件和编解码插件进行调试，用户可以直观的感受设备上报数据到物联网平台，以及使用物联网平台下发远程控制命令。 在“产品开发”页面进入到创建的产品中，选择“在线调测”，并单击“新增测试设备”。 选择“没有真实的物理设备”，使用模拟器进行调测，单击“创建”后，系统会默认创建一个模拟设备，并接入调测界面。 模拟设备数据上报场景，假设上报路灯采集的光照强度为：20，路灯开关状态为：0（关闭），则在设备模拟器中，输入十六进制码流：1400（光照强度消息为第一个字节，对应的十六进制码流为14；路灯开关状态为第二字节，对应的十六进制码流为00），然后单击“发送”，我们可以在应用模拟器中看到转换为JSON格式的数据为："Light_Intensity": 20, "Light_Status": 0。 模拟远程下发控制命令场景，在应用模拟器中，选择服务：StreetLight，命令：SWITCH_LIGHT，命令取值为：ON，单击“立即发送”，我们可以在设备模拟器中看到转换为十六进制的码流：4F4E（经ASCLL码转为为十六进制）。

编解码插件在线开发 通常情况下设备为了省电，设备会采用“二进制”格式上报数据，编解码插件的作用就是将设备上报的“二进制”格式数据，按照Profile文件的定义的属性转换为“JSON”格式数据，便于物联网平台和应用服务器识别。同时，用户远程下发控制命令时，物联网平台会将“JSON”格式的命令转换为“二进制”格式数据下发给设备。 注：如果设备本身上报的是JSON格式数据，则不需要定义编解码插件，如使用Agent Lite接入的设备。 在“产品开发”页面进入到创建的产品中，选择“编解码插件开发”。 在“在线编解码插件编辑器”中，点击“新增消息”。 输入消息名：LightData，消息类型选择：数据上报，然后再点击“添加字段”。 输入上报消息的名字：LightIntensity，数据类型：int8u（8位无符号整型），长度：1字节，单击“完成”。 再次单击“添加字段”，添加路灯上报的路灯开关状态数据。 输入名字：LightStatus，数据类型：int8u（8位无符号整型），长度：1字节，单击“完成”。 单击“完成”，完成路灯上报数据的编解码定义。 再次单击“新增消息”，定义远程控制路灯开关的命令对应的编解码插件消息。 输入消息名：SwitchStatus，消息类型选择：命令下发，然后再点击“添加字段”。 输入名字：SwitchStatus，数据类型：string（字符串类型），长度：3字符，单击“完成”。 单击“完成”，完成远程控制命令的编解码定义。 拖动右侧“设备模型”区域的属性字段和命令字段（Profile文件定义的字段），与编解码插件定义的数据上报消息和命令下发消息的相应字段建立映射关系。 编解码插件与Profile文件建立映射完成后，单击右上角“保存”，并单击“部署”，完成编解码插件的部署。

产品在线开发 产品模型（也称Profile）用于描述设备具备的能力和特性。开发者通过定义Profile文件，在物联网平台构建一款设备的抽象模型，使平台理解该款设备支持的服务、属性、命令等信息，例如温度、光强度、开关等。 本示例以一款智慧路灯为例进行描述，假设路灯设备上报一条数据消息，包含路灯的光照强度（Light_Intensity）和路灯的开关状态（Light_Status）；支持远程控制路灯开关状态的命令（SWITCH_LIGHT）。 在“产品开发”界面，点击“新建产品”，然后选择“自定义产品”。 在弹出的对话框中，设置产品信息，完成后点击“创建”。 进入到Profile定义界面后，点击“新建服务”，填写服务信息，然后点击“√”。 定义路灯上报的环境光强度和路灯开关状态的属性。首先输入“服务名称”：StreetLight，然后点击“新增属性”。 首先定义一条属性为：路灯采集的当前环境的光照强度，数据类型为int，光照强度范围为：0～100。 再点击“添加属性”按钮，定义一条属性为：路灯当前的开关灯状态，数据类型为int，0代表关闭，1代表打开状态。 接下来定义远程控制开关灯状态的命令。点击“添加命令”按钮，定义命令名称为：SWITCH_LIGHT。 点击“添加下发命令字段”，命令名称为：SWITCH_LIGHT，数据类型为：string，长度为：3个字符，枚举值为：ON,OFF。 点击“确定”按钮，完成该路灯的Profile文件创建。

开发中心申请和创建项目 用户第一次使用物联网平台云服务时，首先需要申请开通“开发中心”服务。基于开发中心，用户可以在线开发设备的Profile文件和编解码插件；另外开发中心提供了设备和应用模拟器，可以便捷地调测开发的Profile文件和编解码插件的正确性。 登录华为云官方网站，访问IoT设备管理服务。 在设备管理云服务首页，点击“开发中心”开通业务。 填写开通信息，本示例以选择“智能路灯解决方案”为例，点击“立即开通”。 （可选）进入“开发中心”首页后，如果用户是第一次使用，首先需要点击右上角的“厂商信息”，编辑并完善厂商信息后，返回主页。 在“开发中心”首页，点击“新建项目”，创建一个新的物联网产品项目，填写项目名称、所属行业后，点击“确定”。 创建完项目后，会生成应用ID和应用密钥，请将密钥下载到本地并妥善保管，然后进入项目。 应用密钥用于应用服务器接入的鉴权，在界面上不可见，请妥善保管，如果忘记了密钥，可以在“对接信息”功能中，对密钥进行重置。 项目创建完成后，可以在“对接信息”中，查看项目的基本信息，例如设备接入信息、应用接入信息、重置密钥等。

业务接口调用方法 设置好Constant.py后才能调用其他业务接口。所有业务接口的测试都在“invokeapiTest”中。以如下几个接口为例说明如何调用业务接口： 关于哪些参数需要设置，请查看《应用侧Python SDK API参考》对于可选参数，如果业务不需要，可以不设置。 配置日志 1 2 3 4 5 6 7 8 91011 # 在每个业务接口中都配置了日志，具体日志实现可参考LogUtil.py:# 开发者可通过修改入参来控制日志的输出，以下三个参数都可自行设置；# logPath：日志的输出路径，默认在工作路径d:/python_sdk/log/ # level：日志等级，默认DEBUG（最低等级，即大于等于该等级的日志级别都会输出），如果level=0没有日志输出# logFilename：日志名称def setLogConfig(self, logPath=os.path.join(Constant.workPath, 'log/'), level=logging.DEBUG, logFilename="python_sdk.log"): 鉴权 1 2 3 4 5 6 7 8 910111213141516 # 在AuthenticationTest.py中对鉴权和刷新token接口进行测试:if __name__ == "__main__": from com.huawei.iotplatform.utils.LogUtil import Log # 实例化Authentication() authentication = Authentication() # 调用鉴权类实例authentication提供的业务接口，如getAuthToken ag = authentication.getAuthToken(Constant().clientInfo()) print("====== get access token ======") print("result:", ag + "\n")# 从返回的ag中获取需要的参数，如accessToken authOutDTO = AuthOutDTO()authOutDTO.setAccessToken(json.loads(ag)['accessToken'])print("token", authOutDTO.getAccessToken()) 订阅 1 2 3 4 5 6 7 8 910111213141516171819202122232425 # 在SubscriptionManagementTest.py中对订阅订阅平台业务数据接口进行测试:class SubscriptionManagementTest(object): def subDeviceBusinessData(self): sdbdInDTO = SubDeviceBusinessDataInDTO() sdbdInDTO.notifyType = "bindDevice" sdbdInDTO.callbackUrl = "https://XXX.XXX.XXX.XXX:443/callbackurltest" return sdbdInDTOif __name__ == "__main__": from com.huawei.iotplatform.utils.LogUtil import Log # 实例化 smTest = SubscriptionManagementTest()subscriptionManagement = SubscriptionManagement() # get accessToken at first result = Authentication().getAuthToken(Constant().clientInfo()) authOutDTO = AuthOutDTO() authOutDTO.setAccessToken(json.loads(result)['accessToken']) accessToken = authOutDTO.getAccessToken() # 调用订阅类实例subscriptionManagement提供的业务接口，如subDeviceData ss = subscriptionManagement.subDeviceBusinessData(smTest.subDeviceBusinessData(), accessToken) print("====== subscribe to device business data notification ======") print("result:", ss + "\n") 注册设备 1 2 3 4 5 6 7 8 9101112131415161718192021222324252627282930 # 在DeviceManagementTest.py中对注册设备接口进行测试:class DeviceManagementTest(object): def regDirectDeviceInfo(self): rddInDto = RegDirectDeviceInDTO() rddInDto.nodeId = "AAA" + str(random.randint(0, 9999)) return rddInDtoif __name__ == "__main__": from com.huawei.iotplatform.utils.LogUtil import Log # 实例化 dmTest = DeviceManagementTest() deviceManagement = DeviceManagement() # get accessToken at first result = Authentication().getAuthToken(Constant().clientInfo()) authOutDTO = AuthOutDTO() authOutDTO.setAccessToken(json.loads(result)['accessToken']) accessToken = authOutDTO.getAccessToken() # 调用设备管理类实例deviceManagement提供的业务接口，如regDirectDevice dr = deviceManagement.regDirectDevice(dmTest.regDirectDeviceInfo(), None, accessToken) print("====== register a new device ======") print("result:", dr + "\n")# 从返回的dr中获取需要的参数，如deviceIdrddod = RegDirectDeviceOutDTO()rddod.setDeviceId(json.loads(dr)['deviceId'])deviceId = rddod.getDeviceId()print("deviceId==", deviceId + "\n")

配置平台信息及证书 配置文件（application.ini）以及证书都分别放置在工作路径“d:/python_sdk/”下面的cert 和resources文件夹中，用户也可自行设置工作路径。 平台IP、端口、appId和密码都是从配置文件中读取的，因此，当这些信息发生变化时，只要修改配置文件，不用修改应用服务器的代码。 [CLIENT_INFO]platformIp = 100.100.100.100platformPort = 8743appId = FT8EjQ8O****VbW60Qb8xvgasecret = TtuK4Paf*****yAv66himUk8a 在“Constant.py”中，读取证书和CLIENT_INFO。 1 2 3 4 5 6 7 8 9101112131415161718192021222324252627282930 class Constant(object):# 工作路径 workPath = os.path.join('d:/python_sdk/')# 读取证书def readCertificate(self): certFilePath = os.path.join(Constant.workPath, 'cert/client.crt') certFilePath2 = os.path.join(Constant.workPath, 'cert/client.key') cert = (certFilePath, certFilePath2)return cert# 读取配置文件def readConfFile(self): configFilePath = os.path.join(Constant.workPath, 'resources/application.ini') cf.read(configFilePath) platformIp = cf.get("CLIENT_INFO", "platformIp") platformPort = cf.get("CLIENT_INFO", "platformPort") appId = cf.get("CLIENT_INFO", "appId") secret = cf.get("CLIENT_INFO", "secret")return platformIp, platformPort, appId, secret# 设置平台对接信息def clientInfo(self): clientInfo = ClientInfo() clientInfo.setPlatformIp((Constant().readConfFile())[0]) clientInfo.setPlatformPort((Constant().readConfFile())[1]) clientInfo.setAppId((Constant().readConfFile())[2]) clientInfo.setSecret((Constant().readConfFile())[3]) clientInfo = DictUtil.dto2dict(clientInfo)return clientInfo

编解码插件质检 编解码插件的质检用于检验编解码是否可以正常使用。 获取编解码插件检测工具。 将检测工具“pluginDetector.jar”、Profile文件的“devicetype-capability.json”和需要检测的编解码插件包“package.zip”和tool文件夹放在同一个目录下。 获取设备数据上报的码流，并在检测工具的“data report”页签，将码流以十六进制格式输入，例如：AA72000032088D0320623399。 点击检测工具的“start detect”，查看解码后的json数据。 日志文本框会打印解码数据，如果提示“report data is success”，表示解码成功。 如果提示“ERROR”，表示解码出现错误。 当解码成功后，检测工具会继续调用编解码插件包的encode方法，对应答消息进行编码。 当提示“encode ack result success”时，表示对设备的应答消息编码成功。 获取应用服务器下发的命令（应用服务器通过调用物联网平台的“创建设备命令”接口进行命令下发），并在检测工具的“data report”页签输入。 点击检测工具的“start detect”，检测工具会调用encode接口对控制命令进行编码。 如果提示“encode cmd result success”，表示对命令编码成功；如果提示“ERROR”，表示对命令编码出现错误。 命令示例： { "identifier": "123", "msgType": "cloudReq", "serviceId": "NBWaterMeterCommon", "cmd": "SET_DEVICE_LEVEL", "mid": 2016, "paras": { "value": "10" }, "hasMore": 0 } 获取设备命令执行结果上报的码流，并在检测工具的“data report”页签，将码流以十六进制格式输入，例如：AA7201000107E0。 点击检测工具的“start detect”，查看解码后的Json数据。 日志文本框会打印解码数据，如果提示“report command result success”，表示解码成功；如果提示“ERROR”，表示解码出现错误。

编解码插件打包 插件变成完成后，需要使用Maven打包成jar包，并制作成插件包。 Maven打包 打开DOS窗口，进入“pom.xml”所在的目录。 输入maven打包命令：mvn package。 DOS窗口中显示“BUILD SUCCESS”后，打开与“pom.xml”目录同级的target文件夹，获取打包好的jar包。 jar包命名规范为：设备类型-厂商ID-设备型号-版本.jar，例如：WaterMeter-Huawei-NBIoTDevice-version.jar。 com目录存放的是class文件。 META-INF下存放的是OSGI框架下的jar的描述文件（根据pom.xml配置生成的）。 OSGI-INF下存放的是服务配置文件，把编解码注册为服务，供平台调用（只能有一个xml文件）。 其他jar是编解码引用到的jar包。 制作插件包 新建文件夹命名为“package”，包含一个“preload/”子文件夹。 将打包好的jar包放到“preload/”文件夹。 在“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 设备类型，与Profile文件中的定义保持一致。 是 manufacturerName 制造商名称，与Profile文件中的定义保持一致，否则无法上传到平台。 是 model 产品型号，与Profile文件中的定义保持一致。 是 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", "model":"NBIoTDevice", "description":"codec", "platform":"linux", "packageType":"CIGPlugin", "date":"2017-02-06 12:16:59", "ignoreList":[], "bundles":[ { "bundleName": "WaterMeter-Huawei-NBIoTDevice", "bundleVersion": "1.0.0", "priority":5, "fileName": "WaterMeter-Huawei-NBIoTDevice-1.0.0.jar", "bundleDesc":"", "versionDesc":"" }] } 选中“package”文件夹中的全部文件，打包成zip格式（“package.zip”）。 注：“package.zip”中不能包含“package”这层目录。

编解码插件的输入/输出格式样例 假定某款水表支持的服务定义如下： 服务类型 属性名称 属性说明 属性类型（数据类型） 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 }}

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 服务的命令名，参见profile的服务命令定义。 是 paras ObjectNode 命令的参数，具体字段由profile定义。 是 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} }

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 是 一个服务的数据，具体字段在profile里定义。 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 命令的应答，具体字段由profile定义。 注：body体不是数组。 否 示例： { "identifier": "123", "msgType": "deviceRsp", "mid": 2016, "errcode": 0, "body": { "result": 0 } }

使用真实设备调测 请先参照设备侧开发将设备接入开发中心，开发中心的接入地址请参照平台对接信息获取。 确保设备上报的数据信息与Profile中定义的一致，且如果设备上报的是二进制码流，请确保已经开发了编解码插件。 在产品开发空间，点击“在线调测”。 在“设备列表”区域，点击“新增测试设备”。 系统将弹出“新增测试设备”窗口，勾选“有真实的物理设备”，完成各项参数配置后，点击“创建”。 “设备名称”只允许大小写字母、数字和下划线，需要在产品下保持唯一。 “设备标识”需要在产品下保持唯一，如设备的IMEI、mac等。 “验证码加密”根据设备的实际情况进行配置。 设备创建成功后，将返回“设备ID”和“PSK码”。如果设备使用DTLS协议接入物联网平台，请妥善保存PSK码。 在设备列表中，选择新创建的真实设备，进入调试界面。 将真实设备接入到物联网平台，并进行数据上报，在“应用模拟器”区域查看数据上报的结果，在“消息跟踪”区域查看物联网平台处理日志。 在“应用模拟器”区域进行命令下发，在“消息跟踪”区域查看物联网平台处理日志，在真实设备上查看接收到的命令。

使用虚拟设备调测 在产品开发空间，点击“在线调测”。 在“设备列表”区域，点击“新增测试设备”。 系统将弹出“新增测试设备”窗口，勾选“没有真实的物理设备”，点击“创建”。 在设备列表中，选择新创建的虚拟设备，进入调试界面。虚拟设备名称组成为：“产品名称”+“Simulator”，每款产品下只能够创建一个虚拟设备。 在“设备模拟器”区域，输入十六进制码流或者JSON数据（以十六进制码流为例），点击“发送”，在“应用模拟器”区域查看数据上报的结果，在“消息跟踪”区域查看物联网平台处理日志。 在“应用模拟器”区域进行命令下发，在“设备模拟器”区域查看接收到的命令（以十六进制码流为例），在“消息跟踪”区域查看物联网平台处理日志。

设备管理 平台为每一个注册到平台上的设备生成了一个deviceId，这是设备在平台上的唯一ID，在接口调用时，每个与设备的相关操作都需要deviceId。开发中心的“设备管理”功能模块呈现本项目中的所有产品下的真实设备和虚拟设备，并提供分类统计、在线调测、设备日志等功能，以便于进行设备管理和问题定位。 在“设备管理”新增真实设备，设备名称由开发者定义。当设备侧开发已经完成时，您可以在开发中心创建真实设备，对真实物理设备、编解码插件、应用服务器等进行端到端调试。 在“设备管理”新增虚拟设备，设备名称由系统生成，名称组成为：“产品名称”+“Simulator”，每款产品下只能够创建一个虚拟设备。当设备侧开发还未完成时，您可以在开发中心创建虚拟设备，对编解码插件、应用服务器等进行调测。

SDK独立运行测试 SDK包中提供了可独立运行的jar包，用于测试平台Restful接口。可独立运行测试的jar包在testSDK目录下： 图1 可独立运行的jar包 修改config.properties后再双击运行runMe.bat即可进行测试。 图2 修改config.properties 如果使用商用证书，请直接将证书放在testSDK目录下面（证书名字不可以与ca.jks或者outgoing.CertwithKey.pkcs12相同），并在config.properties中配置证书名及密码；如果使用测试证书，则不需要修改config.properties中的证书信息。 测试结果会在最前面输出：[y]表示测试通过；[x]则表示出错，请仔细查看该行的错误提示或说明。 运行jar包需要依赖JDK，请确认已安装JDK并设置了系统环境变量。 运行runMe.bat的结果如下：

开发环境要求 开发平台 开发环境 配套要求 推荐的操作系统 IoT 1) J2EE for Java Developers 2) Maven插件：m2e - Maven Integration for Eclipse (includes Incubating components) JDK 1.8及以上版本 Windows7 SDK包为纯JAVA的JAR包，在使用上没有特殊限制，JDK在1.8及以上版本即可。

业务接口调用方法 设置好NorthApiClient实例后才能调用其他业务接口。以如下几个接口为例说明如何调用业务接口。 关于哪些参数需要设置，请查看《应用侧JAVA SDK API参考》。对于可选参数，如果业务不需要，可以不设置或者设置为null。 鉴权 123456789 //得到NorthApiClient实例后，再使用northApiClient得到鉴权类实例Authentication authentication = new Authentication(northApiClient);//调用鉴权类实例authentication提供的业务接口，如getAuthTokenAuthOutDTO authOutDTO = authentication.getAuthToken();//从返回的结构体authOutDTO中获取需要的参数，如accessToken，不同接口的token是通用的，只用获取一次，token有效期为1小时。在即将到1小时前，可调用刷新鉴权接口重新获取tokenString accessToken = authOutDTO.getAccessToken(); 订阅 1 2 3 4 5 6 7 8 9101112131415 //得到NorthApiClient实例后，再使用northApiClient得到订阅类实例SubscriptionManagement subscriptionManagement = new SubscriptionManagement(northApiClient);//先设置好subDeviceData的第一个入参SubDeviceDataInDTO结构体SubDeviceDataInDTO sddInDTO = new SubDeviceDataInDTO();sddInDTO.setNotifyType("deviceDataChanged");//需要根据实际情况修改回调的ip和端口ddInDTO.setCallbackUrl("https://XXX.XXX.XXX.XXX:8099/v1.0.0/messageReceiver");try { //调用订阅类实例subscriptionManagement提供的业务接口，如subDeviceData SubscriptionDTO subDTO = subscriptionManagement.subDeviceData(sddInDTO, null, accessToken); System.out.println(subDTO.toString());} catch (NorthApiException e) { System.out.println(e.toString());} 注册设备 1 2 3 4 5 6 7 8 910111213141516 //得到NorthApiClient实例后，再使用northApiClient得到设备管理类实例DeviceManagement deviceManagement = new DeviceManagement(northApiClient);//设置好注册设备接口的第一个入参RegDirectDeviceInDTO2结构体RegDirectDeviceInDTO2 rddInDTO = new RegDirectDeviceInDTO2();String nodeid = "86370303XXXXXX"; //this is a test imeiString verifyCode = nodeid;rddInDTO.setNodeId(nodeid);rddInDTO.setVerifyCode(verifyCode);rddInDTO.setTimeout(timeout);//调用设备管理类实例deviceManagement提供的业务接口，如regDirectDeviceRegDirectDeviceOutDTO rddod = deviceManagement.regDirectDevice(rddInDTO, null, accessToken);//从返回的结构体rddod中获取需要的参数，如deviceIdString deviceId = rddod.getDeviceId();

初始化及证书配置 新建一个NorthApiClient实例，设置好ClientInfo（包括平台IP、端口、appId和密码），再初始化证书。 平台IP、端口、appId和密码都是从配置文件./src/main/resources/application.properties中读取的，因此，当这些信息发生变化时，只要修改配置文件，不用修改应用服务器的代码。本章节所指的证书是平台提供的，在调用平台接口过程中使用；一般情况下，与回调使用的证书不一样。 使用测试证书： 1 2 3 4 5 6 7 8 9101112 NorthApiClient northApiClient = new NorthApiClient();PropertyUtil.init("./src/main/resources/application.properties");ClientInfo clientInfo = new ClientInfo();clientInfo.setPlatformIp(PropertyUtil.getProperty("platformIp"));clientInfo.setPlatformPort(PropertyUtil.getProperty("platformPort"));clientInfo.setAppId(PropertyUtil.getProperty("appId"));clientInfo.setSecret(PropertyUtil.getProperty("secret"));northApiClient.setClientInfo(clientInfo);northApiClient.initSSLConfig();//默认使用测试证书，且不进行主机名校验 如果不使用测试证书，可使用指定证书（如商用证书）： 1 2 3 4 5 6 7 8 9101112131415161718 NorthApiClient northApiClient = new NorthApiClient();PropertyUtil.init("./src/main/resources/application.properties");ClientInfo clientInfo = new ClientInfo();clientInfo.setPlatformIp(PropertyUtil.getProperty("platformIp"));clientInfo.setPlatformPort(PropertyUtil.getProperty("platformPort"));clientInfo.setAppId(PropertyUtil.getProperty("appId"));clientInfo.setSecret(getAesPropertyValue("secret"));SSLConfig sslConfig= new SSLConfig();sslConfig.setTrustCAPath(PropertyUtil.getProperty("newCaFile"));slConfig.setTrustCAPwd(getAesPropertyValue("newCaPassword"));slConfig.setSelfCertPath(PropertyUtil.getProperty("newClientCertFile"));slConfig.setSelfCertPwd(getAesPropertyValue("newClientCertPassword"));northApiClient.setClientInfo(clientInfo);northApiClient.initSSLConfig(sslconfig); //使用指定的证书，且默认使用严格主机名校验 使用指定证书时，如果不使用严格主机名校验，在调用northApiClient.initSSLConfig(sslconfig)之前可以自行设置主机名校验方法： 1234567 northApiClient.setHostnameVerifier(new HostnameVerifier() { public boolean verify(String arg0, SSLSession arg1) { // 自定义主机名校验 …… return true; }}); 主机名校验方法应以安全为原则，不应该直接返回true。

高质量素材规范要求有哪些？ 素材制作规范要求：排版有层次，色调平衡，画面简洁且兼容美感。 整体：图片内容符合所选模板及场景定位 ，准确的传达信息，突出画面的主题。 排版：尽量通过位置关系（前后、上下、大小等）提升文字层次感。 核心信息区域：视觉焦点位，展示主要信息点，避免字体过多、偏小、偏大，突出利益点。 辅助区域：不放重要信息，可辅助营造氛围感，烘托主体信息。 色调：减少使用强对比色彩，色彩组调保持画面平衡。 图片版权：确保设计用途的版权、人物肖像权；杜绝使用明显政治倾向、色情、暴力、恐怖等图片。 图1 高质量素材样例 图2 高质量素材样例 图3 高质量素材样例 图4 高质量素材样例 图5 高质量素材样例 父主题： 智能模板制作常见问题

各手机厂商视频类智能信息模板差异 各手机厂商支持内容的差异 支持情况及规范要求参见表1 表1 各手机厂商视频类智能信息模板支持内容的差异 品牌 华为 小米 OPPO VIVO 魅族 视频类模板素材规范 视频 格式 MP4 / MP4 MP4、TS / 尺寸 16：9 16：9 16：9 大小 10M 25M 无限制 标题 1行，17字 1行，17字 2行，30字 正文 3行，69字 3行，69字 2行，69字 按钮 1个，15字 1个，15字 1行，7字 动参能力 √ / √ √ / 各手机厂商视频类智能信息模板终端样例差异 图1 华为终端样例 图2 VIVO终端样例 图3 OPPO终端样例

智能信息模板总体设计规范有哪些 表1 智能信息模板总体设计规范 规范内容 规范要求 注意事项或建议 文字 使用书面语言 文案内容完整 不能有错别字、语法混乱、符号错乱 不标题党、严重夸大商品 不发布过时效的信息或服务 文案与跳转页面相匹配 - 音视频 内容拥有使用版权 优先使用mp4格式，且内容完整流畅 不能出现马赛克/拉伸变形/模糊等 与对应标题、短信、主体匹配 不含有其他平台水印标识 无杂音、无多音轨 - 图片 内容拥有使用版权 符合所选模板及场景定位 单图大小不超2MB 要素从简、扁平化设计 保证清晰美感，有明确主色调，减少使用强对比色彩 不超过3种字体样式（组合情况下不超过2种字体样式） 周围保持18px~24px边距 不出现引导性按钮 元素不宜过多，以简洁为主 为了保证阅读性，最小文字不小于30px 跳转链接 不存在无法打开的链接、恶意网址 不存在不适用PC的页面 落地页与素材相匹配 不违反广告法 核心功能流程支持全流程流畅 无拉伸、收缩、扭曲等变形或者页面不适配的情况 链接必须为https或http开头 链接跳转需跳转到厂商应用下载平台 页面上线后如有问题，将直接下线再另行通知 父主题： 智能信息模板制作规范

各手机厂商智能信息支持能力差异有哪些？ 表1 各手机厂商智能信息支持能力 各手机厂商智能信息支持能力一览表 华为 小米 OPPO VIVO 魅族 点击事件 打开H5 √ √ √ √ √ 打开浏览器 √ √ √ √ √ 打开快应用 √ √ √ √ √ 打开app √ √ √ √ √ 打电话 √ √ × × √ 发短信 √ √ × × √ 发邮件 √ √ × × √ 设置日程 √ √ × × √ 打开地图 √ √ × × √ 弹窗 √ √ × × √ 复制 √ √ × × √ 查看大图 √ √ √ √ × 短链能力 个性化短链 √ √ √ √ √ 群发短链 √ √ √ √ √ 识别类型 短链识别 √ √ √ √ √ 特征码识别 √ × × × × 文本识别 √ × √ √ × 动参能力 文本动参 √ √ √ × × 兜底能力 打开应用市场 √ √ √ √ × 打开H5 √ √ √ √ × 打开浏览器 √ √ √ √ × 打开快应用 √ √ × × × 父主题： 智能模板制作常见问题

各手机厂商电商（多商品类）智能信息模板差异 各手机厂商支持内容的差异 支持情况及规范要求参见表1。 表1 各手机厂商电商（多商品）类智能信息模板支持内容的差异 品牌 华为 小米 OPPO VIVO 魅族 电商（多商品）类素材规范 图片大小 宽高比1:1，最大大小2M，建议像素192*192 / / / / 主标题 1行，12字 副标题 1行，20字 正文（16:9） 2行，24字 动参能力 √ / / / /

各手机厂商视频图文类和图文视频类智能信息模板差异 各手机厂商支持内容的差异 支持情况及规范要求参见表1 表1 各手机厂商视频图文类和图文视频类智能信息模板支持内容的差异 品牌 华为 小米 OPPO VIVO 魅族 视频图文模板素材规范 图文视频模板素材规范 视频 格式 MP4，可与图片上下位置互换 / / / / 尺寸 16：9 大小 10M 图片 宽高比21:9，最大大小2M，建议像素1248*704 标题 1行，17字 正文 3行，69字 按钮 1个，15字 动参能力 √ / / / /