华为照明物联网解决方案业务应用开发指南

1、华为照明物联网解决方案 业务应用开发指南文档版本发布日期012016-06-01HUAWEI华为技术有限公司版权所有？华为技术有限公司2016。保留一切权利。非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传 播。商标声明m和其他华为商标均为华为技术有限公司的商标。本文档提及的其他所有商标或注册商标，由各自的所有人拥有。您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务 或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示 的声明或保证。由于产品版本升级或其他原因，

2、本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本 文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。华为技术有限公司地址:深圳市龙岗区坂田华为总部办公楼邮编：518129网址:读者对象本文档（本指南）主要适用于以下工程师:二次开发工程师符号约定修改记录符号说明危险用于警示紧急的危险情形，若不避免，将会导致人员死亡 或严重的人身伤害。力警告用于警示潜在的危险情形，若不避免，可能会导致人员死 亡或严重的人身伤害。小心用于警示潜在的危险情形，若不避免，可能会导致中度或 轻微的人身伤害。注意用于传递设备或环境安全警示信息，右不避免，可能会导 致设备损坏、数据丢失、设备性能降低或

3、其它不可预知的 结果。“注意”不涉及人身伤害。0Q说明冷于突出重要/关键信息、最佳实践和小窍门等。“说明”不是安全警示信息，不涉及人身、设备及环境伤害 信息。在本文中可能出现下列标志，它们所代表的含义如下。修改记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。文档版本 01 (2016-06-01)版本拟制/修订责任人拟制/修订日期修订内容及理由批准人V01.00罗振辉/001997442016/3/8新拟制薄会健00330119V01.01吴英德/001970742016/3/9新增接口描述薄会健00330119V01.02罗振辉/00199744苏本胜/00202

4、1812016/5/23增加“远程、策 略控制、告警”API 接口薄会健00330119V01.03鲍利亚/003463662017/6/28修改版本号薄会健003301191概述11.1目的11.2概述11.3术语12整体架构2.2.1架构图22.2接口说明32.3业务应用开发 33设备安装.4.3.1原理说明43.2接口说明53.3 Java加载证书63.3.1获得证书并进行转换 63.3.2对转换后的证书进行加载 63.4白名单配置接口 73.5白名单授权加网接口 93.6未知设备上线接口 103.7设备建档接口 103.8注意事项124远程访问原理134.2接口说明134

5、.2.1 GET接口示例（读取调光等级）134.2.2 SET接口示例（设置调光等级） 144.2.3 ACTION接口示例（设备自检） 154.2.4 ACTION接口示例（组播设置开关状态） 164.2.5 ACTION接口示例（批量设置多个设备的开关状态）174.3注意事项185 计划控制 原理 205.1.1 三层计划关系 205.1.2 对时 205.1.3 计划创建过程 215.2 接口说明 225.2.1 EEM 计划创建接口（采集计划） 225.2.2 网关计划创建接口（控制计划） 235.2.3 网关计划执行结果上报接口 255.2.4 路灯控制器计划执行模式

6、设置接口 265.2.5 路灯控制器计划创建接口 275.2.6 路灯控制器计划管理接口 285.3 注意事项 296 策略控制 原理 306.2 接口说明 306.2.1 EEM 策略创建接口（ EEM 策略） 306.2.2 路灯控制器策略执行模式设置接口 326.2.3 路灯控制器策略创建接口 336.2.4 路灯控制器策略管理接口 346.3 注意事项 3577 告警7.1 原理3.6. 367.2 接口说明 367.2.1 设备上下线 367.2.2 设备过压过流 377.2.3 电量计量不匹配 387.2.4 电量超出计量范畴 387.3 注意事项 388 参考资料

