Cancel
Showing results for 
Search instead for 
Did you mean: 
Highlighted

OEDK - Step by Step Guide

Siemens Genius Siemens Genius
Siemens Genius

Hi,

This is my second post for OEDK. In this post, I will try to do a step-by-step guide on:

  1. how to setup OEDK on your PC
  2. how to on-board an agent using OEDK
  3. how to configure MQTT client to communicate with the OEDK MQTT Broker
  4. how to send TimeSeries Data using OEDK agent to MindSphere

OEDK comes in Docker Container as well as an executable script.

 

Video Demonstration:

 

 

 

Step 1: 

 

In this tutorial, I will be using the Docker Container based agent on my Macintosh for demonstration. Install Docker version 18 or higher and Docker Compose version 1.23 or higher from https://docs.docker.com/compose/install/. More details about installing docker can be found here

 

 

Step 2:

 

Download OEDK Docker Image from here and extract the contents of the zip file. 

Screenshot 2019-07-02 at 4.22.54 PM.png

 

Step 3: Starting OEDK

 

We will use a Password Generator to create our rand.dat file. For that, please visit here and follow the steps shown in the below screenshot.Screenshot 2019-07-02 at 4.26.35 PM.png

 

Open your terminal and CD into the folder where you extracted the OEDK docker agent files and create a file called rand.dat and paste the password you generated in the above step inside the rand.dat file. Remember to save the file.

 

Screenshot 2019-07-02 at 4.38.16 PM.png

 

 

After the above  step, your OEDK folder should look like this:

Screenshot 2019-07-02 at 4.40.39 PM.png

 

Now, it's time to build the docker-compose.yml file. Type the following command at your terminal, from within the OEDK folder where your docker-compose.yml file is:

 

docker-compose build

 

If all goes well, your build should be successful as shown below:

 

Screenshot 2019-07-02 at 4.42.54 PM.png

 

 

Now run the following from within the OEDK folder to start the OEDK Agent, which will start 2 docker containers (one is the Device_Kit and the other is MQTT_Broker)

 

Screenshot 2019-07-02 at 4.48.40 PM.png

 

You now have successfully started the OEDK agent on your local machine. I would recommend using tool like Portainer or Kitematics to manage your Container in a visual interface. I've Kitematics on my Mac to manage containers. 

 

Screenshot 2019-07-02 at 4.54.28 PM.png

 

 

Step 4: Create Persistent Data Volume

 

I would also strongly recommend setting up persistent data volume, as this will simplify lot of things as we work with docker containers. To setup Persistent volume, open Kitematic, and click on the Device_Kit container, then click on the /persistent_massdata. You will receive a popup window asking you if you want to create a persistent data volume. Select Enable Volumes as shown below.

 

Screenshot 2019-07-02 at 4.55.54 PM.png

 

When you click Enable Volumes, you will be redirected to the location on your PC where the folder is created. Please note, i've renamed my folder name to massdata instead of persistent_massdata. 

Screenshot 2019-07-02 at 5.00.25 PM.png

 

You can also navigate to the Settings -> Volumes tab and manually type the location of the folder as shown below:

 

Screenshot 2019-07-02 at 5.01.49 PM.png

 

Next, open the docker-compose.yml file from the OEDK folder and edit the highlighted line with location to your persistent folder details:

 

Screenshot 2019-07-02 at 5.05.10 PM.png

 

Save the file, stop the containers from Kitematic and then re-run the following command:

docker-compose up

Now, you have the 2 containers started and the Device_Kit container is mapped with Persistent Data Volume.

 

Step 5: On-boarding Agent using OEDK

It's time to onboard our first OEDK agent. For this, we will setup a MindConnect Nano Asset in MindSphere:

 

Screenshot 2019-07-02 at 5.12.26 PM.png

 

Give a Random Number when prompted for Unique ID and hit Save.

Screenshot 2019-07-02 at 5.13.24 PM.png

Download the onboarding key:

Screenshot 2019-07-02 at 5.14.41 PM.png

 

The config file will look something like this:

 

{
   "header":{
      "version":"0.1",
      "generationTimeServer":"2019-07-02T09:15:16Z"
   },
   "device":{
      "serialNumber":"RANDOM123",
      "deviceType":"NANO",
      "networkInterfaces":[
         {
            "name":"WebInterface",
            "DHCP":{
               "enabled":true
            },
            "static":{

            }
         },
         {
            "name":"ProductionInterface",
            "DHCP":{
               "enabled":true
            },
            "static":{

            }
         }
      ],
      "deviceIdentifier":"1d2e1490-2dfe-499d-994e-........."
   },
   "agent":{
      "name":"14ab2e9f63ed46778aa44........",
      "proxy":{
         "proxyType":"",
         "host":"",
         "protocol":"HTTP",
         "authenticationType":"BASIC",
         "user":"",
         "password":""
      },
      "agentId":"14ab2e9f63ed46778aa44.........",
      "security":{
         "iat":"eyJraWQiOiJrZXktaWQtMSIsInR5cCI6IkpXVCIsImFs.............",
         "baseUrl":"https://southgate.eu1.mindsphere.io",
         "clientCredentialProfile":[
            "RSA_3072"
         ],
         "tenant":"solarc02",
         "clientId":"14ab2e9f63ed46778aa44........"
      }
   }
}

 

 

