Device provisioning

There are several ways of provisioning devices in Bosch IoT Rollouts. They can either be

Once a device is registered, it can provide additional information in 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

Bosch IoT Rollouts manages devices (a.k.a. Targets) in the Deployment view.

A user provisions a new target by clicking on the of images/confluence/download/thumbnails/1680489074/plus.png icon the Targets table.

After creation, and until the target connects for the first time, the target is in state UNKNOWN, 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 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"
},
"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