华为照明物联网解决方案.docx

华为照明物联网解决方案业务应用开发指南文档版本发布日期华为技术有限公司35 / 41版权所有 华为技术有限公司 。保留一切权利。非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。商标声明和其他华为商标均为华为技术有限公司的商标。本文档提及的其他所有商标或注册商标，由各自的所有人拥有。注意您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。华为技术有限公司地址：深圳市龙岗区坂田华为总部办公楼邮编：网址：.前言读者对象本文档（本指南）主要适用于以下工程师：l 二次开发工程师符号约定在本文中可能出现下列标志，它们所代表的含义如下。符号说明用于警示紧急的危险情形，若不避免，将会导致人员死亡或严重的人身伤害。用于警示潜在的危险情形，若不避免，可能会导致人员死亡或严重的人身伤害。用于警示潜在的危险情形，若不避免，可能会导致中度或轻微的人身伤害。用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。“注意”不涉及人身伤害。用于突出重要关键信息、最佳实践和小窍门等。“说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。修改记录修改记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。文档版本 ()版本拟制修订责任人拟制修订日期修订内容及理由批准人罗振辉新拟制薄会健 吴英德新增接口描述薄会健 罗振辉苏本胜增加“远程、策略控制、告警”接口薄会健 鲍利亚修改版本号薄会健 目录前言概述目的概述术语整体架构架构图接口说明业务应用开发设备安装原理说明接口说明 加载证书获得证书并进行转换对转换后的证书进行加载白名单配置接口白名单授权加网接口未知设备上线接口设备建档接口注意事项远程访问原理接口说明 接口示例(读取调光等级) 接口示例（设置调光等级） 接口示例（设备自检） 接口示例（组播设置开关状态） 接口示例（批量设置多个设备的开关状态）注意事项计划控制原理三层计划关系对时计划创建过程接口说明 计划创建接口（采集计划）网关计划创建接口（控制计划）网关计划执行结果上报接口路灯控制器计划执行模式设置接口路灯控制器计划创建接口路灯控制器计划管理接口注意事项策略控制原理接口说明 策略创建接口（策略）路灯控制器策略执行模式设置接口路灯控制器策略创建接口路灯控制器策略管理接口注意事项告警原理接口说明设备上下线设备过压过流电量计量不匹配电量超出计量范畴注意事项参考资料 调测指南1 概述1.1 目的本指南旨在指导客户基于华为平台开发自己的业务系统，基于场景描述。1.2 概述适用于华为照明物联网解决方案所有的合作厂商、集成厂商进行业务系统构建参考。1.3 术语名称定义路灯管理系统物联网能效管理平台路灯控制器路灯的控制设备，可支持调光、计量、开关等功能。网关路由器设备，通过连接路灯控制器，通过、以太网、连接。设备通篇统一：网关：，路灯控制器：，单控设备：，设备域：2 整体架构2.1 架构图图2-1 架构图整个解决方案包括四个部分构成，主要是路灯控制器、华为物联网网关、平台、（业务系统），各部分功能描述如下。l 路灯控制器：控制路灯调光、开光，支持计量功能，可采集电压、电流、功率、电量、频率数据。l 物联网网关：连接路灯控制器，获取通过方式进行上行与平台进行通信。l 平台：连接物联网网关，提供上行、接口给第三方应用进行二次开发，可实现对路灯进行远程开关、调光等功能，也支持编制计划和策略控制。l ：客户基于平台开发的业务应用系统。2.2 接口说明表2-1 接口说明模块接口类型描述备注路灯控制器物联网网关无线通信技术，支持物联网网关以太网上行通信技术，协议通信接口，采用模型描述，用于下发远程控制命令、本地计划创建、策略创建等功能。接口，用于上报即时消息，如设备上线、下线，设备告警等。2.3 业务应用开发客户可以根据提供的接口进行业务应用开发，接口文档可参考华为物联网平台接口文档。后续章节会根据各类场景描述整个方案原理以及实用接口说明。的使用和的使用请参阅 参考资料章节应用开发前网关需要先配置连接到，配置方法参考下面的附件：3 设备安装3.1 原理说明图3-1 设备安装流程设备安装主要包括以下几个步骤；配置白名单：设备白名单给物联网网关，旨在告知物联网网关那些设备可入网。白名单授权加网：开启网络加网权限，设备可搜索网络，并加入到网络中，白名单之外设备当作非法设备处理，不可加入到网络中。设备上线：设备加网到网络之后，上报上线消息，通过接口告知，当前设备还处于未知设备状态。建档：设备上线之后，当前设备还处于未知设备状态，可调用接口进行建档，建档之后，设备才可正常操作，为可识别设备。在整个过程中，设备的状态变化，如下图所示；图3-2 设备状态图3.2 接口说明1 本文档示例中使用到的网关和传感器需要根据真实环境更改为正确的设备。2 本文档示例中使用的平台的地址是，在真实环境中需要将地址改为平台的地址。3 本文档示例中使用的平台的端口号是，这是基于协议访问平台的缺省缺口号（如果使用协议，缺省的端口号为）。3.3 加载证书3.3.1 获得证书并进行转换从路径下获得和两个证书。前置条件：由于使用的是 格式的证书，所以，必须使用提供的工具箱，因此，执行下面指令的电脑必须安装了( )，最好是配置了环境变量。.转换为: 参数说明：: 源证书路径。: 目标证书存储路径。第一个: 更改条目的密钥口令。第二个: 更改密钥库的存储口令。: 证书的别名,不指定,则默认为。说明：该指令是将可信任的证书转换为 格式的证书。如果指定的不存在这个文件，则自动生成一个文件（注：目录不会自动产生，只会在指定目录下生成文件），如果已经存在了文件，则在该文件中追加该证书。.转换为: 参数说明：: 源证书路径。: 目标证书存储路径。第一个: 更改条目的密钥口令。第二个: 更改密钥库的存储口令。: 证书的别名,不指定,则默认为。说明：该指令是将的证书转换为 格式的证书。如果指定的不存在这个文件，则自动生成一个文件（注：目录不会自动产生，只会在指定目录下生成文件），如果已经存在了文件，则在该文件中追加该证书。3.3.2 对转换后的证书进行加载加载证书样例： ( ) ();(); () (); (); (); ; ()()() (, , )(); ()()();(); ( ) (); () ; () (, )(, )(); ( ) (); 说明：和为中转换后的证书所存放的位置，()方法只需要调用一次即可，()方法中的内容可用对应接口内容进行替换。3.4 白名单配置接口数据项名称: 白名单设备增加例子：为的网关下连接了四个分别为、和的设备，将这四个设备添加到白名单。接口：:： : , , , : () (, ) (, ) ( : , , , ) ();: : , : , : , : , : : , : , : , : : , , , $()( () (););: : , : , : , : , : : , : , : , : , : : , , , $()( () (););3.5 白名单授权加网接口白名单加网例子：为的网关允许加网秒。接口:： : () (, ) (, ) ( ) ();: : , : , : , : , : : ,: , : , : $()( () (););3.6 未知设备上线接口:解压压缩包，获取，通过谷歌浏览器或火狐浏览器打开该。该已配置好请求链接，可直接使用。打开后，显示如下，表示链接正常。如果有未知设备上线，在“!”的方框中会逐步显示。在“”按钮前的输入框，输入以下参数，再点击“”按钮，可查询一定时间范围内的未知设备上线事件。参数： :, :预期返回报文:,:,:,:,:3.7 设备建档接口创建两个单控设备，设备分别为、，设备域()为，模型()为。接口:： : : , : , : , :, :, : , :, :, : : () (, ) (, ) ( : :, :, : , :, :, : ) ();: : , : , : , : , : : , : , : , : : :, :, : , :, :, : $()( () (););3.8 注意事项提供了物联网网关全网加网接口，全网加网操作后，相当于物联网网关不会对加网的设备作任何限制，任何设备都可入网，这个在多网关情况下操作比较危险，设备可能存在串网现象，因此在多网关情况下不推荐使用这个接口。4 远程访问4.1 原理在华为照明物联网解决方案中，提供所有设备的远端操作接口，操作接口主要分接口、接口、接口。 接口主要用于采集设备当前状态和数据，例如获取电压、电流、电量、功率、流明度等数据。接口主要用于配置设备参数和控制操作，例如设置设备上报周期、波动阈值、远程开关、调光等。 接口主要用于命令操作，例如群组操作、自检等。远程操作接口支持对单个设备操作也支持批量操作。4.2 接口说明4.2.1 接口示例(读取调光等级)读取路灯控制器的当前的调光等级接口：: : , : ： : , : , : , : , : : , : $()( () (););4.2.2 接口示例（设置调光等级）设置路灯控制器的调光等级为接口：: : , : ： () (, ) (, ) (, ) ( : , : ) ();： : , : , : , : , : : , : , : , : , : : , : $()( () (););4.2.3 接口示例（设备自检）对路灯控制器发出设备自检命令接口：: : , : , : , : ： () (, ) (, ) (, ) ();： : , : , : , : , : : , : , : , : , : $()( () (););4.2.4 接口示例（组播设置开关状态）将网关的第组设备的开关状态全部设置为关接口：: , :, :, : , : ： () (, ) (, ) (, ) ( , :, :, : , : ) ();： : , : , : , : , : : , : , : , : , : , :, :, : , : $()( () (););4.2.5 接口示例（批量设置多个设备的开关状态）以下示例使用接口，对设备域下所有的设备和路灯控制器、都执行关灯的操作接口:,:, , , : :, :, , :, :, : : () (, ) (, ) (, ) (:,:, , , : :, :, , :, :, : ) ();: : , : , : , : , : : , : , : , : , : :,:, , , : :, :, , :, :, : $()( () (););4.3 注意事项路灯控制器的调光等级数据项的格式如下：列表形式:索引(表示第路，目前路灯控制器只支持路，因此只能为),:调光等级，范围，表示关闭路灯控制器的开关数据项的格式如下：列表形式:索引(表示第路),:开关状态：关；开；保持(写有效）；取反（写有效）5 计划控制5.1 原理华为照明物联网解决方案支持丰富的计划控制和可靠性保证，分别在、物联网网关、路灯控制器侧都支持计划控制，同时物联网网关本地计划还支持经纬度计划。5.1.1 三层计划关系1 控制计划：支持多物联网网关多设备控制计划，一般用于设备控制，例如每日晚上开灯、白天关灯。2 物联网网关控制计划：计划可以下发到物联网网关本地，物联网网关根据内部时钟进行判断，满足条件后执行控制计划，一般用于计划控制（调光、开关）。由于计划下发到物联网网关本地，因此物联网网关和之间网络出现异常，也不受影响，亦可保证控制计划执行无误。物联网网关计划支持根据经纬度计算日出日落时间控制计划。3 路灯控制器控制计划：计划可以直接下发到路灯控制器，但是这个计划比较简单，一般设置为设备掉线执行。这样的话，物联网网关和路灯控制器之间网络出现故障、或者网关出现故障无法正常工作，通过路灯控制器控制计划也可以确保路灯可正常工作。5.1.2 对时物联网网关：物联网网关对时通过完成，自动从服务器获取时钟。路灯控制器：路灯控制器每次上线后，自动向网关请求时钟进行对时，正常运行过程中，每小时周期向网关请求对时。提供接口可远程对物联网网关、路灯控制器进行对时。5.1.3 计划创建过程图5-1 计划创建流程注意在路灯控制器控制计划创建时，一般要求先设置执行模式，标识什么时候计划可执行，一般默认设置为设备掉线状况下执行路灯控制器控制计划，执行模式一次设置之后，永久有效。5.2 接口说明5.2.1 计划创建接口（采集计划）创建周期采集任务，开始时间为，结束时间为，按照每天零点执行，采集设备域为的设备的总有功电能（）。接口: :, :, : , : , :, :, : * * ?, :, , , , :, , , : :, , :, :, : : () (, ) (, ) (: :, :, : , : , :, :, : * * ?, :, , , , :, , , : :, , :, :, : ) ();: : , : , : , : , : : , : , : , : : :, :, : , : , :, :, : * * ?, :, , , , :, , , : :, , :, :, : $()( () (););5.2.2 网关计划创建接口（控制计划）例子：给为的网关连接的一个设备（号为：）添加定时任务（其中涉及到的“冒号”后面没有括号的参数可以根据情况修改）。接口:： :, :, :, :, : ? , :, :, , , , , : :, , :, :, :, : ,: : () (, ) (, ) ( :, :, :, :, : ? , :, :, , , , , : :, , :, :, :, : ,: ) ();: : , : , : , : , : : , : , : , : :, :, :, :, : ? , :, :, , , , , : :, , :, :, :, : ,: $()( () (););5.2.3 网关计划执行结果上报接口:解压设备消息通知侦听压缩包，获取设备消息通知侦听，通过谷歌浏览器或火狐浏览器打开该。该已配置好请求链接，可直接使用。打开后，显示如下，表示链接正常。如果有计划执行结果，在“!”的方框中会逐步显示。在“”按钮前的输入框，输入以下参数，再点击“”按钮，可查询一定时间范围内的计划执行结果。参数： :, :预期返回报文：:,:,:,:,:,:,:5.2.4 路灯控制器计划执行模式设置接口当计划存储在传感器设备中，这些计划可以由传感器设备在离线时执行，也可以在任何状态（不管离线与否）都执行，也可以全部禁止执行，我们将之称为“计划执行模式”。目前支持以下三种计划执行模式：取值说明禁止设备中的所有的计划的执行当设备离线时，才允许执行设备中的计划不管设备离线与否，都允许执行设备中的计划下面示例中，将设置路灯控制器的计划执行模式为“”，以便让该路灯控制器中的计划仅在离线时执行。接口:：: () (, ) (, ) () ();: : , : , :, : , : : ,: , : , : $()( () (););5.2.5 路灯控制器计划创建接口以下示例对号为的路灯控制器创建一个计划任务，使路灯控制器在每天点钟对路灯开灯。接口: :, : , : , : , : , : : , : : () (, ) (, ) ( :, : , : , : , : , : : , : ) ();: : , : , : , : , : : , : , : , : :, : , : , : , : , : : , : $()( () (););5.2.6 路灯控制器计划管理接口除了创建路灯控制器计划任务外，我们还可以“获取、删除、启动、停止”指定的计划任务，也可以查询指定计划任务的状态。请参考 设备模型中内嵌的 设备数据列表文档中的以下接口的说明：l 获取计划任务：l 删除计划任务：l 启动计划任务：l 停止计划任务：l 查询计划任务状态：5.3 注意事项虽然路灯控制器计划支持设备在线时执行，但是由于单个设置计划，导致计划数比较多，因此建议不设置为在线执行，设置为设备掉线执行。6 策略控制6.1 原理在华为照明物联网解决方案中，支持将传感器和控制器的设备进行组合控制，通过传感器采集到的数据进行条件判断，满足条件，执行对应的动作。例如在路灯场景中，通常会通过流明度感应器采集的流明度作为条件判断，当前流明度大于的时候，即可关闭路灯。提供对应接口用于业务应用程序编辑这类策略达到智能化控制的目的。6.2 接口说明6.2.1 策略创建接口（策略）以下示例在平台侧创建策略，当路灯控制器检查到流明度大于时，对路灯进行关灯接口：: : ,: ,: ,: ,: ,: (. ) . ,: * * * * * ?,: ,: ,: , :,:,:,:,:,:： () (, ) (, ) (, ) (: : ,: ,: ,: ,: ,: (. ) . ,: * * * * * ?,: ,: ,: , :,:,:,:,:,:) ();： : , : , : , : , : : , : , : , : , : : : ,: ,: ,: ,: ,: (. ) . ,: * * * * * ?,: ,: ,: , :,:,:,:,:,:$()( () (););6.2.2 路灯控制器策略执行模式设置接口当策略存储在传感器设备中，这些策略可以由传感器设备在离线时执行，也可以在任何状态（不管离线与否）都执行，也可以全部禁止执行，我们将之称为“策略执行模式”。目前支持以下三种策略执行模式：取值说明禁止设备中的所有的策略的执行当设备离线时，才允许执行设备中的策略不管设备离线与否，都允许执行设备中的策略下面示例中，将设置路灯控制器的策略执行模式为“”，以便让该路灯控制器中的策略仅在离线时执行。接口：:： () (, ) (, ) (, ) () ();： : , : , : , : , : : , : , : , : , : $()( () (););注：也可以通过接口读取路灯控制器的“策略执行模式”参数，参见接口示例(读取调光等级)，但要适当调整，如下所示：6.2.3 路灯控制器策略创建接口对路灯控制器新增策略任务，在每天的至时间段内，当光流明度位于区间)时且持续时间达到秒后，将路灯关闭（仅为功能示例，策略内容不一定合理）接口: : , : , : , : , : , : , : , : , : , : : , : ： () (, ) (, ) (, ) ( : , : , : , : , : , : , : , : , : , : : , : ) ();： : , : , : , : , : : , : , : , : , : : , : , : , : , : , : , : , : , : , : : , : $()( () (););6.2.4 路灯控制器策略管理接口除了创建路灯控制器策略任务外，我们还可以“获取、删除、启动、停止”指定的策略任务，也可以查询指定策略任务的状态。请参考 设备模型中内嵌的 设备数据列表文档中的以下接口的说明：l 获取策略任务：l 删除策略任务：l 启动策略任务：l 停止策略任务：l 查询策略任务状态：6.3 注意事项无7