Skip to content

Developing Device Agents

This guide describes how to develop agents for third-party devices to handle communication with MindSphere using the Open Edge Device Kit. The Open Edge Device Kit not only forwards requests to MindSphere, but also performs common tasks such as periodic polls for jobs, security and authentication activities and data caching.

Info

Placeholders are indicated by angular brackets <>.

Preparation

The Open Edge Device Kit is available as docker image and as executable version with installation script. Refer to the Getting started for the executable version using installation script or the docker version to perform the following steps:

  1. Download the Open Edge Device Kit.
  2. Install the Open Edge Device Kit.
  3. Configure settings file of the Open Edge Device Kit.
  4. Start the Open Edge Device Kit.

Onboarding Devices

In order to enable communication between devices and MindSphere, devices have to be onboarded to MindSphere.

Registering the Device in MindSphere

  1. Create an aspect type for the data to be uploaded by the device using the Asset Management Service or the Asset Manager.
  2. Create an asset type with the previously defined aspect type and instantiate an asset using the Asset Management Service or the Asset Manager.
  3. Create the device type and link it to the previously defined asset type using the Device Management Service.
  4. Create the device and link it to the previously defined asset using the Device Management Service.
  5. Download the onboarding configuration file using the Asset Manager. This file contains the necessary security authorization values for it to onboard the device.

    Onboarding Configuration Template
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    {
        "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>"
            }
        }
    }
    

Onboarding the Device using the Open Edge Device Kit

  1. Extract the generationTimeServer field from the onboarding configuration which states MindSphere's time at creation of the onboarding configuration in Zulu time format, e.g.:

    1
    2
    3
    4
    5
    6
    7
    {
        "header": {
            "version": "0.1",
            "generationTimeServer": "2018-09-18T10:09:36Z"
        },
        ...
    }
    
  2. Set the device's time to the extracted MindSphere time.

  3. Establish a connection to the MQTT broker where <mqtt_host> is the host name and <mqt_port> is the port:

    1
    2
    3
    String broker = String.format("tcp://%s:%d", <mqtt_host>, <mqt_port>);
    MqttClient mqttClient = new MqttClient(broker, "<mqtt_client_id>");
    mqttClient.connect();
    
  4. Publish the onboarding configuration file to the Open Edge Device Kit which sends a respective request to MindSphere.

    1
    2
    String topic = "agentruntime/controlling/command/init";
    mqttClient.publish(topic, initFileJsonContent.getBytes(StandardCharsets.ISO_8859_1));
    

Synchronizing the Device Clock with MindSphere

For communication with MindSphere it is required that the device's system time is aligned with MindSphere. This section describes how to use the clock skew feature of the Open Edge Device Kit for adjusting the device clock.

  1. Establish a connection to the MQTT broker as shown before.
  2. Subscribe to the topic for the clock skew status.

    1
    mqttClient.subscribe("agentruntime/monitoring/clockskew", mqttMessageListener);
    
  3. Handle the message and generate a log message.

    1
    2
    3
    4
    @Override
    public void messageArrived(String topic, MqttMessage message) {
        LOG.info("MQTT message arrived: {} --> {}", topic, message.toString());
    }
    
  4. Update the device time.

Uploading Time Series Data

Creating the Data Source Configuration

  1. Define the data source configuration in a file named data.cfg with the format shown below.

    Data Source Configuration Sample
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    {
        "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. Upload the data source configuration to the Device Configuration Service.

  3. Create a new configuration task to upload the data source configuration to the device which is automatically fetched by the Open Edge Device Kit.

Applying the Data Source Configuration

  1. Establish a connection to the MQTT broker as shown before.
  2. Configure each data reader module on the device to subscribe to the data source configuration message.

    1
    mqttClient.subscribe("cloud/monitoring/update/configuration/<protocol>", mqttMessageListener);
    
  3. Wait for the Open Edge Device Kit to publish the data source configuration message for each data source.

Uploading Time Series Data

  1. Establish a connection to the MQTT broker as shown before.
  2. Prepare the time series data in JSON format.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    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. Publish the data to the Open Edge Device Kit.

    1
    2
    3
    4
    5
    6
    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());
    

Caching Data

The Open Edge Device Kit provides a caching mechanism for time series data upload to prevent data loss. The received time series data is encrypted and cached on local file system, if the MindConnect Exchange endpoint is not reachable. The stored data is uploaded when the endpoint is reachable again.

Attention

The cache size is limited and incoming data will start to overwrite the old cached data after a while. The cache size can be adjusted using the parameter offlineCache > size in the settings file.

Info

Publish diagnostic data simultaneously using the topic runtime/inject/diag/timeseries/{protocol}/{data_source_id}.

Accessing Logging Data

The Open Edge Device Kit automatically uploads log data to MindSphere at least once a day. It performs additional uploads when the size of the log file exceeds the limit configured in the settings. Log data can be accessed as follows.

  1. Open Fleet Manager from the MindSphere Launchpad.
  2. Select the asset that represents your device.
  3. Open a Files tab in the asset view.
  4. Select the desired log files and click on Download at the bottom of the tab.

Log File Download

Reading Diagnostic Data

Clients receive diagnostic information by subscribing to the agentruntime/monitoring/diagnostic/ topics published by the Open Edge Device Kit. The Open Edge Device Kit publishes connection status, onboarding status, buffer status, and data source status.

Stopping Data Upload

All data readers must subscribe to the topics below using their respective <protocol> and <data_source_id> parameters. When they receive this message, they shall stop all activities.

1
2
runtime/data/timeseries/stop/<protocol>/<data_source_id>
agentruntime/controlling/command/stop

Offboarding Devices

The Open Edge Device Kit detects when its token becomes invalid and deletes sensitive data (data source configurations, proxy settings and credentials) from the device's disk.

  1. Open Asset Manager from the MindSphere Launchpad.
  2. Select the asset that represents your device.
  3. Select the plugin tile to the left of the asset details.
  4. Click on the Onboarding Status menu and select Offboard. The device can continue to upload data until its token expires (max 1hour).
  5. Wait for the Open Edge Device Kit to publish its status Offboarded using the topic agentruntime/monitoring/diagnostic/onboarding before turning off the device.

Hint

If the device is turned off before the Open Edge Device Kit states that offboarding is complete, sensitive data will remain on the device's disk.

Stopping the Agent

  1. Establish a connection to the MQTT broker as shown before.
  2. Publish the stop command to the Open Edge Device Kit:

    1
    2
    3
    4
    String message = "STOP COMMAND";
    String topic = "agentruntime/controlling/command/stop";
    
    mqttClient.publish(topic, message.getBytes(StandardCharsets.ISO_8859_1));
    
  3. Wait for 30 seconds or until the Open Edge Device Kit publishes the success message via agentruntime/monitoring/opresult/stop

    1
    2
    3
    4
    {
        "value": 0,
        "status": "Stopped"
    }
    
  4. After receiving the success message or if it has not arrived after 30 seconds, kill the Open Edge Device Kit process. After sending the stop command, the Open Edge Device Kit can be restarted as described above.

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.