Onboarding Devices¶

In order to enable communication between devices and Insights Hub, devices have to be onboarded to Insights Hub. The Open Edge Device Kit acts as an agent which connects the device to Insights Hub. This section describes the necessary steps for establishing a connection to Insights Hub.

Registering the Device in Insights Hub¶

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 Insights Hub. This can be done using the generationTimeServer field in the onboarding configuration. This states Insights Hub'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>"
    },
    ...
}

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