Skip to content

Onboarding Devices

In order to enable communication between devices and MindSphere, devices have to be onboarded to MindSphere. The Open Edge Device Kit acts as an agent which connects the device to MindSphere. This section describes the necessary steps for establishing a connection 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

The Open Edge Device Kit includes a built-in operation to onboard the device. This operation is started by publishing the onboarding configuration using the following topic via MQTT:

1
agentruntime/controlling/command/init

Code Example

  1. 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, "MQTTClientID");
    mqttClient.connect();
    
  2. Publish onboarding configuration file to the Open Edge Device Kit:

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

Onboarding Log Messages

The following log messages show logs for a successful onboarding operation using the Open Edge Device Kit:

1
2
3
4
5
2019-02-22 11:09:14,584 [DIAG] HandlerThread_11 | c.s.m.a.d.DiagnosticService | Agent onboarded successfully.
2019-02-22 11:09:14,584 [IN] HandlerThread_11 | c.s.m.a.d.DiagnosticService | inform() : DiagnosticEventMessage = <{"value":1,"state":"Onboarded"}>
2019-02-22 11:09:14,584 [IN] HandlerThread_11 | c.s.m.a.s.h.MessageHandlerBase | Publishing a message to MQTT Broker for topic <agentruntime/monitoring/diagnostic/onboarding>
2019-02-22 11:09:14,584 [IN] HandlerThread_11 | c.s.m.a.s.h.MessageHandlerBase | Message being published is <{"value":1,"state":"Onboarded"}>
2019-02-22 11:09:14,584 [IN] HandlerThread_11 | c.s.m.a.s.c.MqttBrokerClient | Publishing a message to MQTT broker for topic = <agentruntime/monitoring/diagnostic/onboarding>

Info

After onboarding successfully, the status indicator for the device in the Asset Manager should be green.

Time Sync

Before onboarding, the user is responsible for aligning the device's system time with MindSphere. This can be done using the generationTimeServer field in the onboarding configuration. This states MindSphere's creation time of the onboarding configuration in Zulu time format (e.g. 2018-09-18T10:09:36Z):

1
2
3
4
5
6
7
{
    "header": {
        "version": "0.1",
        "generationTimeServer": "<server_time>"
    },
    ...
}

Any questions left?

Ask the community


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