Download a MQTT client like MQTTBox

 

Launch MQTTBox and configure the connection between MQTTBox and the local MQTT_Broker container which is running as part of the OEDK agent.

 

Screenshot 2019-07-02 at 5.20.26 PM.png

 

If you have done everyting correctly so far, your MQTTBox should connect to the local MQTT_Broker running inside the docker container as shown below:

 

Screenshot 2019-07-02 at 5.21.10 PM.png

 

We are going to PUBLISH the configuration we downloaded to a specific topic, which will Onboard our OEDK to MindSphere. PUBLISH topic:

 

agentruntime/controlling/command/init

 

Paste the Configuration file (JSON format) in to the Payload section of MQTTBox and click Publish

 

Screenshot 2019-07-02 at 5.48.13 PM.png

The Agent should now be onboarded and Online.

 

Screenshot 2019-07-02 at 5.46.00 PM.png

 

 

I've also created DataSource and DataPoint in this Agent as shown below:

 

 

Screenshot 2019-07-02 at 5.49.47 PM.pngScreenshot 2019-07-02 at 5.49.54 PM.png

When you are done adding the DataSource and DataPoint, Hit the Apply Changes button to push the changes from MindSphere Agent (from Cloud) to the OEDK edge device. 

 

Screenshot 2019-07-02 at 5.58.47 PM.png

 

Remember, we created Persistent Data Volume before? Now go back to that folder and you will see the agent.cfg, data.cfg and headerDevice.cfg files.

 

Screenshot 2019-07-02 at 5.54.32 PM.png

 

The agent.cfg file contains the IAT token details. data.cfg file contains details about the dataSource and dataPoint. headerDevice.cfg contains details about the Agent Interface details. 

 

Our next step is to create a Virtual Device Asset and Map the Agent Data with Device Asset. This is a basic step and I won't go-through in detail how to create Aspects and Assets. You can read through our documentation on how to create Aspects and Assets and how to map them with Agent.

 

Screenshot 2019-07-02 at 5.59.41 PM.png

Now that we have our Agent onboarded, next step is to try sending some TimeSeries data using OEDK. For this, we need to publish our payload (timeSeries data) to a specific MQTT topic from MQTTBox.

 

Topic to PUBLISH:

runtime/inject/data/timeseries/S7/OEDKData_d0077458-44d

Note:

  1. In the above topic, S7 is actually my DataSource. In your case you may choose S7 or OPCUA when you create your datasource. If you use OPCUA as your datasource, then your topic should be have /OPCUA/ instead of /S7/
  2. OEDKData_d0077458-44d is my dataSourceId. This information can be found from the data.cfg file as shown below:

Screenshot 2019-07-02 at 6.09.16 PM.png

 

Topic to PUBLISH:

runtime/inject/data/timeseries/S7/OEDKData_d0077458-44d

 

Payload:

[{
    "timestamp": "2019-06-02T10:11:00.000Z",
    "values": [
      {
        "dataPointId": "5af04a556d6c4",
        "value": 25,
        "qualityCode": 0
      }
    ]
  }]

Screenshot 2019-07-02 at 6.19.20 PM.png

 

 

Hit PUBLISH and you have done everything correctly up till here, you should see the health status of your DataSource turn Green as shown below:

 

Screenshot 2019-07-02 at 6.12.30 PM.png

 

And if you go to your FleetManager, you should see the data point.

Screenshot 2019-07-02 at 6.18.16 PM.png

 

Here is a snapshot from my previous day:

 

Screenshot 2019-07-02 at 6.21.09 PM.png

 

 

If you have read through here, you have made it. Congrats on your OEDK onboarding and ingesting timeseries!  Hope this tutorial was useful. You can further automate the timeseries ingestion using tools like Node-RED running at your edge device where your OEDK agent is running. I will post the steps in this thread at a later stage.

 

 

 

 

 

 

2 REPLIES 2

Re: OEDK - Step by Step Guide

Siemens Experimenter Siemens Experimenter
Siemens Experimenter

Awesome Sriram !

Re: OEDK - Step by Step Guide

Siemens Experimenter Siemens Experimenter
Siemens Experimenter

Great job !

Note that you can use anything that can generate timeseries MQTT messages, i.e. an algorithm, program or other protocolstack runing on your device , one you have configured a S7 or OPCUA  data source through the NanoBox UI.

 

You only need to reuse the data pont ids and the data source id from teh configuration messages.

The development teamis working on aflexible UI plugin that will aloow you to create custom made configuration UIs.