Siemens MindSphere is a cutting edge industrial Platform as a Service (PaaS) product that takes a lot of the work out of building and deploying IIOT applications. Siemens bills MindSphere as "the cloud-based, open IoT operating system from Siemens that connects your products, plants, systems, and machines, enabling you to harness the wealth of data generated by the Internet of Things (IoT) with advanced analytics." Vertech recently became a MindSphere Solution Partner, and here are a few beginners tips our developers learned as they got started using the platform.
Creating Assets to use in MindSphere
Assets are the backbone of MindSphere data and need to be created to actually save anything in the system. Assets can be created from the Asset Manager from your personal MindSphere portal. To do so we will need to do a few things. If MindSphere has all the built in Assets you need, you can skip this next section, but I’m guessing it won’t.
1. Start out by creating a new Aspect. Replace the Id with your <tenantPrefix.nameYouWant>.
2. Now that the Aspect is created, we can assign that Aspect to an Asset Type. I placed mine under the BasicAgent but it could go anywhere. Again, replace the Id with your <tenantPrefix.NameYouWant>. Assign the Aspect type to the Asset type that was just created.
3. Now we can create an actual Asset. Select your Asset type you just created.
Fill out the Asset information. You can now store and modify the variables in the the Asset via the API.
Testing the API calls without launching an application
One of the first things we realized when we started developing was that MindSphere requires you to launch an application to test the API’s. We needed a way to test APIs without launching. To do this, you must file a ticket with Siemens Technical Support to get access to your secret key. The request format for the ticket is (per the MindSphere developer site):
Subject: Request for new Service Credentials for self-hosted application
Dear MindSphere Support,
Please create new Service Credentials for the tenant with the following parameters:
Tenant name: <your MindSphere tenant>
Account type: <Developer (Dev) or Operator (Ops) depending on your account type>
Service Credentials ID: <preferred name for the Service Credentials set>
To develop/operate I purchased the following products:
(specify Soldto number for relevant products)
MindAccess Developer Plan: <enter Soldto>
MindAccess Operator Plan: <enter Soldto>
Outbound Traffic Upgrade: <enter Soldto>
Further Services: <enter Soldto>
Once you get a response with your secret key, you can utilize a tool like Postman to test out the native MindSphere API’s along with any API’s you create in your own application. To do this you will need to first open Postman and create a request that looks similar to the one below. The URL that you can use is <your tenant name>.piam.eu1.MindSphere.io. You will also want to add the two headers as shown below. (Adding your own secret key to the Authorization header)
One last thing you will need to add is one line of code to the body of the request, and that is grant_type=client_credentials. It will need to be added in as a raw format.
If the call was successful, you will get a result like this one. The key piece of information from this result is the access token value which will be used in your other requests for data to MindSphere. This access token will essentially provide you with unlimited access to MindSphere, so be sure to keep that secret key a secret.
Now that you have the access token, you can make further requests to the API by adding the two headers together as shown in the image below. The Authorization header will be filled with the word Bearer and the access token and the Host header will be gateway.io.Mindsphere.io.
Initially, when we wanted to query our assets and see which variables and aspects were available, the results would come back as empty sets or as nulls. This resulted in copious amounts of desk head butting.
This is because MindSphere utilizes HAL + JSON, which is a way to make your API’s explorable, but also has the result of making each call smaller because it isn’t sending a large set of data with each call. The thought is that you can explore the result set to find the URL for the next call you may need to make. To see this for yourself, first open Postman and create a GET request that hits this endpoint https://gateway.eu1.MindSphere.io/api/assetmanagement/v3/assets. You could also add a filter to the endpoint to narrow down the results.
Once you have gotten the result look for the Asset that you are interested in and look for a part of that result that looks like the image below.
You can now use these URL’s to get further information on the Asset that you are interested in.
Actually saving the data you want.
All data that needs to be saved in MindSphere is saved inside of the IoT Time Series database and is attached to some sort of Asset instance. Now that you have laid the foundation in the platform, this section should be easier to navigate. First, open Postman again, and use the instructions from the "Where are my variables" section above to retrieve all of your Assets. The part that you are interested in here is the assetId. This Id will be used to both insert and retrieve data from the TimeSeries Database.
If you do not remember the name of the Aspect inside of your Asset or of the names of the variables inside of that Aspect, you will need to either look them up in the portal or access them via API calls. To get them via API calls make a request to the https://gateway.eu1.MindSphere.io/api/assetmanagement/v3/assets endpoint again and find the _links section like you did in the previous section. Look for the variables href and the aspects href, depending on which one(s) you need. The result set from these two links will give you all the information that you will need to actually save data to the TimeSeries Database.
The PUT request you need to make will contain the assetId, the Aspect name, and the variable name. Starting with the URL https://gateway.eu1.MindSphere.io/api/iottimeseries/v3/timeseries/<assetId>/<aspectName> , replace the <assetId> and the <aspectName> with the values you just retrieved above. You will also need to add to a JSON object in the body of this request with the variable and data you want to store. The object will consist of two items: a _time variable to which you must assign a time stamp and a variable that must be assigned a value.
Viewing the saved data.
Now that we have saved the data into an Assets variable, we now need to retrieve that data to be able to do something useful with it. To do this you will need the assetId and the name of the variable. The URL that you will need to hit to get the data is, https://gateway.eu1.mindsphere.io/api/iottimeseries/v3/timeseries/<AssetId>/<VariableName>.
Inside of Postman it will look something like this.
You can now set up Assets and store and retrieve data to them. From here, it's up to you to decide what to do with your data. MindSphere provides the structure to connect to manufacturing data on the plant floor via edge devices like the Siemens MindConnect IoT 2040 and other devices. The platform and architecture enable you to spend your development time doing creative things with your data rather than building the infrastructure to collect and store it.
MindSphere allows unparalleled freedom to visualize and analyze your data in an open HTML based environment while utilizing someone else’s platform that you do not need to maintain. Hopefully these few tips will save you some time as you get started on your own MindSphere development journey.
Vertech is a Siemens MindSphere Solution Partner. Our team of programmers can develop MindSphere applications for your organization and help you begin to take advantage of all the IIOT has to offer.