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
1: Assign a distribution set to a device
2: Updating from a device’s perspective
- Via Direct Device Integration API

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.

images/confluence/download/attachments/1680491200/ro-getStarted-updateSingleDevice-newUI---onlyTargetFilter.gif

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.

images/confluence/download/attachments/1680491200/ro-getStarted-updateSingleDevice-newUI---onlyRollout.gif

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).

images/confluence/download/attachments/1680491200/updating_a_single_device.gif

Special case - manual assignment with enabled User consent flow feature

The process illustrated above differs when the user consent flow feature has been activated for the particular tenant.

In that case the Confirm assignment dialog will contain an additional option where you can specify whether the Confirmation required flow should be applied to for this particular assignment.

When the user consent flow feature has been activated for the tenant, this checkbox is activated by default for each assignment.

If you choose to deactivate it for the particular assignment, the assignment will be fulfilled as usual, as the confirmation will be treated as automatically granted.

Otherwise, please consider the additional action states as described in Action state machine.

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.