How to create MindSphere Artifacts from JSON Schema definitions

Did you know that you can create all MindSphere modelling artifacts (Variables, Aspect- and Asset Types as well as Assets) straight from a JSON Schema? This means that if you already have JSON data gathered from your industrial assets (e.g. because they are already available on your production data bus) you can leverage your existing JSON schemas (or extract them from JSON data) to quickly create all needed MindSphere artifacts.

Let’s assume that you are modelling a digital twin of a robot with several servomotors, like this one in the picture (This is a Joy-IT Robo-Set toy robot equipped with Raspberry PI which I am using for this example)

Image for post
Image for post
MindSphere Fleet-Manager 3D Visualization Plugin

The robot is capable of sending the power applied by each servo-motor (servo0-servo5), the rotation angle of the joints(servoangle0-servoangle5) and the sensor data with temperature on the motor1 and the indicators if the motor is blocked or vibrating over MQTT:

Servomotor data for the Robot
Sensor data for the robot

First step is to extract the JSON Schema from the existing data. (In a real manufacturing project, the chances are high that the equipment manufacturer would provide these schemas. We can use e.g. to extract the corresponding schemas

Sensor Data JSON Schema:

Sensor Data JSON Schema

The schema for the servodata is available on GitHub.

We can use this information to create all necessary MindSphere modelling artefacts and start sending data to MindSphere.

Creating MindSphere Assets from JSON Schema

Step 0: Setup the MindSphere CLI

npm install @mindconnect/mindconnect-nodejs -g

Install and setup the CLI from npm as specified here or download binaries from GitHub and put them in the path.

Step 1: Convert the JSON Schema to MindSphere Aspect Definition

The conversion can be done using the following CLI commands.

mc aspects --mode convert --schema schemas/servodata.schema.json --aspect RobotServoData
mc aspects --mode convert --schema schemas/sensordata.schema.json --aspect RobotSensorData

This will create two files in your local directory which will contain aspect definition in MindSphere data format.

Image for post
Image for post
using CLI to convert JSON Schema to MindSphere Aspect format

The aspect definition is very similar to the original schema but it uses MindSphere data types, adds quality codes etc. It also flattens the schemas as MindSphere allows only one level of depth in the asset definitions.

MindSphere RobotSensorData aspect

Step 2 Create Aspects in MindSphere

Now that we have aspect definitions in MindSphere format it is time to create the aspects in MindSphere (note that we ignored the units for the variables, if you want to add them, edit the aspect.mdsp.json file before running the following commands)

mc aspects --mode create --file RobotSensorData.aspect.mdsp.json
mc aspects --mode create --file RobotServoData.aspect.mdsp.json

This will create the corresponding aspects in MindSphere. We can observe them in the Asset Manager.

Image for post
Image for post
The Aspect in MindSphere containing the servomotor variables

Step 3 Create Asset-Type in MindSphere

The next step is to create an asset type for our robot

mc asset-types --mode template --assettype JoyItRobot

This creates a template file JoyItRobot.assettype.mdsp.json which we will modify to use our two aspect definitions. (note: my tenant is called castidev; modify the definition to use your tenant name)

MindSphere Asset Type Template

Creating the asset type in MindSphere is only one command away:

mc asset-types --mode create --file JoyItRobot.assettype.mdsp.json
Image for post
Image for post
Asset Type JoyItRobot in MindSphere

We are now done with modelling tasks in MindSphere. the only thing what is left is to create an instance of our asset type and send some data to MindSphere.

Step 4 Creating an Asset Instance

We can use the CLI to create an instance of the JoyItRobot type which will represent our demo robot. (All of these tasks can be done in MindSphere-UI, I am just using the CLI for consistency)

mc assets --mode create --typeid castidev.JoyItRobot --assetname JoyItRobot_1 
Image for post
Image for post
JoyItRobot_1 Asset Instance

Now that we have our asset we can use e.g. Node-RED or code our own project to send data from our MQTT topics to MindSphere. Take a look at the live example here

Image for post
Image for post
Node-RED Flow for the Robot

The robot data in MindSphere Fleet Manager:

Image for post
Image for post
Data in Fleet Manager

Bonus: generating data point ids from raw data

If you take a closer look at the flow you will see that it uses a function which generates MindSphere DataPointIds from raw data on MQTT Topics. This function can be generated with help of CLI

mc configure-agent --mode func --agentid 6178e1c165944c3ea6d8278282f7886a

The code for this article is available on github, including a demo application which can be used as a starting point for your own MindSphere integration.

If you need a full list of datapoint mappings as well as the mapping function you can create both with

mc configure-agent --mode template --typeid castidev.JoyItRobot \
--language python # other supported languages are js or json

If you don’t have a MindSphere account yet, you can register here for your own start for free account.

Written by

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store