设备协议¶
设备协议用于通过编辑 JavaScript 或上载 JAR 包加载设备接入协议。本章说明如何创建、查看、编辑和删除设备协议。
前提条件¶
确保已在 应用注册 中注册应用。如有需要可联系系统管理员。
设备协议管理¶
创建设备协议¶
登录 EnOS 管理控制台,点击 IoT 协议连接器 > 设备协议,即可看到已创建的设备协议列表。
点击 新增设备协议。
填写以下信息。
名称:输入设备协议的名称。若需要输入不同语言环境的自定义名称,点击 国际化 图标 。
方式:选择处理数据转换方式。目前支持的方式包括以下两种。
描述:输入对设备协议的描述。
点击 确定 创建设备协议,其创建后将具有系统生成 ID,显示在设备协议列表中。
查看设备协议¶
进入 IoT 协议连接器 > 设备协议,从列表中寻找需要查看的设备协议,点击 查看 图标 。
设备协议的详细信息将显示在弹出窗口中。
编辑设备协议¶
进入 IoT 协议连接器 > 设备协议,从列表中寻找需要编辑的设备协议,点击 编辑 图标 。
除 协议 ID 外,其他字段均可编辑。
编辑完成后,点击 确定 以保存修改内容。
删除设备协议¶
进入 IoT 协议连接器 > 设备协议,从列表中寻找需要删除的设备协议,点击 删除 图标 。
删除后的设备协议不可恢复。若确定删除设备协议,在弹出窗口中点击 删除 按钮。
协议处理¶
设备协议中包含多种类型,目前支持 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" }