Visualization of the digital twin - Developer Bosch IoT Suite

What you will learn

In this tutorial, you will learn how to visualize the data output of a connected device. This can also include the device (ESP8266-based prototype) you might have previously connected to the Bosch IoT Suite in the tutorial “Connecting a simple device to the Bosch IoT Suite”.

This tutorial is based on “Generate a Node.js Dashboard that reads device data from Bosch IoT Suite and visualizes it in Vorto UI Widgets” tutorial from Vorto.

In case you want to create own widgets, check out the “Extending the Dashboard with custom widgets – Tutorial” from Vorto.

Duration of the tutorial

This tutorial will take you approximately 30 min to 45 min after installing the necessary software.

What you need to install and prepare

The Vorto Dashboard offers pre-configured widgets to visualize data of digital twins managed by Bosch IoT Things. The application needs access to your Bosch IoT Things service instance. It will analyze the information model of each Thing in the service instance.

In case the Thing has at least one compatible feature definition (function block model), the dashboard will map the values to the assigned widget.

The definition refers to a defined function block model. You can find further information on the model here.

Install

Download and install node.js on your computer. Also the package manager for node.js NPM is required and will be installed along with node.js.

Prepare

The Vorto Dashboard requires a compatible device or at least its digital twin within Bosch IoT Things. Go straight to the chapter “Provide access to your digital twin in the Vorto Dashboard” if you already worked through the tutorial “Connecting a simple device to the Bosch IoT Suite”. If not, please start this tutorial from the beginning.

Tasks to complete

Book and configure the Bosch IoT Suite for Asset Communication package

Provide access to your digital twin in the Vorto Dashboard

Install the Vorto Dashboard

Run the Vorto Dashboard

Troubleshooting

Icon illustrating the registration of a device.

Book and configure the Bosch IoT Suite for Asset Communication package

In this section, you will:

Create a Bosch IoT Suite account
Subscribe to the Bosch IoT Suite Asset Communications package
Configure a namespace for your things (digital twins)
Create and configure a technical OAuth2.0 client
Generate a test token to access the APIs of the Bosch IoT Suite

Create a Bosch IoT Suite account

Navigate to the Bosch IoT Suite.
Create a Bosch IoT Suite account.
Login with your credentials.

Single sign-on with your Bosch user ID

In the process, you will create or reuse an existing Bosch ID. This user ID enables a single-sign-on (SSO) functionality that can be used for multiple Bosch applications.

Bosch IoT Suite documentation

For more information, have a look at the Bosch IoT Suite documentation.

Subscribe to the Bosch IoT Suite for Asset Communication package

Subscribe to the Bosch IoT Suite for Asset Communication package by following these steps:

Navigate to Service Subscriptions.
Click New Subscription.
Follow the subscription wizard.

Content of the package

Your service subscription to the Asset Communication package includes:

A Bosch IoT Hub service instance
A Bosch IoT Things service instance
The unified Device Provisioning API for simplified device registration
Both are already fully preconfigured and connected to communicate with each other
A limited license for the Bosch IoT Suite Gateway Software, which is not used in this tutorial

Configure a namespace for your devices (digital twins)

Configure your unique Bosch IoT Things namespace by following these steps:

Navigate to Bosch IoT Things by clicking Go to Dashboard.
Click Solution/Namespace.
Insert a new globally unique namespace using java package notation, e.g. your.things.namespace.
Click Submit namespace.

Namespace

The namespace is used as a unique prefix for all your Thing IDs to make the thing IDs globally unique.

Bosch IoT Things documentation

For more information, have a look at the Bosch IoT Things documentation.

Create and configure a technical OAuth2.0 Client

Create an OAuth2 Client with full access to Bosch IoT Things and Bosch IoT Hub by following the next steps:

Navigate to the Bosch IoT Suite.
Click the user account icon , then click Sign In in the overlay.
Once you are authenticated, click the user account icon .
Click OAuth2 Clients in the overlay.
In the section New OAuth2 Client insert a new name, e.g. Asset Communication Client.
Select the Hub and the Things full access scopes.
Click Create.

Bosch IoT Suite: select both, Hub and Things.

OAuth2.0 Client

You can use the OAuth2 Client in your application to authenticate it with many of the Bosch IoT Suite APIs as a technical client.

Generate a test token

Generate and copy a test token by following the next steps:

Navigate to your Bosch IoT Suite.
Click the user account icon .
Click OAuth2 Clients in the overlay.
Click Use next to your active OAuth2 Client.
Copy the test token by clicking Copy to clipboard.

Screenshot of the Bosch IoT Suite OAuth2 client.

Bosch IoT Things: generating and copying a test token.

Test token

In this tutorial, you will mainly use a so-called test token of this client to authenticate against all HTTP REST APIs. Note that the test token is only valid for 60 minutes each time you generate one.

Register your device with the Bosch IoT Suite

Back to the tasks ▲

Register your device with the Bosch IoT Suite for Asset Communication package at the Device Provisioning API by following these steps:

