Booking Bosch IoT Device Management

Bosch IoT Device Management is a service package which supports the scalable and secure ingestion of large volumes of sensor and asset data, and also the remote control of your assets. The service package serves as the instance to create the digital twin of the engine.

Proceed as follows

1. Open your Bosch IoT Suite account.

2. Click the New Subscription button to add the Bosch IoT Suite for Asset Communication service package.

3. Select Bosch IoT Device Management.

4. Activate the Free Plan - Frankfurt (EU-1) - AWS checkbox.

5. In the Instance Name field, enter a name for the instance.

6. Click the Subscribe button.
   → The details of the subscription are displayed.

7. Click the Subscribe button to book the free plan.
   → The subscription is being provisioned. It may take a while until your booking is active. Optionally, refresh the page.

Connecting Bosch IoT Device Management with Bosch IoT Insights

As a next step, a connection between Bosch IoT Device Management and your Bosch IoT Insights project has to be established.

Proceed as follows

1. In the Service Subscriptions overview page, click Go to Developer Console.
   → The Suite UI is displayed.

2. Open the Connections entry in the left navigation.
   In case it is not there, use the search, and click the star icon to pin it to your navigation bar.
   → The Connections page is displayed. Your instance is pre-configured with two connections, to allow all messages to be routed and processed at various service layers.

3. Click the Add button to create a connection to Insights.
   → The Create a new connection dialog is displayed.
   

   

4. Use the drop down and choose HTTP: Template for Bosch IoT Insights.

5. In the Connection name field, enter a name for the connection.

6. Click the Continue button.

7. In the Bosch IoT Insights project ID from binding credentials field, enter the ID of your project.

   You can find the Project ID in the binding credentials of your subscription. The Project ID is also visible in the URL of your project.

8. In the Bosch IoT Insights username field, enter the username of the API user that you created in the Creating an API user in Bosch IoT Insights section.

9. In the Bosch IoT Insights password field, enter the password of the API user that you created in the Creating an API user in Bosch IoT Insights section.

10. Click the Continue button.

11. In the Authorization subject field, enter insights.

    The authorization subject is required to authorize the data transfer from the Device Management instance to Bosch IoT Insights.
    After the connection has been set up, it will be visible in section Targets.

    This subject needs to be set in the policy later on.

12. Click the Continue button.
    → The connection details are displayed.

13. Click the Test connection button to ensure that the connection is working fine.

14. Click the Create button to create the connection.

Creating a namespace

The next step is to create a unique namespace in Bosch IoT Device Management. A namespace is used to separate things from different solution spaces from each other.

Proceed as follows

1. Starting from your Service Subscriptions page click Go to Developer Console item of your Device Management booking.

2. The Developer Console shows up.
   

3. Open the Namespace entry in the left navigation.
   

4. Click the plus icon to add a namespace.

5. Enter a namespace name in the field.
   The namespace can be anything, as long as it conforms to the reverse domain name notation, e.g. example.dm, as in our case.
   However, it needs to be unique, i.e. you cannot register the exact same namespace for multiple instances.

6. The search index fields are set to the defaults which are most convenient for Bosch IoT Device Management to work properly.

   1. More search index fields can be added later if needed.

   2. The required fields are the minimum necessary and cannot be deactivated.

7. Confirm with Save.
   
   

Adjusting the provided collection in the API development tool

To send data to your Bosch IoT Insights project, we have provided a collection that consists of GET and PUT requests with which the Thing will be created, the Thing policy updated, and the data of the Thing modified. We also provided two requests that you can use to verify the creation of the Thing and the update of the policy.

In this section, the provided variables located in the URL and in the authorization tab need to be set. To set the values for the authorization variables, an OAuth2 client has to be created in your Bosch IoT Suite account, refer to the Creating an OAuth2 client section.

Proceed as follows

1. Download the provided collection.

2. Open Postman.

3. Click the Import button and select the downloaded collection.

4. Click the View more actions icon of the collection and select Edit.
   → The EDIT COLLECTION dialog is displayed.

5. Open the Variables tab.
   → All variables provided in the collection are listed. The value for the things_endpoint has already been provided.

   The Things Endpoint can be found in the Access Credentials of your subscription under Bosch IoT Things.

6. In the CURRENT VALUE field of the namespace variable, paste the namespace you just created.

7. Open the Authorization tab.

   Some of the following fields may already be pre-filled and can be skipped.

8. In the TYPE drop-down list, select OAuth 2.0.

9. In the Token Name field of the Configure New Token section, enter a name for the token.

10. In the Grant Type drop-down list, select Client Credentials.

11. In the Access Token URL, enter the access token URL.

    The Access Token URL can be found in the list of your OAuth2 Clients. Click the Use button. Scroll down to the Java Example with Spring Security OAuth2 Boot section and copy the Access Token URi from the second box.

12. Open the Variables tab to enter values for the Client ID, Client Secret, and the Scope.

13. In the CURRENT VALUE field of the oauth2_clientId variable, paste the Client ID of the OAuth2 client you just created.

14. In the CURRENT VALUE field of the oauth2_clientSecret variable, paste the Client Secret of the OAuth2 client you just created.

15. In the CURRENT VALUE field of the oauth2_scope variable, paste the scope of the OAuth2 client you just created.

16. Open the Authorization tab again.

17. In the Client Authentication drop-down list, select Send client credentials in body.

18. Click the Get New Access Token button to receive a new access token.

19. Click the Use Token button.

