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)
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:
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. https://jsonschema.net/ to extract the corresponding schemas
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 -gInstall 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 RobotSensorDataThis will create two files in your local directory which will contain aspect definition in MindSphere data 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.
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.jsonThis will create the corresponding aspects in MindSphere. We can observe them in the Asset Manager.
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 JoyItRobotThis 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)
Creating the asset type in MindSphere is only one command away:
mc asset-types --mode create --file JoyItRobot.assettype.mdsp.json
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 
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 https://playground.mindconnect.rocks/#flow/996ec513.e1f4d8
The robot data in MindSphere 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 6178e1c165944c3ea6d8278282f7886aThe 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 jsonIf you don’t have a MindSphere account yet, you can register here for your own start for free account.