端侧规则

概述

在云端规则中，用户创建的规则的解析及执行均在云端完成，云平台需要判断条件是否满足并触发相应的设备联动操作。端侧规则是指用户在云平台创建的设备联动规则，可以下发到端侧设备，该设备上会运行端侧规则引擎，对云端下发的规则进行解析并执行。端侧规则可以在网络中断或设备无法与云端交互情况下，继续在端侧执行指定规则。端侧规则可以扩展用户应用场景，提升端侧设备运行的稳定性及执行效率等。例如：设置室内光照强度低于20时，打开灯控总开关，自动照明，实现不依赖网络设备的智能控制。

图1 端侧规则架构图

相关背景概念说明可参考基础概念。

使用场景

公路隧道中的监控设备种类较多，数量较大，并且隧道内网络环境复杂，网络质量也不稳定。然而，在应急处理时对网络实时性要求较高，因此无法将应急设备间的联动完全依赖于云端规则处理，需要借助端侧规则引擎实现预案联动。在实施时，可以预先针对火灾、交通事故等不同情况制定相应的设备联动预案。监控人员可以根据隧道内发生的情况，一键启动设备预案，通过端侧规则引擎实现多种相关设备同步进行状态变化，从而降低对网络质量的依赖，提高整体设备联动效率。例如，当烟道温度过高时，可以联动排水阀控制器打开排水阀实现降温；当一氧化碳浓度过高时，可以联动covi设备控制风机来通风。

使用限制

• 相对云端规则，目前端侧规则的执行动作只支持命令下发。
• 设备需适配指定的SDK：Device SDK C_v1.1.2及以上版本。
• 设备需通过上述SDK提供的API，主动上报SDK版本号至华为云IoT平台。

使用说明与示例

下面以智能路灯系统为例，介绍如何使用端侧规则。

1. 访问设备接入服务，单击“管理控制台”进入设备接入控制台。选择您的实例，单击实例卡片进入。
2. 创建产品以及新增物模型。
   1. 创建产品，进入管理控制台，选择您的实例，单击实例卡片进入。选择“产品-创建产品”，单击“设备类型”，在弹出的对话框内选择“智能路灯”，填写好产品名称后单击“确定”。
      图2 创建产品-SmartLight
      
   2. 创建模型，右侧选择“产品”，找到“SmartLight”，然后单击“详情”。
      图3 产品-查看SmartLight详情
      
   3. 进入产品信息页面后，单击“导入库模型”，选择“SmartStreetLight”，然后单击“确定”。
      图4 产品-导入库模型SmartStreetLight
      
   4. 单击“基本信息”，可见模型定义中包含两个服务，分别为“BasicData”和“LightControl”，单击“BasicData”可见服务详情中包含一个名为“luminance”的属性。单击“LightControl”可见其包含一个名为“switch”的命令。
      图5 模型定义-SmartLight
      

3. 在左侧选择“设备-所有设备”，单击“注册设备”。选择步骤2创建产品选择的资源空间以及所属产品，填写设备标识码，单击“确定”。
   图6 设备-注册密钥设备
   

4. 设备创建成功，复制设备密钥，此处需要保存好设备密钥，后面需要用到。
   图7 设备-注册设备成功
   

5. 创建规则。
   1. 在左侧选择“规则-设备联动”，单击上方"所属资源空间"，选择设备所在产品的所属资源空间，然后单击“创建规则”。
      图8 设备联动-创建规则
      
   2. 进入创建规则的页面，填写规则名称，选中“端侧执行”，然后选择规则执行设备，即选择将此条规则下发给哪个设备去解析执行。
      图9 新建联动规则-端侧规则基本信息
      
   3. 选择刚刚创建的设备“smartlight001”，选好后，单击右下角按钮“确定”。
      图10 新建联动规则-选择端侧设备
      
      说明：

      只有适配了端侧SDK的设备（目前只支持Device SDK C_v1.1.2版本），才支持创建端侧规则。

   4. 单击“添加条件”，可见设备为本设备不可选择；单击“添加动作”，用户可根据需求选择指定设备，该设备可以为本设备，也可以为其他设备。
      图11 新建联动规则-条件及动作说明
      
   5. 在触发条件中配置属性触发为“luminance<= 27”，在执行动作中配置control_light指令并填写参数值，light_state为“on”。
      图12 新建联动规则-条件及动作
      

