设备协议¶

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

开始前准备¶

你需要设备管理员角色的权限。如果没有请联系组织管理员添加，参见策略，角色，与权限。
确保已在 应用注册 中注册应用。更多信息，参见注册和管理应用。

设备协议管理¶

创建设备协议¶

登入 EnOS 管理控制台，点击 设备接入 > 设备协议，即可看到已创建的设备协议列表。
点击 新增设备协议。
填写以下信息。
- 名称：输入设备协议的名称。若需要输入不同语言环境的自定义名称，点击 国际化 图标。
- 方式：选择处理数据转换方式。目前支持的方式包括以下两种。
  - JAR：通过 JAR 的方式处理数据，指定类名并上传 JAR 包。更多信息，参见 JAR 方式。
  - Script：通过 JavaScript 的方式处理数据，在脚本填写框中编写脚本。更多信息，参见 Script 方式。
- 描述：输入对设备协议的描述。
点击确定创建设备协议，其创建后将具有系统生成 ID，显示在设备协议列表中。

查看设备协议¶

进入 设备接入 > 设备协议，从列表中寻找需要查看的设备协议，点击查看图标。
设备协议的详细信息将显示在弹出窗口中。

编辑设备协议¶

进入 设备接入 > 设备协议，从列表中寻找需要编辑的设备协议，点击编辑图标。
除 协议 ID 外，其他字段均可编辑。
编辑完成后，点击确定以保存修改内容。

删除设备协议¶

进入 设备接入 > 设备协议，从列表中寻找需要删除的设备协议，点击删除图标。
删除后的设备协议不可恢复。若确定删除设备协议，在弹出窗口中点击删除按钮。

协议处理¶

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

JAR 方式 ¶

源代码和示例代码可从 https://github.com/EnvisionIot/third-party-protocol 下载。
添加以下代码引入 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 时，可通过创建多个类实现该接口，不同的类可以处理不同的数据请求。

有关方法参数的详细信息，参见参数信息。
指定使用的具体类名，例如 com.envisioniot.enos.third_party_protocol.haystack.CreateDeviceCodecPlugin。
上传 JAR 包。

Script 方式 ¶

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

有关函数参数的详细信息，参见参数信息。
点击测试以测试和调试脚本，确保其能正常操作。
- 调试时，需确保代码包含所有 3 个函数。
- 从 Script 的下拉列表中选择调试的函数。
- 在 输入 Metadata、输入 Response、输入 OriginalReq 处填写函数所需的参数内容。
- 点击测试，所选函数的结果将显示在输出中。

参数信息 ¶

JAR 和 Script 中使用的方法/函数分别有 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 字段分辨请求的业务类型。目前支持的类型分别为 CreateDevice，UpdateModel，PostMeasurePoint 和 LoginDevice。

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"
      }
    }
  ]
}

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

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"
}