设备协议


设备协议用于通过编辑 JavaScript 或上载 JAR 包加载设备接入协议。本章说明如何创建、查看、编辑和删除设备协议。

前提条件

确保已在 应用注册 中注册应用。如有需要可联系系统管理员。

设备协议管理

创建设备协议

  1. 登录 EnOS 管理控制台,点击 IoT 协议连接器 > 设备协议,即可看到已创建的设备协议列表。

  2. 点击 新增设备协议

  3. 填写以下信息。

    • 名称:输入设备协议的名称。若需要输入不同语言环境的自定义名称,点击 国际化 图标 btn_internationalization

    • 方式:选择处理数据转换方式。目前支持的方式包括以下两种。

      • JAR:通过 JAR 的方式处理数据,指定 类名 并上传 JAR 包。更多信息,参见 JAR 方式

      • Script:通过 JavaScript 的方式处理数据,在脚本填写框中编写脚本。更多信息,参见 Script 方式


    • 描述:输入对设备协议的描述。


    ../../_images/device_protocol_create.png


  4. 点击 确定 创建设备协议,其创建后将具有系统生成 ID,显示在设备协议列表中。

查看设备协议

  1. 进入 IoT 协议连接器 > 设备协议,从列表中寻找需要查看的设备协议,点击 查看 图标 btn_view

  2. 设备协议的详细信息将显示在弹出窗口中。

编辑设备协议

  1. 进入 IoT 协议连接器 > 设备协议,从列表中寻找需要编辑的设备协议,点击 编辑 图标 btn_edit

  2. 协议 ID 外,其他字段均可编辑。

  3. 编辑完成后,点击 确定 以保存修改内容。

删除设备协议

  1. 进入 IoT 协议连接器 > 设备协议,从列表中寻找需要删除的设备协议,点击 删除 图标 btn_delete

  2. 删除后的设备协议不可恢复。若确定删除设备协议,在弹出窗口中点击 删除 按钮。

协议处理

设备协议中包含多种类型,目前支持 JAR 和 Script 两种方式,即可以通过 Java 代码或者 JavaScript 代码的形式对协议进行处理。

JAR 方式

  1. 源代码和示例代码可从 https://github.com/EnvisionIot/third-party-protocol 下载。

  2. 添加以下代码引入 core 的依赖。

    <dependency>
     <groupId>com.envisioniot.enos.third_party_protocol</groupId>
     <artifactId>core</artifactId>
     <version>1.0.0</version>
    </dependency>
    


    在 core 中的 ICodecPlugin 接口有三个方法,分别为 getProtocol()decode(Map<String, Object> meta, String originalReq)encodeResponse(Map<String, Object> meta, String originalReq, Response<T> response)。使用 JAR 时,可通过创建多个类实现该接口,不同的类可以处理不同的数据请求。


    有关方法参数的详细信息,参见 参数信息


  3. 指定使用的具体类名,例如 com.envisioniot.enos.third_party_protocol.haystack.CreateDeviceCodecPlugin

  4. 上传 JAR 包。

Script 方式

  1. 在页面中填写 JavaScript 脚本,实现 getProtocol()encodeResponse(meta, originalReq, response)decode(meta, originalReq) 三个函数。

    ../../_images/js_functions.png


    有关函数参数的详细信息,参见 参数信息


  2. 点击 测试 以测试和调试脚本,确保其能正常操作。

    • 调试时,需确保代码包含所有 3 个函数。

    • Script 的下拉列表中选择调试的函数。

    • 输入 Metadata输入 Response输入 OriginalReq 处填写函数所需的参数内容。

    • 点击 测试,所选函数的结果将显示在 输出 中。

参数信息

JARScript 中使用的方法/函数分别有 3 个参数,其说明,参阅以下内容。

Meta

Metadata 信息包含以下内容:

  • orgId:即使用该协议网关的 orgId。

  • netCompType:该协议网关中使用的网络组件的类型。

  • httpUri:网络组件接收到的 path。

  • protocolGateway:该协议网关的 ID。


使用 JAR 时,meta 的信息以 Map<String, Object> 的形式传入。在使用 Script 时,meta 以对象结构的形式传入。

Response

此处的 Response 为 EnOS 云端发出的 Response,例如创建设备返回的设备相关信息,或者更新模型、发送测点返回的成功/失败信息。请参阅以下示例。


{
    "mainCode": 200,
    "mainMessage": "OK",
    "items": []
}

OriginalReq

