Bosch IoT Rollouts

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:

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

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 images/confluence/download/thumbnails/1680489074/plus.png 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 images/confluence/download/thumbnails/1680489074/question-circle.png .


images/confluence/download/attachments/1680489074/provisioning_a_device.gif


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.

images/confluence/download/attachments/1680489074/securityToken_setting.png


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 images/confluence/download/thumbnails/1680489074/question-circle.png to REGISTERED images/confluence/download/thumbnails/1680489074/dot-circle.png .

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:

images/confluence/download/attachments/1680489074/target_details_attributes_ddi.png


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 images/confluence/download/thumbnails/1680489074/list.png 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 images/confluence/download/thumbnails/1680489074/plus.png .

images/confluence/download/attachments/1680489074/target_details_metadata_add.png

The keys are displayed under the Metadata tab in the target details table. Click them to see their value.

images/confluence/download/attachments/1680489074/target_details_metadata.png

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 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 to register the device and update its attributes.

Via Direct Device Integration API

A device which has not previously been provisioned via Management UI 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.

images/confluence/download/attachments/1680489074/gatewayToken_setting.png

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.

$ 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:

images/confluence/download/attachments/1680489074/target_details_attributes_ddi.png