Device provisioning
This page describes the device provisioning process for users of Bosch IoT Rollouts as a standalone service.
If you are using Bosch IoT Rollouts as part of your Bosch IoT Device Management subscription, the provisioning should be done as described in Provisioning of devices or via the respective APIs.
There are several ways of provisioning devices in Bosch IoT Rollouts:
a device can be pre-provisioned - using the Management UI (Classic) or the Management API - and then registered, or
a device (-management) itself can register with Bosch IoT Rollouts via the Direct Device Integration API or the Device Management Federation API.
Once a device is registered, it can provide additional information in the form of key-value attributes (a.k.a. Controller Attributes).
Table of contents:
Via Management UI (Classic)
First, the device is provisioned via the UI before it registers itself providing further information.
1: Pre-provision a device
With Bosch IoT Rollouts, devices (a.k.a. Targets) are managed in the Deployment view.
You can provision a new target by clicking the 
icon in the Targets table.
In the dialog, provide the mandatory Controller ID, and the optional Name and Description.
After the target is created and until it connects for the first time, its state is UNKNOWN, also indicated by the question mark icon 
.
2: Register the device
Now, that the device is pre-provisioned, it can register itself via the Direct Device Integration API (DDI) and provide additional information.
The required authentication is provided by the device’s Security Token (see Authentication > Target security token.)
This can be enabled in the System configuration view under Authentication Configuration > “Allow targets to authenticate directly …”.
Enable it and then save it by clicking on the save icon at the bottom of the page.
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 listed at Getting started > API Replacement Token.
$ 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:
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 list icon 
in the target details table.
Fill out the key and value field and click the save button to add new data.
More key-value pairs can be added by clicking the plus icon
.
The keys are displayed under the Metadata tab in the target details table. Click them to see their value.
Via Management API
Similar to the Management UI (Classic), a device can be pre-provisioned using a single call to the Management API.
The respective replacement tokens are listed at Getting started > API Replacement Token.
$ 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 (Classic) to register the device and update its attributes.
Via Direct Device Integration API
A device which has not previously been provisioned via Management UI (Classic) or Management API, can access Bosch IoT Rollouts by providing a gateway token to authenticate. See Authentication > Gateway security token.
This can be configured and retrieved in the System Configuration view under Authentication Configuration > “Allow a gateway to authenticate …”.
Enable it and then save it by clicking on the save icon.
The generated token can then be used in the authorization header of the request.
The respective replacement tokens are listed at Getting started > API Replacement Token.
A device registered via DDI API is in state REGISTERED, indicated by the icon in the Deployment view of the Management UI (Classic).
$ 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" }}'You can verify that the attributes were set correctly by checking the Attributes tab of the target details table: