Device provisioning

images/confluence/download/attachments/894245057/provisioning.svg

Table of contents

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.

Create a Suite Auth client

Each call to our services needs to be authorized.
In this case, you will use the Suite Auth approach provided by the Bosch IoT Suite portal.

  1. Navigate to the Bosch IoT Suite portal https://accounts.bosch-iot-suite.com/subscriptions/

  2. Click the images/confluence/download/thumbnails/894245057/my-account.png icon for My Account

  3. Click the link for OAuth2 Clients

  4. Click + New OAuth2 Client

    images/confluence/download/attachments/894245057/suite-auth.png

    1. Set a name for the client.

    2. Select the Hub and the Things scopes.

    3. Click Create to store the entries.
      You may need to Refresh the page after a few seconds to see your OAuth 2 client details.

      Henceforth, whenever you need a token this client can create one.

Example - Simple device registration

Request

  1. Authorize

    1. Click Use Client - this will generate a token (JWT) which is valid for 60 minutes.

    2. Click Copy to clipboard to copy the Test Token to your clipboard.

    3. Your entry point into our interactive API documentation is Bosch IoT Suite - Device Provisioning.

      1. Open the Authorization dialog.

        images/confluence/download/attachments/894245057/auth-things-api.png
      2. Paste your Bearer token into the Value field.

      3. Confirm with Authorize.

      4. Close the dialog.

  2. Use the provisioning resource.
    POST /{service-instance-id}/devices

  3. Click Try it out to get all entry fields editable.

  4. Set the service-instance-id.
    If you have not stored your credentials at the end of the step Subscribe a package instance,
    open an new tab and navigate https://bosch-iot-suite.com/ > Service Subscriptions > your instance > ... Show Credentials
    copy the value of your Service Instance ID and switch back to the API docs to enter it in the respective field.

  5. Edit the content for the body.

  6. Set the minimal request body.

    • 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. See First configuration steps.

    • The "hub" entries : For your credentials you can set the password in plain text here, as we use HTTPS.
      It will be stored on the backend in the hashed form.

    • The "thing" entry could theoretically remain empty (an empty "POST" thing is supported and would generate an empty thing and its default policy).

      {
      "id": "your.namespace:device-4711",
      "hub": {
      "device": { },
      "credentials": {
      "type": "hashed-password",
      "secrets": [
      {
      "password": "your-secret-in-plain-text-will-be-hashed-automatically"
      }
      ]
      }
      },
      "things": {
      "thing": {
      "attributes": {
      "manufacturer": "My awesome company"
      }
      }
      }
      }
  7. Click Execute to submit the request.

  8. Verify that the request was successful Code 201.

Response

You can download the result as JSON for further requests.

A successful response would look like the following snippet.

{
"id": "your.namespace:device-4711",
"hub": {
"credentials": {
"tenantId": "xxx_hub",
"deviceId": "your.namespace:device-4711",
"type": "hashed-password",
"authId": "your.namespace_device-4711",
"enabled": true,
"secrets": [
{
"password": "your-secret"
}
],
"adapters": [
...
]
},
"device": {
"deviceId": "your.namespace:device-4711"
}
},
"things": {
"thing": {
"attributes": {
"manufacturer": "My awesome company"
},
"thingId": "your.namespace:device-4711",
"policyId": "your.namespace:device-4711",
...
}
}
}

Summary

Upon success, you have created following entities:

Your physical device will send its telemetry data to this "digital twin". Now learn how to Make things accessible for the Things dashboard.