Click Authorize. A dialog opens. Paste the test token as value of the bearerAuth (http, Bearer) section. Proceed with Authorize, then Close the dialog.
Unfold the provisioning section and click the POST method “/{service-instance-id}/devices”.
Click Try it out.
Add your Service Instance ID (you will find all important information as described in the “Service Instance ID” infobox).
Click Edit below the Edit Value field.

Copy the following code and replace everything in the field Edit Value:

{ 
   "id":"<com.bosch.example:my-device-id-4711>",
   "hub":{ 
      "device":{ 
         "enabled":true
      },
      "credentials":{ 
         "type":"hashed-password",
         "secrets":[ 
            { 
               "password":"<yourPassword>"
            }
         ]
      }
   },
   "things":{ 
      "thing":{ 
         "attributes":{ 
            "manufacturer":"<Robert Bosch GmbH>"
         },
         "features":{ 
            "illuminance":{ 
               "definition":[ 
                  "org.eclipse.vorto:Illuminance:1.0.0"
               ],
               "properties":{ 
                  "status":{ 
                     "value":{ 
                        "currentMeasured":555,
                        "minMeasured":0,
                        "maxMeasured":999
                     }
                  }
               }
            }
         }
      }
   }
}

Define your credentials (check the “Device credentials” infobox) by editing everything in <pointy brackets> (make sure to delete the <pointy brackets>).
Click Execute to run your API call and register your device.

You should get a response with the code HTTP 201 created and a payload reflecting the device you just registered.

Service Instance ID

You can find all necessary information on your subscriptions in the Credentials section.

Navigate to Service Subscriptions.
Click Access Credentials in the specific row of the subscription you need the Instance ID for.
For the Service Instance ID scroll down to the Access Credentials section.

Device credentials

"id":"<your.Things.namespace:your-generic-device-name>"

This is the ID put together by the namespace you already created here and the name of your device which you define in the recent step for the first time.

"password":"<your-device-password>"

Define your individual password here (we recommend six characters).

"manufacturer":"<Your awesome company>"

Insert the name of your company here.

Do not forget to delete the pointy brackets and remember your device password! Download the response in JSON notation. Thus, you can look up the authId and the password later.

HTTP 401 - Errorcode

If you get an HTTP 401 response, your test token has probably reached the end of its validity time. Generate a new token by opening your OAuth2.0 client list in a new tab, and clicking Use in the specific line where your client is listed.

Provide access to your digital twin in the Vorto Dashboard

Register your Vorto Dashboard device with the Bosch IoT Suite for Asset Communication package at the Device Provisioning API by following these steps:

Create a new folder on your computer.
Create a new text file.
Save the text file as config.json and place it in the new folder.
Open the file with a text editor (e.g. Notepad ++, TextEdit).

Copy the following template and paste it into the file:

{
"client_id": "<xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx>",
"client_secret": "<xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx>",
"scope": "<service:iot-things-eu-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_things/full-access>",
"intervalMS": 10000
}

Fill in the credentials of the OAuth2 Client (check the info box OAuth2 Client credentials to see where to find them) you used to authorize within the provisioning process. Replace everything in pointy brackets (delete the pointy brackets afterwards).
Save the file.

You should now have an individualized config.json file with your credentials taken from the OAuth2 Client.

OAuth2 Client credentials

Here you will find the credentials of the OAuth2 Client:

Navigate to your Bosch IoT Suite.
Click the user account icon in the top right, then click OAuth2 Clients in the overlay.
Click Details next to your active OAuth2 Client.

Install the Vorto Dashboard

Install the Vorto Dashboard by following these steps:

Open the terminal.
Type npm install -g vorto-dashboard.
Press the Enter key to confirm.

NPM is installing the Vorto Dashboard.

Troubleshooting

In case of any error messages, check the troubleshooting section for help.

Run the Vorto Dashboard

Run the Vorto Dashboard by following these steps:

Open the terminal.
Navigate into the folder to which you saved the config.json file.
Type vorto-dashboard ./config.json and press Enter. The Vorto Dashboard is started.
Open your web browser and type localhost:8080 into the address bar. The Vorto Dashboard overview screen opens.
Select your added Thing in order to open it.

As a result you should see two boxes:

One box containing all information about your connected Thing.
One box named illuminance containing a gauge widget.

Icon illustrating troubleshooting.

Troubleshooting

In case of irregularities during the process, check this section for help.

Your computer is located behind a (corporate) proxy

In case you cannot run the Vorto Dashboard due to reasons caused by your proxy preferences, you will have to insert your proxy credentials in the node.js as well. Add the following lines with your credentials in the terminal:

npm config set proxy http://<username>:<password>@<proxy-server-url>:<port>

npm config set https-proxy http://<username>:<password>@<proxy-server-url>:<port>

Your Vorto Dashboard is not working properly

When your Vorto Dashboard is not working properly (e.g. the gauge widget is not visible or information is missing) try to use another web browser like Google Chrome.