6. 参考下表参数说明，创建设备联动规则。

   表1 参数说明

   参数名称	说明
   规则名称	创建的规则名称。
   激活规则	勾选：创建规则后，规则处于激活状态。 不勾选：创建规则后，规则处于未激活状态。
   生效时间	一直生效：没有时间限制，持续检查是否满足当前规则条件。 指定时间：可以选择时间段，在特定的时间内检查是否满足规则条件。 说明： 由于端侧规则存储在内存当中，当设备下电时，端侧存储的规则将清空。当设备重新开机或上电时，端侧设备会从云端更新该设备的历史全量规则。
   描述	对该规则的描述。
   触发条件	满足条件：可设置满足全部条件，或者任意一个条件。 说明： 当设置满足全部条件时，不能同时设置设备属性触发和定时触发，只支持同时设置多种设备属性触发。 触发类型：目前只支持设备属性触发和定时触发。 设备属性触发：设备上报属性时触发。 选择服务：选择对应的服务类型。 选择属性：选择满足条件后上报数据的设备属性。 说明： 属性的数据类型为int和decimal时，支持选择多种判断符号。 属性的数据类型为string时，判断条件仅支持相等。 定时触发：设置个性化的定时条件，如每日定时触发或按策略定时触发。 每日定时触发：可以设置规则触发的时间点，该条件一般用于周期性的触发条件，如每天7:00，关闭路灯。 按策略定时触发 时间点：可以选择规则触发的起始时间点。 重复次数：规则重复触发的次数（1~1440次）。 间隔（分钟）：在起始时间点后，重复触发规则的时间间隔（1~1440分钟）。
   执行动作	单击“添加动作”，设置在规则触发后，需要执行的动作。 下发命令：依次选择需要执行下发命令的设备、服务、命令，然后配置下发命令的参数。

7. 单击右下角“创建规则”，完成端侧规则的创建。新创建的规则默认激活，用户可以在规则列表“状态”列禁用规则。
8. 编写设备侧代码。在支持端侧规则引擎的SDK中（目前仅支持Device C SDK），只需要用户实现属性上报及命令处理的回调函数即可。单击这里获取iot-device-sdk-c，按说明文档步骤操作，在准备工作完成之后进行以下修改：
   1. 打开文件src/device_demo/device_demo.c，找到函数HandleCommandRequest。
      图13 命令处理
      

      此处为方便示例，将上述命令处理实现为：

          printf("----- execute command----- \n");
          printf("service_id: %s\n", command->service_id);
          printf("command_name: %s\n", command->command_name);
          printf("paras: %s\n", command->paras);
   2. 打开文件src/device_demo/device_demo.c，找到函数TestPropertiesReport。
      图14 代码替换
      

      替换代码为：

      const int serviceNum = 1; // reported services' total count
      ST_IOTA_SERVICE_DATA_INFO services[serviceNum];
      
      #define MAX_BUFFER_LEN 70
      char propsBuffer[MAX_BUFFER_LEN];
      //此处为获取温度值的示例，从真实传感器获取数值需要由用户实现
      if(sprintf_s(propsBuffer, sizeof(propsBuffer), "{\"luminance\": %d}", 20) == -1){
      printf("can't create string of properties\n");
      return;
      }
      
      services[0].event_time = GetEventTimesStamp(); // if event_time is set to NULL, the time will be the iot-platform's time.
      services[0].service_id = "BasicData";
      services[0].properties = propsBuffer;
      
      int messageId = IOTA_PropertiesReport(services, serviceNum, 0, NULL);
      if (messageId != 0) {
      printf("report properties failed, messageId %d\n", messageId);
      }
      free(services[0].event_time);
   3. 编译sdk并执行。观察输出，可以看到对应的command。

      ----- execute command-----
      service_id: BasicData
      command_name: control_light
      paras: {
              "light_state":       "on"
      }

      以上日志仅为一个示例。用户需要实现上述1中具体的命令处理代码。

      跨设备执行命令时，需要设备间具备相互通信的能力。同时由于用户使用的通信协议可能不同，如WiFi，BLE，ZigBee等，所以要调用函数IOTA_SetDeviceRuleSendMsgCallback注册自定义发送函数。

      Demo中已默认注册HandleDeviceRuleSendMsg，用户需要自行在预置函数HandleDeviceRuleSendMsg实现消息发送。执行命令的设备接收消息后，则需要自行实现命令解析和执行。

      图15 解析命令并执行