Update a single device
This workflow covers the following steps:
assign a distribution set to a device
download the update on device-side
provide feedback to Bosch IoT Rollouts
Table of contents:
Introduction
Updating a device requires actions both on the management side (UI/API) and the device side (DDI/DMF).
First, the already created update has to be assigned to a device. Then, the device has to retrieve the update, install it, and provide feedback to Bosch IoT Rollouts whether the update has been successful or not.
1: Assign a Distribution Set to a device
The initial step of installing an update to a device is the assignment of a Distribution Set to a device. This can be done by using either the Management UI or the Management API.
Via Management UI
Go to the Deployment view and assign the update by dragging&dropping the Distribution Set (myOs-DS) on the respective device (Device 01).
Via Management API
To install the update that was created in the previous step, we have to assign the Distribution Set (DS_ID=2829) containing the update to a device. This is done with the following call.
The respective replacement tokens are listed at Getting started > API Replacement Token.
$ curl
'https://<HOST>/rest/v1/distributionsets/<DS_ID>/assignedTargets/'
-u
"<TENANT_ID>\<USERNAME>:<PASSWORD>"
-i -X POST -H
'Content-Type: application/json;charset=UTF-8'
-d'[{
"id"
:
"device03"
,
"type"
:
"forced"
}]'
{
"assigned"
:
1
,
"alreadyAssigned"
:
0
,
"total"
:
1
}
The target status of device03 changed from REGISTERED
to PENDING
and is waiting now for the device to poll for updates.
2: Updating from a device’s perspective
After the update has been assigned to a device from management side, it is the device’s turn.
It can either discover that there is an update by polling via Direct Device Integration API, or react to the DOWNLOAD_AND_INSTALL event sent via Device Management Federation API.
Via Direct Device Integration API
Retrieving an update via Direct Device Integration API comprises at least four steps:
2.1: Poll for Updates
A device connected to Bosch IoT Rollouts via DDI usually polls its resource in a configured time interval. Once a Distribution Set is assigned to that device, the response contains a link to the update (deploymentBase).
$ curl
'https://<HOST>/<TENANT_ID>/controller/v1/device03'
-i -H
'Accept: application/hal+json'
-H
'Authorization: TargetToken <TARGET_TOKEN>'
{
"config"
: {
"polling"
: {
"sleep"
:
"00:05:00"
}
},
"_links"
: {
"deploymentBase"
: {
"href"
:
"https://<HOST>/<TENANT_ID>/controller/v1/device03/deploymentBase/845?c=1492353743"
}
}
}
2.2: Get Information about the Update
Following the provided link to the update action, the device receives detailed information about the update. Among others, links to the comprised artifacts are provided.
$ curl
'https://<HOST>/<TENANT_ID>/controller/v1/device03/deploymentBase/845?c=1492353743'
-i -H
'Accept: application/hal+json'
-H
'Authorization: TargetToken <TARGET_TOKEN>'
{
"id"
:
"845"
,
"deployment"
: {
"download"
:
"forced"
,
"update"
:
"forced"
,
"chunks"
: [
{
"part"
:
"os"
,
"version"
:
"1.0"
,
"name"
:
"myOs"
,
"artifacts"
: [
{
"filename"
:
"example.file"
,
"hashes"
: {
"sha1"
:
"d2e7291c2c52b87b2ee00983217e1bcc0909251f"
,
"md5"
:
"b14f29fe8cea6b25e62a8e5c48b5a3a1"
,
"sha256"
:
"ef6f7bbae45f41b62c26c5150e3ee673b4169991c5c570393fbc4e8d43581016"
},
"size"
:
28
,
"_links"
: {
"download"
: {
"href"
:
"https://<HOST>/<TENANT_ID/..."
}
}
}
]
]
}
}
2.3: Download the Artifact from the given URL
Following the download link of each artifact, a device can download all update relevant artifacts.
$ curl
'https://<HOST>/<TENANT_ID>/...'
-i -H
'Accept: application/hal+json'
-H
'Authorization: TargetToken <TARGET_TOKEN>'
This is a test update file.
2.4: Provide Feedback to Bosch IoT Rollouts
The device may choose how much feedback it wants to provide to Bosch IoT Rollouts. However, the information whether or not the update has been successful has to be given, allowing the backend to stay up to date regarding the installed Distribution Set.
$ curl
'https://<HOST>/<TENANT_ID>/controller/v1/device03/deploymentBase/845/feedback'
-i -X POST -H
'Accept: application/hal+json'
-H
'Authorization: TargetToken <TARGET_TOKEN>'
{
"id"
:
"845"
,
"status"
: {
"result"
: {
"finished"
:
"success"
},
"execution"
:
"closed"
,
"details"
: [ ]
}
}
As the target indicated that the update has been successful, the target status of device03 changed from PENDING
to IN_SYNC
.
Find details on State machines in section concepts.