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.
In case the user consent flow feature has been activated for the particular tenant, there is a step in between, where the end user is asked to confirm their consent to receive the update before the device can actually retrieve the update.
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 UIs or the Management API.
Via Management UI
When using the Management UI (part of the common Bosch IoT Suite UI), follow these steps:
Target filter
To update a single device you first need to create a target filter, filtering out all other devices
Go to Targets from the left navigation and type in the following query:
name == {{name-of-device}}
Click the Save icon above and type in a user-friendly name.
For a detailed guide refer to List and filter targets.
Rollout
Open the Rollouts UI feature from the left navigation and click the + icon in the header of the view.
In the first wizard step, Targets and distribution set, type in the rollout name and description.
From the respective drop-downs, select the Target filter you just created, as well as the Distribution set you want to distribute to the device.
You can skip the Group definition step by clicking Next, as you are updating only one device.
On the Action type and start option step, choose Forced and Auto.
Review your settings and click Create.
The new rollout will be displayed as part of your Rollouts list.
For a detailed guide refer to Create a rollout.
Via Management UI (Classic)
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, you 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"
}
}
}
There is a slight difference when the user consent flow feature has been activated for this tenant.
In such a case, instead of a deploymentBase, the response will contain a confirmationBase and the device has to interact with it to confirm the action. Find out more here.
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.