7、 EEM V200R009C00 调测指南 391 概述本指南旨在指导客户基于华为 EEM平台开发自己的业务系统，基于场景描述。1.1目的适用于华为照明物联网解决方案所有的合作厂商、集成厂商进行业务系统构建参考1.2概述1.3术语名称定义SMS路灯管理系统EEM物联网能效管理平台路灯控制器路灯的控制设备，可支持调光、计量、开关等功能。网关路由器设备，通过zigbee连接路灯控制器，通过 3G、以太 网、LTE连接EEM。设备通篇统一：网关：000D6F00055CCF08 ,路灯控制器： 2E00216EFC000222，单控设备：2E00216EFC000222，设备 域:

8、root2.1架构图2整体架构图2-1架构图EEMGPRS/3G/LTEZig Bee MeshNehvork-JrBrightness Sensor (option a D整个解决方案包括四个部分构成，主要是路灯控制器、华为物联网网关、EEM平台、APP （业务系统），各部分功能描述如下。路灯控制器：控制路灯调光、开光，支持计量功能，可采集电压、电流、功率、电 量、频率数据。物联网网关：连接路灯控制器，获取通过3G/LTE方式进行上行与EEM平台进行通信。 EEM平台：连接物联网网关，提供上行 RESTCONFWebSocket接口给第三方应用进行 二次开发，可实现对路灯进行远程开关、 调光

9、等功能，也支持编制计划和策略控制。APP客户基于EEM平台开发的业务应用系统。2.2接口说明表2-1接口说明模块接口类 型描述备注路灯控制器 物联网网关Zigbee无线通信技术，支持 MESH物联网网关EEM3G/LTE/以太网上行通信技术，TCP/IP协议通 信EEMAPPRESTCO NFRestful接口，采用YANG模型 描述，用于下发远程控制命令、 本地计划创建、策略创建等功 能。EEMAPPWEBSO CKETWebSocket接口，用于上报即 时消息，如设备上线、下线， 设备告警等。2.3业务应用开发客户可以根据EEM提供的接口进行业务应用开发，接口文档可参考华为物联网EEM平台

10、接口文档。后续章节会根据各类场景描述整个方案原理以及实用接口说明。Restful的使用和Websocket的使用请参阅8参考资料章节应用开发前网关需要先配置连接到EEM，配置方法参考下面的附件：EE与AR50之 间的组网步骤.docx3设备安装3.1原理说明图3-1设备安装流程sd调用流程/APP| EEM| 物联网网关 | 路灯控制器设备安装主要包括以下几个步骤；配置白名单：设备白名单给物联网网关，旨在告知物联网网关那些设备可入网。白名单授权加网：开启 Zigbee网络加网权限，设备可搜索网络，并加入到Zigbee网络中，白名单之外设备当作非法设备处理，不可加入到Zigbee网络中。设备上线

11、：设备加网到Zigbee网络之后，上报上线消息，EEM通过 WEBSOCKET接口 告知APP,当前设备还处于未知设备状态。建档：设备上线之后，当前设备还处于未知设备状态，APP可调用EEM接口进行建档，建档之后，设备才可正常操作，为可识别设备。在整个过程中，设备的状态变化，如下图所示； 图3-2设备状态图stm状态图 /可识别设备3.2接口说明1 本文档示例中使用到的网关ID和传感器ID需要根据真实环境更改为正确的设备ID。2 本文档示例中使用的EEM平台的IP地址是,在真实环境中需要将 IP地址改为EEM平台的IP地址。3 本文档示例中使用的 EEM平台的IP端口号是18

12、443，这是基于https协议访问EEM平台的缺省缺口号（如果使用http协议，缺省的端口号为8181 ）。3.3 Java 加载证书3.3.1 获得证书并进行转换从路径 /opt/controller/naas/naas-karaf-1.0.1-SNAPSHOT/configuration/ssl 下获得 iotdmClient.p12 和 server.crt 两个证书。前置条件：由于使用的是Java Key Store格式的证书，所以，必须使用Java提供的keytool 工具箱，因此，执行下面指令的电脑必须安装了 JDK（Java SE Development Kit） ，最好是 配置

13、了环境变量。1. 转换 server.crt 为 trustcer.jks:keytool -mport -alias iotdmServer -file server.crt -keystore jks/trustcer.jks -keypassChan geme_123 -storepass Chan geme_123 -trustcacerts -oprompt 参数说明：server.crt: 源证书路径。jks/trustcer.jks: 目标证书存储路径。 第一个 Changeme_123: 更改条目的密钥口令。 第二个 Changeme_123: 更改密钥库的存储口令。iotdm

14、Server: 证书的别名 ,不指定 ,则默认为 mykey。 说明：该指令是将可信任的证书转换为 Java Key Store 格式的证书。如果指定的 targetJKSPath 不存在这个 jks 文件， 则自动生成一个 jks 文件（注： 目录不会自动产生， 只会在指定目录下生成 jks 文件），如果已经存在了 jks 文件，则在该 jks 文件中追加该 证书。2. 转换 iotdmClient.p12 为 keystore.jks :keytool -v -importkeystore -srckeystore iotdmClient.p12 -srcstoretype PKCS12

15、-destkeystore jks/keystore.jks -deststoretype JKS -srcstorepass Changeme_123 -deststorepass Changeme_123 -noprompt -changealias -destalias iotdmalias -alias iotdmclient 参数说明：iotdmClient.p12: 源证书路径。jks/keystore.jks : 目标证书存储路径。 第一个 Changeme_123: 更改条目的密钥口令。 第二个 Changeme_123: 更改密钥库的存储口令。iotdmclient: 证书的

16、别名 ,不指定 ,则默认为 mykey。说明：该指令是将p12的证书转换为Java Key Store格式的证书。如果指定的targetJKSPath 不存在这个 jks 文件， 则自动生成一个 jks 文件（注： 目录不会自动产生， 只会在指定目录下生成 jks 文件），如果已经存在了 jks 文件，则在该 jks 文件中追加该 证书。3.3.2 对转换后的证书进行加载加载证书样例：public class Testpublic static void main(String args)Cert.loadJKSCert();Cert.setInterface();public static

17、void loadJKSCert()char password = Changeme_123.toCharArray();File keystore = new File(keystore.jks);File trustFile = new File(trustcer.jks);SSLContext sslcontext;trysslcontext =SSLContexts.custom().useProtocol(TLSv1.2).loadTrustMaterial(trustFile) .loadKeyMaterial(keystore, password, password).build

18、();HttpClient httpClient =HttpClients.custom().setSSLContext(sslcontext).build();Unirest.setHttpClient(httpClient);catch (KeyManagementException | UnrecoverableKeyException |NoSuchAlgorithmException | KeyStoreException| CertificateException | IOException e)e.printStackTrace();public static void setI

19、nterface()HttpResponse response;tryresponse =Unirest.post(50:18443/iotdm/nb/v1/system/action/urn:huawei:iotdm:devmgr/get).header(content-type,application/json).queryString(domain, H1).asJson();catch (UnirestException e)e.printStackTrace();说明： keystore.jks 和 trustcer.jks 为 3.3.1 中转换后

20、的证书所存放的位置， loadJKSCert() 方法只需 要调用一次即可， setInterface() 方法中的内容可用对应接口内容进行替换。3.4 白名单配置接口数据项名称 : 白名单设备增加 white-list-device-add例子：ID 为 000D6F00055CCF08 的网关下连接了四个 ID 分别为 2E00B136CB000515 、 2E0012F111000178 、2E00B136CB000594 和 2E0012F111000181 的设备，将这四个设备 添加到白名单。接口：URL::18443/iotdm/nb/v1/devi

21、ce/action/000D6F00055CCF08/urn:huawei:i otdm:device/huawei-iotdm-device-common:white-list-device-addMethod:POSTBody ：devices:2E00B136CB000515, 2E0012F111000178, 2E00B136CB000594, 2E0012F111000181Result:OKJava:HttpResponse response =Unirest.post(:18443/iotdm/nb/v1/device/action/000D6F

22、00055CCF08/urn:huawei:iotdm:device/huawei-iotdm-device-common:white-list-device-add).header(content-type, application/json).header(cache-control, no-cache).body(n devices:n n 2E00B136CB000515,n2E0012F111000178,n 2E00B136CB000594,n2E0012F111000181n n).asString();Javascript:var settings = async: true,

23、crossDomain: true,url::18443/iotdm/nb/v1/device/action/000D6F00055CCF08/urn:huawei:iotdm:device/huawei-iotdm-device-common:white-list-device-add,method: POST,headers: content-type: application/json,cache-control: no-cache,processData: false,data: ndevices:n n 2E00B136CB000515,n2E0012

24、F111000178,n 2E00B136CB000594,n2E0012F111000181n n$.ajax(settings).done(function (response) console.log(response););JavaScript:var settings = async: true,crossDomain: true,url::18443/iotdm/nb/v1/device/action/000D6F00055CCF08/urn:huawei:iotd m:device/huawei-iotdm-device-common:white-

25、list-device-add,method: POST,headers: content-type: application/json,cache-control: no-cache,postman-token: 312f143f-fa9a-cfbd-3627-27e9eb041eb2,processData: false,data: rndevices:rn rn 2E00B136CB000515,rn2E0012F111000178,rn 2E00B136CB000594,rn2E0012F111000181rn rnrn$.ajax(settings).done(function (r

26、esponse) console.log(response););3.5 白名单授权加网接口白名单加网 white-list-permit-join-net例子： ID 为 000D6F00055CCF08 的网关允许加网 21 秒。接口:URL::18443/iotdm/nb/v1/device/action/000D6F00055CCF08/urn:huawei:i otdm:device/huawei-iotdm-device-common:white-list-permit-join-netMethod ： POSTBodypermit-time:21R

27、esult:OKJava:HttpResponse response =Unirest.post(:18443/iotdm/nb/v1/device/action/000D6F00055CCF08/ur n:huawei:iotdm:device/huawei-iotdm-device-common:white-list-permit-join-net).header(content-type, application/json).header(cache-control, no-cache).body(n permit-time:21n).asString()

28、;JavaScript:var settings = async: true,crossDomain: true,url::18443/iotdm/nb/v1/device/action/000D6F00055CCF08/urn:huawei:iotd m:device/huawei-iotdm-device-common:white-list-permit-join-net,method: POST,headers: content-type: application/json,cache-control: no-cache,processData: fals

29、e,data: n permit-time:21n$.ajax(settings).done(function (response) console.log(response););3.6未知设备上线接口URL:wss:/:18443/iotdm/stream/nb/v1/system?type=urn:huawei:device:gateway:unknown-device-online解压 unknown-device-online.zip 压缩包，获取 unknown-device-online.html ,通过谷歌浏览 器或火狐浏览器打开该html。该html已配置好

30、请求链接，可直接使用。unknown-device-online.zipope n-q uote! ”的方打开html后，显示如下，表示链接正常。如果有未知设备上线，在“ 框中会逐步显示。WebSccket：open-quat e!在“ send”按钮前的输入框，输入以下参数，再点击“send”按钮，可查询一定时间范围内的未知设备上线事件。参数：startTime:2015-05-07T00:00:00Z,stopTime:2015-05-07T23:00:00Z预期返回报文：eventTime:2016-03-08T17:32:51+08,urn:huawei:device:gateway:

31、unknown-device-onl ine:model:hwslc,proto:fenjin,gateway:000D6F00055CCF08,esn:2E00216E FC0002223.7设备建档接口创建两个单控设备，设备esn分别为2E00216EFC000222、2E33000001000200，设备域(domain)为 root，模型(model)为 hwslc。接口 ：URL::18443/iotdm/nb/v1/system/action/urn:huawei:iotdm:devmgr/add Method:POSTBody ： device:m

32、odel : hwgw,domain : root,esn : 000D6F00055CCF08,model:hwslc,domain:root,esn:2E00216EFC000222, model:hwslc,domain:root,esn:2E33000001000200Result:OKJava:HttpResponse response =Unirest.post(:18443/iotdm/nb/v1/system/action/urn:huawei:iotdm:de vmgr/add).header(content-type, application

33、/json).header(cache-control, no-cache).body( device:rn rnt rntmodel:hwslc, rntdomain:root, rntesn:2E00216EFC000222 rnt, rnt model:hwslc, rntdomain:root, rntesn:2E33000001000200 rnt rn rnrn).asString();JavaScript:var settings = async: true,crossDomain: true,url::18443/iotdm/nb/v1/syst

34、em/action/urn:huawei:iotdm:devmgr/add,method: POST,headers: content-type: application/json,cache-control: no-cache,processData: false,data: device:rn rnt rntmodel:hwslc, rntdomain:root, rntesn:2E00216EFC000222 rnt, rnt model:hwslc, rntdomain:root, rntesn:2E33000001000200 rnt rn rnrn$.ajax(settings).

35、done(function (response) console.log(response););3.8 注意事项EEM 提供了物联网网关全网加网接口，全网加网操作后，相当于物联网网关不会对加 网的设备作任何限制，任何设备都可入网，这个在多网关情况下操作比较危险，设备可 能存在串网现象，因此在多网关情况下不推荐使用这个接口 。4远程访问4.1原理在华为照明物联网解决方案中，EEM提供所有设备的远端操作接口，操作接口主要分GET接口、SET接口、ACTION接口。GET接口主要用于采集设备当前状态和数据， 例如获取电压、电流、电量、功率、流明度等数据。SET接口主要用于配置设备参数和控制操作，例

36、如设置设备上报周期、波动阈值、远程开关、调光等。ACTION 接口主要用于命令操作，例如群组操作、自检等。远程操作接口支持对单个设备操作也支持批量操作。4.2接口说明4.2.1 GET接口示例（读取调光等级）读取路灯控制器2E00216EFC000222的当前的调光等级接口：URL::18443/iotdm/nb/v1/device/get/2E00216EFC000222/urn:huawei:iotd m:device/data/huawei-iotdm-device-sensor:dim-levelMethod:GETResult:OKindex: 0,l

37、evel: 0Java：:18443/iotdm/nb/v1/device/get/2E00216EFC000222/urn:huawei:iotdm:de vice/data/huawei-iotdm-device-sensor:dim-levelJavaScript:var settings = async: true, crossDomain: true, url::18443/iotdm/nb/v1/device/get/2E00216EFC000222/urn:huawei:iotdm:d evice/data/huaw

38、ei-iotdm-device-sensor:dim-level,method: GET,headers: cache-control: no-cache, postman-token: 68e1d7e0-1f1a-b490-fe6e-98f09d1f2765 $.ajax(settings).done(function (response) console.log(response););4.2.2 SET 接口示例(设置调光等级)设置路灯控制器 2E00216EFC000222 的调光等级为 75% 接口：URL::18443/iotdm/nb/v1/dev

39、ice/set/2E00216EFC000222/urn:huawei:iotdm: device/data/huawei-iotdm-device-sensor:dim-levelMethod:POSTBody:index: 0,level: 75Result:OKJava：HttpResponse response = Unirest.post(:18443/iotdm/nb/v1/device/set/2E00216EFC000222/urn:h uawei:iotdm:device/data/huawei-iotdm-device-sensor:dim-

40、level).header(content-type, application/json).header(cache-control, no-cache).header(postman-token, e3bf1ce2-73c4-5e2a-11e5-684e2a70f8d2).body(rn rn index: 0,rnlevel: 75rn rnrn).asString();JavaScript：var settings = async: true, crossDomain: true,url::18443/iotdm/nb/v1/device/set/2E00

41、216EFC000222/urn:huawei:iotdm:d evice/data/huawei-iotdm-device-sensor:dim-level,method: POST,headers: content-type: application/json,cache-control: no-cache,postman-token: 5df0330b-0a92-84c7-7a6a-ba1347d7db93,processData: false,rnrndata: rn rn index: 0,rn level: 75rn$.ajax(settings).done(function (r

42、esponse) console.log(response););4.2.3 ACTION 接口示例(设备自检)对路灯控制器 2E00216EFC000222 发出设备自检命令接口：URL::18443/iotdm/nb/v1/device/action/2E00216EFC000222/urn:huawei:i otdm:device/huawei-iotdm-device-common:system-self-checkMethod:ACTIONBody:Result:OKself-check-status: success,hardware-version

43、: 1,product-version: V200R007C10,software-version: 51Java：HttpResponse response =Unirest.post(:18443/iotdm/nb/v1/device/action/2E00216EFC000222/ur n:huawei:iotdm:device/huawei-iotdm-device-common:system-self-check).header(content-type, application/json).header(cache-control, no-cache

44、).header(postman-token, 884168d1-554a-fea2-cd12-4fc976c91651) .asString();JavaScript：var settings = async: true,crossDomain: true,url: :18443/iotdm/nb/v1/device/action/2E00216EFC000222/urn:huawei:iotd m:device/huawei-iotdm-device-common:system-self-check,method: POST,headers: content

45、-type: application/json,cache-control: no-cache,postman-token: 72fe13a8-81d3-8012-1773-a8a6e1c79be7, processData: false, data: $.ajax(settings).done(function (response) console.log(response););4.2.4 ACTION 接口示例(组播设置开关状态) 将网关 000D6F00055CCF08 的第 1 组设备的开关状态全部设置为关 接口：:18443/iotdm/nb/v1/

46、device/action/000D6F00055CCF08/urn:huawei:iotdm :device/huawei-iotdm-device-common:multicastMethod:ACTIONBody: gid:1, type:set, path:/huawei-iotdm-device:data/huawei-iotdm-device-sensor:switch-status, body:index:0, status:offResult:OK Java： HttpResponse response =Unirest.post(:18443/

47、iotdm/nb/v1/device/action/000D6F00055CCF08/ur n:huawei:iotdm:device/huawei-iotdm-device-common:multicast).header(content-type, application/json).header(cache-control, no-cache) .header(postman-token, af3bacf0-1f55-e41a-27ca-938dff882507).body(rn gid:1,rn type:set,rnn body:rn rn rn index:0,rn status:

48、offrn rn rnrn).asString();JavaScript：var settings = async: true, crossDomain: true, url::18443/iotdm/nb/v1/device/action/000D6F00055CCF08/urn:huawei:iotd m:device/huawei-iotdm-device-common:multicast,method: POST,headers: content-type: application/json,cache-control: no-cache, postma

49、n-token: 543dfe51-83fa-5763-c2d9-2748c68b5c88,processData: false,data: rngid:1,rntype:set,rnn body:rnrnrn index:0,rnstatus:offrnrn rnrn$.ajax(settings).done(function (response) console.log(response););4.2.5 ACTION 接口示例(批量设置多个设备的开关状态) 以下示例使用 ACTION 接口，对设备域 3B01 下所有的设备和路灯控制器 2E00216EFC000222 、 2E00216

50、EFC000223 都执行关灯的操作 接口:URL:95:18443/iotdm/nb/v1/system/action/urn:huawei:iotdm:task/bul k-ctlMethod:POSTBody domains:3B01, devices:2E00216EFC000222,2E00216EFC000223, priority:1,retry-times:3, retry-intervals:1000, max-timeout:10000, enable:true,action: name:2, type:set, delay:1000, path:/huawei-iotdm-device:data/huawei-iotdm-de