Bosch IoT Suite

Register your devices

This section details the steps on how to register your devices with the Bosch IoT Suite.


Table of contents:


How to execute

Define a device identifier

According to your demands, choose an appropriate identifier. This identifier must be unique for your application.

Combine this identifier with the namespace, which you have configured in your service instance as a prefix.

Then you will have the device ID your.namespace:your-device-identifier.

This will also act as thing ID for the thing that represents the digital twin of your device.

Define a device credential

Bosch IoT Hub relies on protocol adapters to establish a device’s identity before it is allowed to publish telemetry data or send events.
Conceptually, Bosch IoT Hub distinguishes between two identities

  • Identity associated with the authentication credentials (termed the authentication identity or authId), and

  • Identity to act as the device identity or deviceId.
    (This one was described above as required to follow the pattern your.namespace:your-device-identifier. )

Choose the auth ID as it is convenient for your device driver, and set a secure device credential.

A device may be authenticated using different types of secrets, e.g. a hashed password or certificates, depending on the capabilities of the device and/or protocol adapter.

The Bosch IoT Hub - HTTP Protocol Adapter supports the following credential types:

  • Password credentials

  • Device certificates

The Bosch IoT Hub - MQTT Protocol Adapter supports the following credential types:

  • Password credentials

  • Device certificates


You should choose a secure way to generate it, and use a length according to your security demands.


Provision the device using the Bosch IoT Suite - Device Provisioning API

Prepare a JSON request document

The example contains all required information to provision a device.
However, you can enlarge it to your needs, as long as it is valid JSON, and compatible to our thing notation.

{
"id": "<your.namespace>:<your-device-identifier>",
"hub": { "credentials": { "type": "hashed-password", "secrets": [ { "password": "<your-password-in-plaintext>" } ] } },
"things": { "thing": { } }
}


Use your Suite OAuth2 client and issue an OAuth2 token

At this point we assume you have already defined the Suite Auth client with the scope you need.
In case you missed to do this step, find guidance at Device provisioning via API.

Go to https://accounts.bosch-iot-suite.com/oauth2-clients/

  • Find the list of your clients and click Use for the one which should create new token.

    images/confluence/download/attachments/894247796/suite-oauth.png

  • Copy it to your clipboard as you will need it in the next step to invoke the Device Provisioning API.

    Make sure not to start or end with an empty space, as this will lead to errors at the authorization attempt.

  • Be aware that the token will expire after 60 minutes.
    In case it expires before your are done with your provisioning request, you need to get a new token.

Invoke the Device Provisioning API

From your credentials section at https://accounts.bosch-iot-suite.com/subscriptions, and copy <your-service-instance-id>.

Use the POST operation to send the prepared JSON document on
https://deviceprovisioning.eu-1.bosch-iot-suite.com/api/1/<your-service-instance-id>/devices

Provide your prepared OAuth token as standard HTTP Authorization prefixed with "Bearer ".

Configure your device with your credential and connectivity parameters

At this point we assume that your are aware of the meaning of your device's authId and the associated device credential, and why it is crucial to not spoil them.

These need to be known at the point in time, when your device is up and running and tries to establish the connection to our cloud services.

Use the implicit device registration

When you send messages from a new device to the Bosch IoT Hub via a gateway, a new device will automatically be created.
Also the default Bosch IoT Things ↔ Bosch IoT Hub connection enables for an automatic thing to be created in the Bosch IoT Things service.


Please take into account that the protocol adapters of the Bosch IoT Hub have a caching mechanism in place for devices and their credentials. That means if you make changes in the device's or credentials' properties, it takes some time until the protocol adapters apply the changes. Currently the cache setting is configured to 10 minutes.