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

DOCPROPERTY"Product&ProjectName"华为照明物联网解决方案DOCPROPERTYDocumentName业务应用开发指南华为专有和保密信息版权所有©华为技术有限公司PAGE39概述目的本指南旨在指导客户基于华为EEM平台开发自己的业务系统，基于场景描述。概述适用于华为照明物联网解决方案所有的合作厂商、集成厂商进行业务系统构建参考。术语名称定义SMS路灯管理系统EEM物联网能效管理平台路灯控制器路灯的控制设备，可支持调光、计量、开关等功能。网关路由器设备，通过zigbee连接路灯控制器，通过3G、以太网、LTE连接EEM。设备通篇统一：网关：000D6F00055CCF08，路灯控制器：2E00216EFC000222，单控设备：2E00216EFC000222，设备域：root整体架构架构图整个解决方案包括四个部分构成，主要是路灯控制器、华为物联网网关、EEM平台、APP（业务系统），各部分功能描述如下。路灯控制器：控制路灯调光、开光，支持计量功能，可采集电压、电流、功率、电量、频率数据。物联网网关：连接路灯控制器，获取通过3G/LTE方式进行上行与EEM平台进行通信。EEM平台：连接物联网网关，提供上行RESTCONF、WebSocket接口给第三方应用进行二次开发，可实现对路灯进行远程开关、调光等功能，也支持编制计划和策略控制。APP：客户基于EEM平台开发的业务应用系统。接口说明模块接口类型描述备注路灯控制器<->物联网网关Zigbee无线通信技术，支持MESH物联网网关<->EEM3G/LTE/以太网上行通信技术，TCP/IP协议通信EEM<->APPRESTCONFRestful接口，采用YANG模型描述，用于下发远程控制命令、本地计划创建、策略创建等功能。EEM<->APPWEBSOCKETWebSocket接口，用于上报即时消息，如设备上线、下线，设备告警等。业务应用开发客户可以根据EEM提供的接口进行业务应用开发，接口文档可参考华为物联网EEM平台接口文档。后续章节会根据各类场景描述整个方案原理以及实用接口说明。Restful的使用和Websocket的使用请参阅REF_Ref486941237\r\h8REF_Ref486941241\h参考资料章节应用开发前网关需要先配置连接到EEM，配置方法参考下面的附件：设备安装原理说明设备安装主要包括以下几个步骤；配置白名单：设备白名单给物联网网关，旨在告知物联网网关那些设备可入网。白名单授权加网：开启Zigbee网络加网权限，设备可搜索网络，并加入到Zigbee网络中，白名单之外设备当作非法设备处理，不可加入到Zigbee网络中。设备上线：设备加网到Zigbee网络之后，上报上线消息，EEM通过WEBSOCKET接口告知APP，当前设备还处于未知设备状态。建档：设备上线之后，当前设备还处于未知设备状态，APP可调用EEM接口进行建档，建档之后，设备才可正常操作，为可识别设备。在整个过程中，设备的状态变化，如下图所示；接口说明本文档示例中使用到的网关ID和传感器ID需要根据真实环境更改为正确的设备ID。本文档示例中使用的EEM平台的IP地址是，在真实环境中需要将IP地址改为EEM平台的IP地址。本文档示例中使用的EEM平台的IP端口号是18443，这是基于https协议访问EEM平台的缺省缺口号（如果使用http协议，缺省的端口号为8181）。Java加载证书获得证书并进行转换从路径/opt/controller/naas/naas-karaf-1.0.1-SNAPSHOT/configuration/ssl下获得iotdmClient.p12和server.crt两个证书。前置条件：由于使用的是JavaKeyStore格式的证书，所以，必须使用Java提供的keytool工具箱，因此，执行下面指令的电脑必须安装了JDK(JavaSEDevelopmentKit)，最好是配置了环境变量。1.转换server.crt为trustcer.jks:keytool–import–aliasiotdmServer-fileserver.crt-keystorejks/trustcer.jks-keypassChangeme_123-storepassChangeme_123-trustcacerts–noprompt参数说明：server.crt:源证书路径。jks/trustcer.jks:目标证书存储路径。第一个Changeme_123:更改条目的密钥口令。第二个Changeme_123:更改密钥库的存储口令。iotdmServer:证书的别名,不指定,则默认为mykey。说明：该指令是将可信任的证书转换为JavaKeyStore格式的证书。如果指定的targetJKSPath不存在这个jks文件，则自动生成一个jks文件（注：目录不会自动产生，只会在指定目录下生成jks文件），如果已经存在了jks文件，则在该jks文件中追加该证书。2.转换iotdmClient.p12为keystore.jks:keytool-v-importkeystore-srckeystoreiotdmClient.p12-srcstoretypePKCS12-destkeystorejks/keystore.jks-deststoretypeJKS-srcstorepassChangeme_123-deststorepassChangeme_123-noprompt-changealias-destaliasiotdmalias-aliasiotdmclient参数说明：iotdmClient.p12:源证书路径。jks/keystore.jks:目标证书存储路径。第一个Changeme_123:更改条目的密钥口令。第二个Changeme_123:更改密钥库的存储口令。iotdmclient:证书的别名,不指定,则默认为mykey。说明：该指令是将p12的证书转换为JavaKeyStore格式的证书。如果指定的targetJKSPath不存在这个jks文件，则自动生成一个jks文件（注：目录不会自动产生，只会在指定目录下生成jks文件），如果已经存在了jks文件，则在该jks文件中追加该证书。对转换后的证书进行加载加载证书样例：publicclassTest{publicstaticvoidmain(String[]args){Cert.loadJKSCert();Cert.setInterface();}}publicstaticvoidloadJKSCert(){char[]password="Changeme_123".toCharArray();Filekeystore=newFile("keystore.jks");FiletrustFile=newFile("trustcer.jks");SSLContextsslcontext;try{sslcontext=SSLContexts.custom().useProtocol("TLSv1.2").loadTrustMaterial(trustFile).loadKeyMaterial(keystore,password,password).build();HttpClienthttpClient=HttpClients.custom().setSSLContext(sslcontext).build();Unirest.setHttpClient(httpClient);}catch(KeyManagementException|UnrecoverableKeyException|NoSuchAlgorithmException|KeyStoreException|CertificateException|IOExceptione){e.printStackTrace();}}publicstaticvoidsetInterface(){HttpResponse<JsonNode>response;try{response=Unirest.post("50:18443/iotdm/nb/v1/system/action/urn:huawei:iotdm:devmgr/get").header("content-type","application/json").queryString("domain","H1").asJson();}catch(UnirestExceptione){e.printStackTrace();}}说明：keystore.jks和trustcer.jks为3.3.1中转换后的证书所存放的位置，loadJKSCert()方法只需要调用一次即可，setInterface()方法中的内容可用对应接口内容进行替换。白名单配置接口数据项名称:白名单设备增加[white-list-device-add]例子：ID为000D6F00055CCF08的网关下连接了四个ID分别为2E00B136CB000515、2E0012F111000178、2E00B136CB000594和2E0012F111000181的设备，将这四个设备添加到白名单。接口：Java:JavaScript:白名单授权加网接口白名单加网[white-list-permit-join-net]例子：ID为000D6F00055CCF08的网关允许加网21秒。接口:Java:JavaScript:未知设备上线接口URL:解压unknown-device-online.zip压缩包，获取unknown-device-online.html，通过谷歌浏览器或火狐浏览器打开该html。该html已配置好请求链接，可直接使用。打开html后，显示如下，表示链接正常。如果有未知设备上线，在“open-quote!”的方框中会逐步显示。在“send”按钮前的输入框，输入以下参数，再点击“send”按钮，可查询一定时间范围内的未知设备上线事件。设备建档接口创建两个单控设备，设备esn分别为2E00216EFC000222、2E33000001000200，设备域(domain)为root，模型(model)为hwslc。接口:Java:JavaScript:注意事项EEM提供了物联网网关全网加网接口，全网加网操作后，相当于物联网网关不会对加网的设备作任何限制，任何设备都可入网，这个在多网关情况下操作比较危险，设备可能存在串网现象，因此在多网关情况下不推荐使用这个接口。远程访问原理在华为照明物联网解决方案中，EEM提供所有设备的远端操作接口，操作接口主要分GET接口、SET接口、ACTION接口。GET接口主要用于采集设备当前状态和数据，例如获取电压、电流、电量、功率、流明度等数据。SET接口主要用于配置设备参数和控制操作，例如设置设备上报周期、波动阈值、远程开关、调光等。ACTION接口主要用于命令操作，例如群组操作、自检等。远程操作接口支持对单个设备操作也支持批量操作。接口说明GET接口示例(读取调光等级)读取路灯控制器2E00216EFC000222的当前的调光等级接口：Java：JavaScript：SET接口示例（设置调光等级）设置路灯控制器2E00216EFC000222的调光等级为75%接口：URL::18443/iotdm/nb/v1/device/set/2E00216EFC000222/urn:huawei:iotdm:device/data/huawei-iotdm-device-sensor:dim-levelMethod:POSTBody:[{"index":0,"level":75}]Result:OKJava：JavaScript：ACTION接口示例（设备自检）对路灯控制器2E00216EFC000222发出设备自检命令接口：Java：JavaScript：ACTION接口示例（组播设置开关状态）将网关000D6F00055CCF08的第1组设备的开关状态全部设置为关接口：Java：JavaScript：ACTION接口示例（批量设置多个设备的开关状态）以下示例使用ACTION接口，对设备域3B01下所有的设备和路灯控制器2E00216EFC000222、2E00216EFC000223都执行关灯的操作接口:Java:JavaScript:注意事项路灯控制器的调光等级数据项的格式如下：路灯控制器的开关数据项的格式如下：计划控制原理华为照明物联网解决方案支持丰富的计划控制和可靠性保证，分别在EEM、物联网网关、路灯控制器侧都支持计划控制，同时物联网网关本地计划还支持经纬度计划。三层计划关系EEM[控制计划]：支持多物联网网关多设备控制计划，一般用于设备控制，例如每日晚上开灯、白天关灯。物联网网关[控制计划]：计划可以下发到物联网网关本地，物联网网关根据内部时钟进行判断，满足条件后执行控制计划，一般用于计划控制（调光、开关）。由于计划下发到物联网网关本地，因此物联网网关和EEM之间网络出现异常，也不受影响，亦可保证控制计划执行无误。物联网网关计划支持根据经纬度计算日出日落时间控制计划。路灯控制器[控制计划]：计划可以直接下发到路灯控制器，但是这个计划比较简单，一般设置为设备掉线执行。这样的话，物联网网关和路灯控制器之间Zigbee网络出现故障、或者网关出现故障无法正常工作，通过路灯控制器[控制计划]也可以确保路灯可正常工作。对时物联网网关：物联网网关对时通过NTP完成，自动从NTP服务器获取时钟。路灯控制器：路灯控制器每次上线后，自动向网关请求时钟进行对时，正常运行过程中，每24小时周期向网关请求对时。EEM提供接口可远程对物联网网关、路灯控制器进行对时。计划创建过程注意在路灯控制器[控制计划]创建时，一般要求先设置执行模式，标识什么时候计划可执行，一般默认设置为设备掉线状况下执行路灯控制器[控制计划]，执行模式一次设置之后，永久有效。接口说明EEM计划创建接口（采集计划）创建周期采集任务，开始时间为2016-02-0200:00:00，结束时间为2020-02-0200:00:00，按照每天零点执行，采集设备域为root的设备的总有功电能（total-active-energy）。接口Java:Javascript:网关计划创建接口（控制计划）例子：给ID为000D6F00055CCF08的网关连接的一个设备（ID号为：2E00216EFC000222）添加定时任务（其中涉及到的“冒号”后面没有括号的参数可以根据情况修改）。接口:Java:Javascript:网关计划执行结果上报接口url:wss://:18443/iotdm/stream/nb/v1/device解压设备消息通知侦听.zip压缩包，获取设备消息通知侦听.html，通过谷歌浏览器或火狐浏览器打开该html。该html已配置好请求链接，可直接使用。打开html后，显示如下，表示链接正常。如果有计划执行结果，在“open-quote!”的方框中会逐步显示。在“send”按钮前的输入框，输入以下参数，再点击“send”按钮，可查询一定时间范围内的计划执行结果。路灯控制器计划执行模式设置接口当计划存储在传感器设备中，这些计划可以由传感器设备在离线时执行，也可以在任何状态（不管离线与否）都执行，也可以全部禁止执行，我们将之称为“计划执行模式”。目前支持以下三种计划执行模式：取值说明forbid禁止设备中的所有的计划的执行when-offline当设备离线时，才允许执行设备中的计划always不管设备离线与否，都允许执行设备中的计划下面示例中，将设置路灯控制器2E00216EFC000222的计划执行模式为“when-offline”，以便让该路灯控制器中的计划仅在离线时执行。接口:Java:Javascript:路灯控制器计划创建接口以下示例对ID号为2E00216EFC000222的路灯控制器创建一个计划任务，使路灯控制器在每天9点钟对路灯开灯。接口:Java:Javascript:路灯控制器计划管理接口除了创建路灯控制器计划任务外，我们还可以“获取、删除、启动、停止”指定的计划任务，也可以查询指定计划任务的状态。请参考《EEMV200R007C10设备模型.docx》中内嵌的《EEMV200R007C10设备数据列表.xlsx》文档中的以下接口的说明：获取计划任务：plan-task-get删除计划任务：plan-task-del启动计划任务：plan-task-start停止计划任务：plan-task-stop查询计划任务状态：plan-task-status-query注意事项虽然路灯控制器计划支持设备在线时执行，但是由于单个设置计划，导致计划数比较多，因此建议不设置为在线执行，设置为设备掉线执行。策略控制原理在华为照明物联网解决方案中，支持将传感器和控制器的设备进行组合控制，通过传感器采集到的数据进行条件判断，满足条件，执行对应的动作。例如在路灯场景中，通常会通过流明度感应器采集的流明度作为条件判断，当前流明度大于80lux的时候，即可关闭路灯。EEM提供对应接口用于业务应用程序编辑这类策略达到智能化控制的目的。接口说明EEM策略创建接口（EEM策略）以下示例在平台侧创建策略，当路灯控制器2E00216EFC000222检查到流明度大于80时，对路灯进行关灯接口：Java：JavaScript：路灯控制器策略执行模式设置接口当策略存储在传感器设备中，这些策略可以由传感器设备在离线时执行，也可以在任何状态（不管离线与否）都执行，也可以全部禁止执行，我们将之称为“策略执行模式”。目前支持以下三种策略执行模式：取值说明forbid禁止设备中的所有的策略的执行when-offline当设备离线时，才允许执行设备中的策略always不管设备离线与否，都允许执行设备中的策略下面示例中，将设置路灯控制器2E00216EFC000222的策略执行模式为“when-offline”，以便让该路灯控制器中的策略仅在离线时执行。接口：Java：JavaScript：注：也可以通过GET接口读取路灯控制器的“策略执行模式”参数，参见GET接口示例(读取调光等级)，但URL要适当调整，如下所示：路灯控制器策略创建接口对路灯控制器2E00216EFC000222新增策略任务1，在每天的00:00:00至23:59:59时间段内，当光流明度位于区间[1000,2000)时且持续时间达到5秒后，将路灯关闭（仅为功能示例，策略内容不一定合理）接口:Java：JavaScript：路灯控制器策略管理接口除了创建路灯控制器策略任务外，我们还可以“获取、删除、启动、停止”指定的策略任务，也可以