20. Click the Update button.
    → All changes made in the Authorization tab and the Variables tab have been saved.

Creating the digital twin of the engine

After the settings have been adjusted, the digital twin of the engine can be created in Postman.

Proceed as follows

1. Open the Create an engine in IoT Things PUT request.

2. Click the Send button.
   → The 201 Created HTTP status code has been returned and the digital twin created. The response also contains the policy which is always created for a Thing. The policy manages the access to things.

Adjusting the Thing policy

As a next step, the policy has to be adjusted to allow Bosch IoT Insights to read values from the Thing. Therefore, the authorization subject is required that was created when establishing the connection between Bosch IoT Device Management and Bosch IoT Insights.

Proceed as follows

1. Open the Update the thing policy PUT request.

   The INSIGHTS entry at the end of the URL means that the request will create a new entry labeled Insights with the content prepared in the body.

2. Replace the authorization_subject parameter with the authorization subject.

   You can find the authorization subject in the Connections UI, refer to the note below step 11 in the Connecting Bosch IoT Device Management with Bosch IoT Insights section.

3. Click the Send button.
   → The 201 Created HTTP status code has been returned and the policy adjusted.

Sending device data to Bosch IoT Insights

Now that the Thing has been created and the policy adjusted, data can be sent to your Bosch IoT Insights project. The request body shows the front sensor and the rear sensor of the Thing as well as the values that shall be sent. In the Pre-Request Script, values have been provided which will be sent randomly to your project.

Proceed as follows

1. Open the Modify the temperatures PUT request.

2. Click the Send button.
   → The 204 Created HTTP status code has been returned and values sent to the Bosch IoT Insights project.

Checking whether device data has been received and processed

The next step is to check whether your Bosch IoT Insights project has received and processed the sent temperature values.

Proceed as follows

1. Open your Bosch IoT Insights project.

2. Open the Processing > Input History tab to check whether the data has been received.

3. Check the entries for the latest input.
   

4. Open the Explore > Data Browser tab to check whether the data has been processed.

5. Click through the payload and you will find the temperature values that were sent for the front sensor and rear sensor.
   

   If the device data has not been processed, a pipeline might not be running. Open the Processing > Pipelines tab and, if necessary, start a pipeline, refer to the Starting and stopping a pipeline chapter.

Creating a query template

To create a widget visualizing the received temperature values, a query template has to be created that serves as the data source in the widget configuration.

Proceed as follows

1. Open the Explore > Data Explorer tab.

2. Click the Add Template button to create a new query template.
   

   

3. In the Name field, enter a name for the query template.

4. Click the Access rights button to define the access rights for the desired user roles. Refer to the Managing query template access rights chapter.

5. In the Template Definition pane, enter the following query.

   [

   {

   "$match": {

   "metaData.thingId" : "${engine_id}"

   }

   },

   { "$sort" : { "_id" : -1 }

   },

   { "$limit" : 1 }

   ]

6. In the Parameters pane, click the Add parameter button.
   → The Edit parameter dialog is displayed.

7. In the Technical Name field, enter engine_id.

8. In the engine_id field below the Define default value checkbox, enter the Thing ID which consist of the namespace and the Thing's name.

9. Click the Save button.

10. Click the Save template button.
    → The template has been created.

11. Click the Run button to check whether the template is working correctly.
    

    

Creating the Value widget with the received device data

The next step is to configure the Value widget to visualize the received temperature values.

Proceed as follows

1. Open the Views tab.

2. Open the desired dashboard you want to add the widget to.

3. Click the Add Widget button.

4. Select the Value widget.
   → The widget configuration page is displayed.
   

   

5. Open the Dashboard Settings pane to set how the widget is displayed in the dashboard.

   1. In the Size drop-down list, decide how much space the widget should take in the form of columns.

   2. In the Title field, enter a title for the widget.

6. Open the General Settings pane to configure some general aspects for the widget.

   1. In the Widget Refresh Interval in Seconds field, enter a value in seconds after which the widget should be refreshed.

7. Open the Data Sources pane to configure the data source for the widget.

   1. Click the + Add Source button to add a data source.

   2. Select Query Template.

   3. In the Query Template drop-down list, select the query template you just created.

   4. Click the Save Data Source button.

8. Open the Value View Settings pane to configure the value.

   1. Click the Add Value button to open the value configuration.

   2. In the Path drop-down list, select the 0.payload.value.front-sensor.properties.temperature parameter path.

      The number in the beginning of the parameter path refers to the document number in the data source. The 0 in the example above means that the first document of the data source is considered.

   3. In the Label field, change the name of the value.

   4. Click the Add icon to add the value for the rear sensor.

   5. In the Path drop-down list, select the 0.payload.value.rear-sensor.properties.temperature parameter path.

      The number in the beginning of the parameter path refers to the document number in the data source. The 0 in the example above means that the first document of the data source is considered.

   6. In the Label field, change the name of the value.

   7. Optionally, deactivate the Show Only Value checkbox to set ranges for the value to be displayed in a traffic light system as described in the Optional: Adding color indicators section.

9. Click the Add button.
   → The Value widget is added to the dashboard and shows the values that were sent the first time.

Sending device data again

As a last step, watch how the temperature values in the widget change when you send them again using the API development tool.

Proceed as follows

1. Click the Send button in the Modify the temperatures PUT request.

2. Open the dashboard in which the Value widget is located.
   → The temperature values are automatically updated. You can also click the Refresh icon .