Bosch IoT Rollouts

Create an update

This scenario covers the following steps:

  • create a software module

  • upload an artifact

  • create a distribution set

  • assign a software module to a distribution set


Table of contents:

Introduction

After the device has been registered with Bosch IoT Rollouts, you can create the update you want to install on the device by using either the Management UI or the Management API.


Via Management UI

When using the Management UI (part of the common Bosch IoT Suite UI), follow these steps:

Create a software module

  1. Open the Software modules UI feature by selecting it from the left navigation.
    The List menu in the sub-navigation opens by default.

  2. Create your first software module by clicking the + icon on the top right.

    images/confluence/download/attachments/1680491195/roUi-softm-create1-version-3-modificationdate-1697635906000-api-v2.png
  3. Fill in all required fields in the Add software module dialog:

    1. Select OS as type.

    2. Type in a unique name.

    3. Type in its version.

    4. Optionally add the vendor name, a description, and enable artifact encryption.

images/confluence/download/attachments/1680491195/roUi-softm-create2-version-3-modificationdate-1697636032000-api-v2.png

Once created, the software module will appear on the list.

For a detailed guide refer to Create a software module and Manage artifacts.

Upload an artifact

As a next step, you need to upload an artifact to the software module.

  1. Select the newly created software module to open its details and artifacts views.

  2. Click the + icon in the Artifacts view to upload one or multiples files (a.k.a. Artifacts) into your module.

images/confluence/download/attachments/1680491195/roUi-softm-uploadArtifact1-version-2-modificationdate-1697464338000-api-v2.png

Create a distribution set

Now, a distribution set is required to package your software module(s).

  1. To create one, go to the Distribution sets UI feature on the left navigation.

  2. Select List from the sub-navigation (should be selected by default).

  3. Then, click on the + icon at the top right of the view.

  4. In the Add distribution set dialog that opens up, fill in all the required fields.
    Choose the same type as the type of your software module, i.e. OS only.

The type of the distribution set has to be the same as the type of the software module. Otherwise, the software module will not appear in the list, and you will not be able to assign it to the distribution set.

The Migration step is required toggle is explained here.

images/confluence/download/attachments/1680491195/roUI-ds-createDistSet-version-1-modificationdate-1697451131000-api-v2.png

Assign the software module to the distribution set

As a final step, you have to assign your software module to your distribution set:

  1. Select the desired distribution set.

  2. Click the Assign software modules icon images/confluence/download/thumbnails/1680491195/link-version-1-modificationdate-1683724934000-api-v2.png in the top right area.

  3. Select the required software module from the list.

  4. Click Assign.

images/confluence/download/attachments/1680491195/roUI-ds-assignDistSet-version-1-modificationdate-1697451408000-api-v2.png


Via Management API

Creating an update via the Management API requires four calls:

Create a software module

You start by creating a software module.

The respective replacement tokens are listed at Getting started > API Replacement Token.

$ curl 'https://<HOST>/rest/v1/softwaremodules' -u "<TENANT_ID>\<USERNAME>:<PASSWORD>" -i -X POST -H 'Content-Type: application/json;charset=UTF-8' -d'[{
"vendor" : "Bosch",
"name" : "new-software-module",
"description" : "First version of MyOS.",
"type" : "os",
"version" : "2.0"
}]'
[
{
"createdBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
"createdAt": 1530539254263,
"lastModifiedBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
"lastModifiedAt": 1530539254263,
"name": "new-software-module",
"description": "First version of MyOS.",
"version": "2.0",
"type": "os",
"vendor": "Bosch",
"deleted": false,
"_links": {
"self": {
"href": "https://<HOST>/rest/v1/softwaremodules/1500"
}
},
"id": 1500
}
]

Upload an artifact

Now you can upload files to your newly created software module (SM_ID=1500).

You can take any file you want or create a demo file by running the following command in your terminal

echo "This is a test update file." > example.file.

$ curl 'https://<HOST>/rest/v1/softwaremodules/<SM_ID>/artifacts' -u "<TENANT_ID>\<USERNAME>:<PASSWORD>" -i -X POST -H 'Content-Type: multipart/form-data' -F 'file=@example.file'
 
{
"createdBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
"createdAt": 1530539803637,
"lastModifiedBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
"lastModifiedAt": 1530539803637,
"hashes": {
"sha1": "d2e7291c2c52b87b2ee00983217e1bcc0909251f",
"md5": "b14f29fe8cea6b25e62a8e5c48b5a3a1"
},
"providedFilename": "example.file",
"size": 28,
"_links": {
"self": {
"href": "https://<HOST>/rest/v1/softwaremodules/1500/artifacts/335"
},
"download": {
"href": "https://api.eu1.bosch-iot-rollouts.com/rest/v1/softwaremodules/1500/artifacts/335/download"
}
},
"id": 335
}

Create a distribution set

In this third step, you have to create a distribution set which can be rolled out to a device.

$ curl 'https://<HOST>/rest/v1/distributionsets' -u "<TENANT_ID>\<USERNAME>:<PASSWORD>" -i -X POST -H 'Content-Type: application/json;charset=UTF-8' -d'[{
"requiredMigrationStep": false,
"name": "My-first-distribution-set",
"description": "Update of EMEA devices",
"type": "os",
"version": "1.0",
"modules": [
{
"id": 1500
}
]
}]'
 
[
{
"createdBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
"createdAt": 1530540407559,
"lastModifiedBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
"lastModifiedAt": 1530540407559,
"name": "My-first-distribution-set",
"description": "Update of EMEA devices",
"version": "1.0",
"modules": [
{
"createdBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
"createdAt": 1530539254263,
"lastModifiedBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
"lastModifiedAt": 1530539803644,
"name": "My-first-distribution-set",
"description": "Update of EMEA devices",
"version": "1.0",
"type": "os",
"vendor": "Example Ltd.",
"deleted": false,
"_links": {
"self": {
"href": "https://<HOST>/rest/v1/softwaremodules/1500"
}
},
"id": 1500
}
],
"requiredMigrationStep": false,
"type": "os",
"complete": true,
"deleted": false,
"_links": {
"self": {
"href": "https://<HOST>/rest/v1/distributionsets/2829"
}
},
"id": 2829
}
]

Assign the software module to the distribution set

Finally, you have to assign the software module (SM_ID=1500), containing the update, to the distribution set (DS_ID=2829).

$ curl 'https://<HOST>/rest/v1/distributionsets/<DS_ID>/assignedSM' -u "<TENANT_ID>\<USERNAME>:<PASSWORD>" -i -X POST -H 'Content-Type: application/json;charset=UTF-8' -d '[{
"id": <SM_ID>
}]'