Introduction

Updating a device requires actions taken from both, the management side (UI/API) and the device side (DDI/DMF).

First, the previously created update has to be assigned to a device. In a second step, 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 either using the Management UI or the Management API.

Via Management UI

Go to the Deployment view and assign the update by drag&drop the Distribution Set (myOs-DS) on the respective device (Device 01).

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

Via Management API

To install the update, that we 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.