Provisioning a Device

Overview

This workflow covers the following steps:

  • pre-provision a device via Management UI or Management API
  • register a device via Direct Device Integration API or Device Management Federation API
  • provide device metadata and attributes

Getting the Service Creating an Update

Introduction

There are four ways of provisioning devices in Bosch IoT Rollouts. They can either be pre-provisioned using the Management UI or the Management API, or a device (-management) itself can register with Bosch IoT Rollouts via Direct Device Integration API or Device Management Federation API. Once a device is registered, it can provide additional information in form of key-value attributes (a.k.a. Config Data).

Via Management UI

First, the device is provisioned via the UI before it registers itself providing further information.

1: Pre-provision a device

Bosch IoT Rollouts manages devices (a.k.a. Targets) in the Deployment view. A user provisions a new target by clicking on the of the Targets table. After creation, and until the target connects for the first time, the target is in state UNKNOWN, indicated by the icon.

Provision Target in UI

2: Register the device

Now, that the device is pre-provisioned, it can register itself via DDI and provide additional information. The required authentication is provided by the device’s Security Token. This can be enabled in the System Configuration view under Authentication ConfigurationAllow targets to authenticate directly …”. Enable it and then save it by clicking on the icon at the bottom of the page.

Enable Security Token Authentication

The device can now authenticate itself with its security token and update its status and attributes. First, register the device by polling the device’s DDI resource. The respective replacement tokens are explained here.

$ curl 'https://<HOST>/<TENANT_ID>/controller/v1/device01' -i -H 'Accept: application/hal+json' -H 'Authorization: TargetToken <TARGET_TOKEN>'

{
    "config": {
        "polling": {
            "sleep": "00:05:00"
        }
    },
    "_links": {
        "configData": {
            "href": "https://<HOST>/<TENANT_ID>/controller/v1/device01/configData"
        }
    }
}

You may notice, that the target state changed from UNKNOWN to REGISTERED . Finally, let’s add some attributes to the device by following the link to configData provided in response to our last call:

$ curl 'https://<HOST>/<TENANT_ID>/controller/v1/device01/configData' -i -X PUT -H 'Authorization: TargetToken <TARGET_TOKEN>' -H 'Content-Type: application/json;charset=UTF-8' -d '{
  "mode" : "merge",
  "data" : {
    "VIN" : "JH4TB2H26CC000000",
    "hwRevision" : "2"
  },
  "status" : {
    "result" : {
      "finished" : "success"
    },
    "execution" : "closed",
    "details" : [ ]
  }
}'

You can verify, that the attributes were set correctly, by checking the Attributes tab of the target details table:

Target Details

3: Add metadata

Custom metadata in the form of key-value pairs can be added to a device. You can edit a device’s metadata by clicking the icon in the target details table. Fill out the key and value field and click the Save Botton to add new data. More key-value pairs can be added by clicking the icon. The keys are displayed under the Metadata tab in the target details table. Click them to see their value.

Target Details

Via Management API

Similar to the Management UI, a device can be pre-provisioned using a single call to the Management API. The respective replacement tokens are explained here.

$ curl 'https://<HOST>/rest/v1/targets' -u "<TENANT_ID>\<USERNAME>:<PASSWORD>" -i -X POST -H 'Content-Type: application/json;charset=UTF-8' -d '[ {
  "controllerId" : "device02",
  "name" : "Device 02",
  "description" : "My first Device created via Management API."
} ]'

[
  {
    "createdBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
    "createdAt": 1530533483880,
    "lastModifiedBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
    "lastModifiedAt": 1530533483880,
    "name": "Device 02",
    "description": "My first Device created via Management API.",
    "controllerId": "device02",
    "updateStatus": "unknown",
    "securityToken": "51b8e7fb97fe10bd49a57ca39f19677d",
    "requestAttributes": true,
    "_links": {
      "self": {
        "href": "https://<HOST>/rest/v1/targets/device02"
      }
    }
  }
]

As the device is now pre-provisioned, you can take the same steps as for the Management UI to register the device and update its attributes.

Via Direct Device Integration API

A device can only connect and register with Bosch IoT Rollouts i.e., without having been previously provisioned via Management UI or Management API, by providing a gateway token to authenticate. This can be configured and retrieved in the System Configuration view under Authentication ConfigurationAllow a gateway to authenticate …”. Enable it and then save it by clicking on the icon.

Enable Gateway Token Authentication

The generated token can then be used in the authorization header of the request. The respective replacement tokens are explained here. A device registered via DDI-API is in state REGISTERED, indicated by the icon in the “Deployment” view of the Management UI.

$ curl 'https://<HOST>/<TENANT_ID>/controller/v1/device03' -i -H 'Accept: application/hal+json' -H 'Authorization: GatewayToken <GATEWAY_TOKEN>'

{
    "config": {
        "polling": {
            "sleep": "00:05:00"
        }
    },
    "_links": {
        "configData": {
            "href": "https://<HOST>/<TENANT_ID>/controller/v1/device03/configData"
        }
    }
}

Finally, let’s add some attributes to the device by following the link to configData provided in response to our last call:

$ curl 'https://<HOST>/<TENANT_ID>/controller/v1/device03/configData' -i -X PUT -H 'Authorization: GatewayToken <GATEWAY_TOKEN>' -H 'Content-Type: application/json;charset=UTF-8' -d '{
  "mode" : "merge",
  "data" : {
    "VIN" : "JH4TB2H26CC000001",
    "hwRevision" : "1"
  },
  "status" : {
    "result" : {
      "finished" : "success"
    },
    "execution" : "closed",
    "details" : [ ]
  }
}'

You can verify, that the attributes were set correctly, by checking the Attributes tab of the target details table:

Target Details

Getting the Service [Top ] Creating an Update