对于不同的业务请求,decode 方法应该将输入的数据转换成对应的请求格式。

  • JAR:请求的 request 应该属于 BaseRequest 类的某一个子类(如 CreateDeviceRequest)。

  • Script:Request 的结构应该符合以下列出的请求的格式,以根据 messageType 字段分辨请求的业务类型。目前支持的类型分别为 CreateDeviceUpdateModelPostMeasurePointLoginDevice


    1. CreateDevice 请求格式

    创建设备时需要确保协议网关中填入的应用有 设备管理服务 的全部权限。


    通过 model 和 device 信息创建设备

    示例:

    {
      "messageType": "CreateDevice",
      "models": [
        {
          "externalDeviceId": "",
          "externalModelId": "model-id-1",
          "name": {
            "defaultValue": "model-name-1",
            "i18nValue": { }
          },
          "measurepoints": {
            "mp001": "TEXT",
            "mp002": "ARRAY:INT"
            },
          "attrs": {
            "location": "TEXT"
            },
          "tags": {
            "someKeys": "tagValue"
          }
        }
      ],
      "devices": [
        {
          "externalDeviceId": "site-1-device-1",
          "externalModelId": "model-id-1",
          "name": {
            "defaultValue": "dev-1",
            "i18nValue": {}
          },
          "timezone": "Asia/Shanghai",
          "attrs": {
            "location": "Shanghai"
          },
          "tags": {
            "devTag": "some tag"
          }
        },
        {
          "externalDeviceId": "site-1-device-2",
          "externalModelId": "model-id-1",
          "name": {
            "defaultValue": "dev-2",
            "i18nValue": {}
          },
          "timezone": "Asia/Shanghai",
          "attrs": {
            "location": "Shanghai"
          },
          "tags": {
            "devTag": "some tag"
          }
        }
      ]
    }
    


    创建设备的请求中,需要有 modelsdevices 的内容,分别用于描述模型和设备相关的信息。


    2. UpdateModel 请求格式

    更新模型时需要确保协议网关中填入的应用有 设备管理服务 的全部权限。


    通过 externalDeviceId 更新模型

    该请求更新具有对应指定的设备 ID 的设备的模型。


    示例:

    {
      "messageType": "UpdateModel",
      "isPartialUpdate": "true",
      "models": [
        {
          "externalDeviceId": "site-1-device-1",
          "measurepoints": {
            "mp001": "TEXT",
            "mp002": "ARRAY:INT"
          },
          "attrs": {
            "location": "TEXT"
          }
        }
      ]
    }
    


    通过 externalModelId 更新模型

    该请求更新与指定模型 ID 对应的模型。


    示例:

    {
      "messageType": "UpdateModel",
      "isPartialUpdate": "true",
      "models": [
        {
          "externalModelId": "model-id-1",
          "measurepoints": {
            "mp001": "TEXT",
            "mp002": "ARRAY:INT"
          },
          "attrs": {
            "location": "TEXT"
          }
        }
      ]
    }
    


    3. PostMeasurePoint 请求格式

    通过 externalDeviceId 发送测点

    该请求发布与指定的设备 ID 对应的设备的测点。


    示例:

    {
      "messageType": "PostMeasurePoint",
      "ignoreInvalidMeasurePoint": true,
      "isRealtime": true,
      "measurepoints": [
        {
          "externalDeviceId": "site-1-device-1",
          "measurepoints": {
            "mp001": "hello",
            "mp002": [1, 2, 3]
          },
          "time": 123456678
        }
      ]
    }
    


    通过 assetId 发送测点

    该请求发布与指定的 asset ID 对应的设备的测点。


    示例:

    {
      "messageType": "PostMeasurePoint",
      "ignoreInvalidMeasurePoint": true,
      "isRealtime": true,
      "measurepoints": [
        {
          "assetId": "7lk3DQL1",
          "measurepoints": {
            "mp001": "hello",
            "mp002": [1, 2, 3]
          },
          "time": 123456678
        }
      ]
    }
    


    通过 productKey 与 deviceKey 发送测点

    该请求发布与指定的 product key 与 device key 对应的设备的测点。


    示例:

    {
      "messageType": "PostMeasurePoint",
      "ignoreInvalidMeasurePoint": true,
      "isRealtime": true,
      "measurepoints": [
        {
          "productKey": "mWqieraU",
          "deviceKey": "LSwYlj98Za",
          "measurepoints": {
            "mp001": "hello",
            "mp002": [1, 2, 3]
          },
          "time": 123456678
        }
      ]
    }
    


    4. LoginDevice 请求格式

    通过 externalDeviceId 登录设备

    该请求将登录与指定设备 ID 对应的设备。


    示例:

    {
      "messageType": "LoginDevice",
      "devices": [
        {
          "externalDeviceId": "site-1-device-1",
          "sign": "signBySignMethod",
        }
      ],
      "keepOnline": 300,
      "signMethod": "sha256",
      "timestamp": "1564988853275"
    }
    


    通过 assetId 登录设备

    该请求将登录与指定 asset ID 对应的设备。


    示例:

    {
      "messageType": "LoginDevice",
      "devices": [
        {
          "assetId": "7lk3DQL1",
          "sign": "signBySignMethod",
        }
      ],
      "keepOnline": 300,
      "signMethod": "sha256",
      "timestamp": "1564988853275"
    }
    


    通过 productKey 与 deviceKey 登录设备

    该请求将登录与指定 product key 与 device key 对应的设备。


    示例:

    {
      "messageType": "LoginDevice",
      "devices": [
        {
          "productKey": "mWqieraU",
          "deviceKey": "LSwYlj98Za",
          "sign": "signBySignMethod",
        }
      ],
      "keepOnline": 300,
      "signMethod": "sha256",
      "timestamp": "1564988853275"
    }