开发设备代理¶
本指南描述了如何为第三方设备开发代理,以便使用 Open Edge Device Kit 处理与 MindSphere 的通信。Open Edge Device Kit 不仅将请求转发到 MindSphere,还执行一些常见的任务,例如对作业的定期轮询、安全性和身份验证活动以及数据缓存。
信息
占位符由尖括号 <>
表示。
准备¶
Open Edge Device Kit 可用作 docker 镜像和可执行版本的安装脚本。参考使用安装脚本的可执行程序版本或docker 版本执行以下步骤:
- 下载 Open Edge Device Kit。
- 安装 Open Edge Device Kit。
- 配置 Open Edge Device Kit的设置文件。
- 启动 Open Edge Device Kit。
上线设备¶
为了实现设备和 MindSphere 之间的通信,设备必须被上线到 MindSphere。
在 MindSphere 中注册设备¶
- 为使用 Asset Management Service 或者 Asset Manager 的设备要上传的数据创建一个 aspect 类型。
- 使用前面定义的 aspect 类型创建 asset type,并使用 Asset Management Service 或者 Asset Manager 实例化 asset。
- 创建设备类型并使用 Device Management Service 将其链接到前面定义的 asset type。
- 创建设备并使用Device Management Service将其链接到前面定义的的 asset。
-
使用 Asset Manager 下载上线配置文件。该文件包含必要的安全授权值,以便将其上线到设备上。
上线配置模板
{ "header": { "version": "0.1", "generationTimeServer": "<server_time>" }, "device": { "deviceIdentifier": "<device_id>" }, "agent": { "name": "<agent_name>", "proxy": { "proxyType": "FIXED", "host": "<proxy_host>:<proxy_port>", "protocol": "HTTP", "authenticationType": "BASIC", "user": "", "password": "" }, "agentId": "<agent_id>", "security": { "iat": "<Iat_value>", "baseUrl": "<mdsp_base_url>", "clientCredentialProfile": ["RSA_3072"], "tenant": "<mdsp_tenant_name>", "clientId": "<client_id>" } } }
使用 Open Edge Device Kit 上线设备¶
-
从上线配置中提取
generationTimeServer
字段,该字段在创建 Zulu 时间格式的 onboarding 配置时声明 MindSphere 的时间,例如:{ "header": { "version": "0.1", "generationTimeServer": "2018-09-18T10:09:36Z" }, ... }
-
设置设备时间为提取的 MindSphere 时间。
-
建立到 MQTT 代理的连接,其中
<mqtt_host>
是主机名,<mqt_port>
是端口:String broker = String.format("tcp://%s:%d", <mqtt_host>, <mqt_port>); MqttClient mqttClient = new MqttClient(broker, "<mqtt_client_id>"); mqttClient.connect();
-
将上线配置文件发布到 Open Edge Device Kit,该工具包将向 MindSphere 发送相应的请求。
String topic = "agentruntime/controlling/command/init"; mqttClient.publish(topic, initFileJsonContent.getBytes(StandardCharsets.ISO_8859_1));
将设备时钟与 MindSphere 同步¶
与 MindSphere 通信需要设备的系统时间与 MindSphere 保持一致。本部分描述如何使用 Open Edge Device Kit 的时钟偏移特性来调整设备时钟。
- 像之前一样建立到 MQTT 代理的连接。
-
订阅时钟偏移状态的主题。
mqttClient.subscribe("agentruntime/monitoring/clockskew", mqttMessageListener);
-
处理消息并生成一个日志消息。
@Override public void messageArrived(String topic, MqttMessage message) { LOG.info("MQTT message arrived: {} --> {}", topic, message.toString()); }
-
更新设备时间。
上传时间序列数据¶
创建数据源配置¶
-
在名为
data.cfg
的文件中定义数据源配置,格式如下所示。数据源配置示例
{ "dataConfiguration": { "agentId": "f5f6c04336fa4116a6417b8b1eef7495", "configurationId": "1", "uploadCycle": "10", "description": null, "dataSources": [{ "name": "my_data_source_1", "dataSourceId": "12cs3", "description": "my_descripton", "protocol": "my_protocol", "readCycleInSeconds": "5", "protocolData": { "myField1": "", "myField2": "", "myField3": "" }, "dataPoints": [{ "dataPointId": "0000", "name": "my_variable1", "description": "my_descripton_1", "unit": "PERCENT", "dataType": "INT", "dataPointData": { "myField1": "", "myField2": "" } }, { "dataPointId": "0001", "name": "my_variable_2", "description": "my_descripton_2", "unit": "PERCENT", "dataType": "LONG", "dataPointData": { "myField1": "", "myField2": "" } }] }] } }
-
上传数据源配置到 Device Configuration Service。
- 创建一个新的配置任务,将数据源配置上载到 Open Edge Device Kit 自动获取的设备上。
应用数据源配置¶
- 像之前一样建立到 MQTT 代理的连接。
-
配置设备上的每个数据读取器模块,以订阅数据源配置消息。
mqttClient.subscribe("cloud/monitoring/update/configuration/<protocol>", mqttMessageListener);
-
等待 Open Edge Device Kit 发布每个数据源的数据源配置消息。
上传时间序列数据¶
- 像之前一样建立到 MQTT 代理的连接。
-
用 JSON 格式准备时间序列数据。
String json_template = "[\n" + " {\n" + " \"timestamp\": \"<time_stamp>\",\n" + " \"values\": [\n" + " {\n" + " \"dataPointId\": \"<data_point_id>\",\n" + " \"value\": \"<data_value>\",\n" + " \"qualityCode\": \"<quality_code>\"\n" + " }\n" + " ]\n" + " }\n" + "]"; json_template = json_template.replace("<time_stamp>", data.getTimestamp()); json_template = json_template.replace("<data_point_id>", data.getDataPointID()); json_template = json_template.replace("<data_value>", data.getDataValue()); json_template = json_template.replace("<quality_code>", data.getQualityCode());
-
将数据发布到 Open Edge Device Kit。
String topic_template = "runtime/inject/data/timeseries/<protocol>/<data_source_id>"; topic_template = topic_template.replace("<protocol>", dataTimeSeriesProtocol); topic_template = topic_template.replace("<data_source_id>", dataTimeSeriesSource); mqttClient.publish(topic_template, json_template.getBytes());
缓存数据¶
Open Edge Device Kit 为时间序列数据上传提供了缓存机制,以防止数据丢失。如果 MindConnect 交换端点不可用,则将接收到的时间序列数据加密并缓存在本地文件系统中。当端点再次可访问时,将上传存储的数据。
注意
缓存大小是有限的,传入的数据将在一段时间后开始覆盖旧的缓存数据。缓存大小可以使用settings file中的参数 offlineCache
> size
来调整。
信息
发布诊断数据的同时使用主题runtime/inject/diag/timeseries/{protocol}/{data_source_id}
。
访问存入数据¶
Open Edge Device Kit 每天至少自动上传一次日志数据到 MindSphere。当日志文件的大小超过设置中配置的限制时,它执行额外的上传。日志数据可以像以下一样访问。
- 从 Launchpad中打开**Fleet Manager**。
- 选择代表你设备的 asset。
- 在 asset 视图中打开一个**文件**选项卡。
- 选择想要的日志文件并单击选项卡底端的**下载**。
读取诊断数据¶
客户端通过订阅由 Open Edge Device Kit发布的 agentruntime/monitoring/diagnostic/
主题收到诊断信息。Open Edge Device Kit 发布连接状态,上线状态,缓存状态和数据源状态。
停止数据上传¶
所有数据阅读器必须使用各自的 <protocol>
和 <data_source_id>
参数订阅下面的主题。当他们收到这个消息时,他们应该停止所有的活动。
runtime/data/timeseries/stop/<protocol>/<data_source_id>
agentruntime/controlling/command/stop
下线设备¶
Open Edge Device Kit 检测令牌何时失效,并从设备的磁盘中删除敏感数据(数据源配置、代理设置和凭证)。
- 从 Launchpad 中打开 Asset Manager。
- 选择代表你设备的 asset。
- 选择 asset 详细信息左侧的插件图块。
- 单机**上线状态**菜单并选择**下线**。设备可以继续上传数据直到令牌过期(至多1小时)。
- 在关闭设备之前,等待 Open Edge Device Kit 使用
agentruntime/monitoring/diagnostic/onboarding
主题发布其状态Offboarded
。
提示
如果设备在 Open Edge Device Kit 声明下线完成之前关闭,敏感数据将留在设备的磁盘中。
停止代理¶
- 像之前一样建立到 MQTT 代理的连接。
-
发布停止命令到Open Edge Device Kit:
String message = "STOP COMMAND"; String topic = "agentruntime/controlling/command/stop"; mqttClient.publish(topic, message.getBytes(StandardCharsets.ISO_8859_1));
-
等待30秒或者直到 Open Edge Device Kit 通过
agentruntime/monitoring/opresult/stop
发布成功消息。{ "value": 0, "status": "Stopped" }
-
在收到成功消息或30秒后仍未收到成功消息后,关闭 Open Edge Device Kit 进程。发送停止命令后,Open Edge Device Kit 可以按照上面的描述重新启动。