Skip to content

开发设备代理

本指南描述了如何为第三方设备开发代理,以便使用 Open Edge Device Kit 处理与 MindSphere 的通信。Open Edge Device Kit 不仅将请求转发到 MindSphere,还执行一些常见的任务,例如对作业的定期轮询、安全性和身份验证活动以及数据缓存。

信息

占位符由尖括号 <> 表示。

准备

Open Edge Device Kit 可用作 docker 镜像和可执行版本的安装脚本。参考使用安装脚本的可执行程序版本docker 版本执行以下步骤:

  1. 下载 Open Edge Device Kit。
  2. 安装 Open Edge Device Kit。
  3. 配置 Open Edge Device Kit的设置文件。
  4. 启动 Open Edge Device Kit。

上线设备

为了实现设备和 MindSphere 之间的通信,设备必须被上线到 MindSphere。

在 MindSphere 中注册设备

  1. 为使用 Asset Management Service 或者 Asset Manager 的设备要上传的数据创建一个 aspect 类型。
  2. 使用前面定义的 aspect 类型创建 asset type,并使用 Asset Management Service 或者 Asset Manager 实例化 asset。
  3. 创建设备类型并使用 Device Management Service 将其链接到前面定义的 asset type。
  4. 创建设备并使用Device Management Service将其链接到前面定义的的 asset。
  5. 使用 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 上线设备

  1. 从上线配置中提取 generationTimeServer 字段,该字段在创建 Zulu 时间格式的 onboarding 配置时声明 MindSphere 的时间,例如:

    {
        "header": {
            "version": "0.1",
            "generationTimeServer": "2018-09-18T10:09:36Z"
        },
        ...
    }
    

  2. 设置设备时间为提取的 MindSphere 时间。

  3. 建立到 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();
    
  4. 将上线配置文件发布到 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 的时钟偏移特性来调整设备时钟。

  1. 像之前一样建立到 MQTT 代理的连接。
  2. 订阅时钟偏移状态的主题

    mqttClient.subscribe("agentruntime/monitoring/clockskew", mqttMessageListener);
    
  3. 处理消息并生成一个日志消息。

    @Override
    public void messageArrived(String topic, MqttMessage message) {
        LOG.info("MQTT message arrived: {} --> {}", topic, message.toString());
    }
    
  4. 更新设备时间。

上传时间序列数据

创建数据源配置

  1. 在名为 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": ""
                    }
                }]
            }]
        }
    }
    
  2. 上传数据源配置到 Device Configuration Service

  3. 创建一个新的配置任务,将数据源配置上载到 Open Edge Device Kit 自动获取的设备上。

应用数据源配置

  1. 像之前一样建立到 MQTT 代理的连接。
  2. 配置设备上的每个数据读取器模块,以订阅数据源配置消息

    mqttClient.subscribe("cloud/monitoring/update/configuration/<protocol>", mqttMessageListener);
    
  3. 等待 Open Edge Device Kit 发布每个数据源的数据源配置消息。

上传时间序列数据

  1. 像之前一样建立到 MQTT 代理的连接。
  2. 用 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());
    
  3. 将数据发布到 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。当日志文件的大小超过设置中配置的限制时,它执行额外的上传。日志数据可以像以下一样访问。

  1. 从 Launchpad中打开**Fleet Manager**。
  2. 选择代表你设备的 asset。
  3. 在 asset 视图中打开一个**文件**选项卡。
  4. 选择想要的日志文件并单击选项卡底端的**下载**。

日志文件下载

读取诊断数据

客户端通过订阅由 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 检测令牌何时失效,并从设备的磁盘中删除敏感数据(数据源配置、代理设置和凭证)。

  1. 从 Launchpad 中打开 Asset Manager
  2. 选择代表你设备的 asset。
  3. 选择 asset 详细信息左侧的插件图块。
  4. 单机**上线状态**菜单并选择**下线**。设备可以继续上传数据直到令牌过期(至多1小时)。
  5. 在关闭设备之前,等待 Open Edge Device Kit 使用 agentruntime/monitoring/diagnostic/onboarding 主题发布其状态 Offboarded

提示

如果设备在 Open Edge Device Kit 声明下线完成之前关闭,敏感数据将留在设备的磁盘中。

停止代理

  1. 像之前一样建立到 MQTT 代理的连接。
  2. 发布停止命令到Open Edge Device Kit:

    String message = "STOP COMMAND";
    String topic = "agentruntime/controlling/command/stop";
    
    mqttClient.publish(topic, message.getBytes(StandardCharsets.ISO_8859_1));
    
  3. 等待30秒或者直到 Open Edge Device Kit 通过 agentruntime/monitoring/opresult/stop 发布成功消息。

    {
        "value": 0,
        "status": "Stopped"
    }
    
  4. 在收到成功消息或30秒后仍未收到成功消息后,关闭 Open Edge Device Kit 进程。发送停止命令后,Open Edge Device Kit 可以按照上面的描述重新启动。


Last update: March 22, 2023