This offer is only addressed to commercial customers including freelancers and entrepreneurs. All prices exclude all taxes.
Subscribe Find out first about new and important news

Getting started with the Bosch IoT Suite for Asset Communication

Welcome to our Bosch IoT Suite for Asset Communication package.

Icons illustrating the Bosch IoT Suite for Asset Communication service package.

With this tutorial (ca. 20 minutes), you will learn how to subscribe for the package, how to make sure you understand its configuration, and how to provision an IoT asset.

After provisioning, your IoT asset can send telemetry data via Bosch IoT Hub to Bosch IoT Things.
To control the IoT asset you can mimic a business application and send messages via Bosch IoT Things and via Bosch IoT Hub back to the asset.

Follow these little steps for a quick-start:

Booking a package

Use the Bosch IoT Suite portal as an entry point.

Screenshot showing how to sign into your Bosch account.
  1. Click My Account and Sign in with your Bosch ID
    • In case you don’t have an account yet, register a new one (Sign up for an account).
    • After logging in you will be re-directed to the Suite.
  2. Click My Subscriptions – New Subscription
    • Select Bosch IoT Suite for Asset Communication
    • Set your Instance name (this must be unique)
    • Subscribe
    • The Status will be “Provisioning” while the service subscription mechanism checks the validity, e.g. if the instance name is unique.
    • In case the Status is still not “Active” after some seconds, click the Refresh button.
  3. Check your Credentials.
    The example shows the structure of the credentials
 {
         "service_instance_id" : "xxx-xxx-xxx-xxx-xxx",
         "provisioning_endpoint" : "https://deviceprovisioning.eu-1.bosch-iot-suite.com/api/1/your-service-instance-ID",
         "hub" : {
            "tenant_id" : "xxx",
            ...more-details...
          },
        "things" : {
           "api_token" : "xxx",
            ...more-details...
         }
      }

Tip: All these credentials are also useful in case your need to address one of these services by their own API.

First configuration steps

Use the Dashboard link from your Service Subscriptions page as an entry point.

Tip: The default configuration already happened automatically.

However, you will need to set a namespace.

The easiest way to do it is via Things UI.

Screenshot showing how to choose a namespace

The namespace needs to conform the reverse domain name notation, e.g. example.your.package.name

Understand your service instance configuration:

Bosch IoT Hub

  • Your instance is automatically pre-configured to be allowed to send messages to our cloud infrastructure.
  • The connection is visible at the Bosch IoT Things Dashboard.
  • The ID of your asset will be registered as device ID at Bosch IoT Hub and as thing ID at Bosch IoT Things.
    For now, keep in mind that it will be the same value.

Bosch IoT Things

  • Your instance is pre-configured to allow all messages from Hub to be routed and processed at Bosch IoT Things.
  • Open the Connections tab to see the entries created automatically during the package booking process.
    • https://things.eu-1.bosch-iot-suite.com/solution/connections
    • The Coordinates section is filled with the Hub credentials received at booking.
    • In section Sources you will find the pre-configured topics:
      telemetry/{{your-hub-service-tenant-ID}}
      and events/{{your-hub-service-tenant-ID}}
    • The authorization subject: integration:{{your-things-service-solution-ID}}:hub
      This entry you will also find in the default policy which we create for you.
    • The option to Enable Bosch IoT Hub/Things ID convention is checked by default and a strong prerequisite for the successful and secure communication between the two service layers. Thus, keep in mind that the device ID at the Hub will be identical with the thing ID at the Things service by default.
    • Setting the namespace is required before you initiate your very first device/thing registration.

Congratulations, you are ready to register your devices for your IoT scenario.

Device provisioning API

General description

With just ONE request at our API, you will be able to register a device (in the context of the Bosch IoT Hub service) and create a digital twin representation of this device (in the context of the Bosch IoT Things service) in thing notation.

Your entry point into our interactive documentation is Bosch IoT Suite – Device Provisioning.

Authorize

You will need to authorize via a JSON Web Token issued by our Suite Auth component.

You can create such a token on your Service Subscriptions page. If your browser still shows the apidocs pages, click the Suite icon to navigate back to the Bosch IoT Suite portal.

  1. Click the icon for My Account.
  2. Click the link for OAuth2 Clients.
  3. Add a New Oauth2 Client.
    • Select the hub and the things entries related to your package subscription.
    • Set a name for the client.
      Upon success, you will be shown your OAuth2 Client Details.
    • Click Use Client – this will generate a token (JWT) which is valid for 5 minutes.
    • Copy the Bearer token to your clipboard.
      Tip: Make sure not to copy empty spaces with it, as this will lead to errors.
  4. Return to you Bosch IoT Suite – APIs browser window.
  5. Paste your Bearer token into the Value field.
  6. Confirm with Authorize.
  7. Close the dialog

Example – Simple device registration

Request

Screenshot showing the steps to provision a device.

Bosch IoT Suite – APIs

  • Use the provisioning resource
  • POST /{service-instance-id}/devices
  • Click Try it out to get all entry fields editable
  • Set the service-instance-id to the value you see at the Service Subscriptions > Credentials section.
    (See Booking a package)
  • Edit the Request body
    In our example we set following request body
 {
       "id": "your.namespace:my-device-id-4711",
       "hub": {
         "device": {
           "enabled": true
         },
         "credentials": {
           "type": "hashed-password",
           "secrets": [
             {
               "password": "your-secret"
             }
           ]
         }
       },
       "things": {
         "thing": {
           "attributes": {
             "manufacturer": "My awesome company"
           }
         }
       }
     }

Click Execute to submit the request.

Caption:

  • The “id” value needs to be defined by you.
    In case you have not defined a namespace yet, you will need to do it now:
    Service Subscriptions page > Your instance > Dashboard > Namespace.
    In case “my-device-id-4711” already exists just alter the name, as it needs to be unique.
  • The “hub” entries
    In our example the device-id will be the same as the id at the top of the request body, and "enabled": true is the default behavior anyway. Thus, we can leave this empty.
    For your credentials you can use all types as described in Bosch IoT Hub documentation > Manage Credentials and Bosch IoT Hub API docs > Device Registry > Credentials > Model.
  • The “thing” entry could remain empty, as an empty “POST” thing is supported and would generate an empty thing and its default policy.

Response

Upon success, you have created following entities:

  • device in the context of Bosch IoT Hub, associated with credentials, which the Hub will require whenever a device identifies as the registered one. Find details on the device data model at https://docs.bosch-iot-hub.com/general-concepts/devicedatamodel.html
  • An empty digital twin in thing notation associated with a policy. The thing entity can be refined with all the static attributes (which support you on organizational tasks) as well as with all dynamic telemetry data sent by your sensors. Such values are expected to be structured as features an their properties according to our model. Find details on the things data model at Things and Features.
  • A default policy, which can be refined as fine grained as your usage scenario requires. In case your custom policy needs to look different from the very beginning, you can edit the policy first, and later re-use it multiple times on provisioning devices of the same kind. However, keep in mind that such a policy will only be a copy (not a clone) and will thus not evolve in case you change one of pattern or copies. Find details on the access control policies for things at Policies.

Well done, stay tuned for more tutorials on this topic.

Cookie Information

This website uses cookies for reasons of functionality, comfort, and statistics. If you consent to this use of cookies, please click ”Ok“. If you like to disable the cookies for webtracking, please click here. For more information see our Privacy Policy