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

   {
       "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:

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:

   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:

   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:

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>

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):

{
    "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 Development License Agreement.