Update many devices

This workflow covers the following steps:

  • create a target filter

  • create and start a rollout (incl. approval workflow)

Table of contents:

Introduction

The previous section showed how an update can be installed to a single device without much effort.

Now we want to update a large number of devices demonstrating how the rollout management can be used.

We will use the hawkBit Device Simulator to setup some demo devices simulating our global fleet, and learn how we can manage them using target filters, before we create a rollout to update all of them in a defined way.

Prerequisites

Setting up many devices with hawkBit device simulator

One way of creating a large number of devices for demo purposes is the hawkBit Device Simulator.

While the simulator supports both DMF and DDI, we want to use DDI here. Therefore, we have to disable DMF as described in the README.md under hawBit APIs. Once the simulator is running, devices are created via REST.

For this example, we create three groups (emeadevice, apacdevice, amerdevice) with 15 devices each.

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

$ curl 'http://localhost:8083/start?name=emeadevice&amount=15&tenant=<TENANT_ID>&api=ddi&endpoint=<HOST>&gatewaytoken=<GATEWAY_TOKEN>'
 
$ curl 'http://localhost:8083/start?name=apacdevice&amount=15&tenant=<TENANT_ID>&api=ddi&endpoint=<HOST>&gatewaytoken=<GATEWAY_TOKEN>'
 
$ curl 'http://localhost:8083/start?name=amerdevice&amount=15&tenant=<TENANT_ID>&api=ddi&endpoint=<HOST>&gatewaytoken=<GATEWAY_TOKEN>'

Enabling the approval workflow

It may be necessary that an update has to be approved by a superior or responsible, before it can be rolled out.

This is supported in Bosch IoT Rollouts by the Approval Workflow feature.

To enable it, you have to go to System Configuration view > Rollout Configuration and enable “Approve rollout …”.

Creating a target filter

Target filters help to manage devices by grouping them according to a query.

Additionally, these filters are used for auto-assignments of updates i.e., a newly registered device fitting the query will be automatically updated with the selected Distribution Set.

In the Management UI, these filters are also required for selecting devices in a rollout.

Via Management UI

Target filters are managed in the Target Filters view. A filter is created by clicking on the plus icon images/confluence/download/thumbnails/1680491202/plus.png and providing a name and query.

The query supports auto-completion. For further reference you can see Target filters view.

To query for all simulated devices, use the following expression: description==Plug* and save it as All_Devices filter.

Additionally, add three filters for the device groups from the different regions:

  • EMEA_Devices: name==emea*

  • APAC_Devices: name==apac*

  • AMER_Devices: name==amer*

images/confluence/download/attachments/1680491202/creating_target_filter.gif

Via Management API

Creating a Target Filter can be done with a single REST call containing the query string (see syntayx at Target filters view) and the desired name.

$ curl 'https://<HOST>/rest/v1/targetfilters' -u "<TENANT_ID>\<USERNAME>:<PASSWORD>" -i -X POST -H 'Content-Type: application/json' -d '{
"query" : "name==emeadevice*",
"name" : "EMEA_Devices"
}'
 
{
"createdBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
"createdAt": 1530626882492,
"lastModifiedBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
"lastModifiedAt": 1530626882492,
"name": "EMEA_Devices",
"query": "name==emeadevice*",
"autoAssignDistributionSet": null,
"_links": {
"self": {
"href": "https://<HOST>/rest/v1/targetfilters/75"
},
"autoAssignDS": {
"href": "https://<HOST>/rest/v1/targetfilters/75/autoAssignDS"
}
},
"id": 75
}

Use the same endpoint to create filters for:

  • APAC_Devices,

  • AMER_Devices, and

  • ALL_Devices (name==*).

Creating a rollout

Let’s install our MyOS update to all our 45 devices.

While we could use the same mechanisms as described for updating a single device, Bosch IoT Rollouts provides a more scalable and manageable approach for rolling out updates to a large number of devices: rollout management.

Via Management UI

Switch over to the Rollout view and click on the icon to create a new rollout.

Start by giving a name and selecting the desired Distribution set.

The selected Custom Target Filter has to contain all devices, which should get updated. In our case, that would be All_Devices.

Now, switch to the Advanced Group definition tab and create sub-groups using the EMEA-, APAC-, AMER-device filters.

Finally, you can change the Trigger threshold of the EMEA group to 70 i.e., wait until 70 % of the devices of this group were updated successfully before triggering the next group.

Moreover, reduce the Error threshold to 20 i.e., pause the rollout immediately if more than 20 % of the updates of a group were not successful.

After saving the rollout, an approver has to approve the rollout by clicking on the handshake icon images/confluence/download/thumbnails/1680491202/handshake.png .

Now that the rollout is approved, it can be started by clicking on the play icon images/confluence/download/thumbnails/1680491202/play.png .

images/confluence/download/attachments/1680491202/updating_many_devices.gif

Via Management API

A rollout can be easily created using the following call.

On top level, we have to provide the update we want to install, a name and description, as well as a filter query containing all affected devices.
The request shown, utilizes the advanced group definition to further specify how the update should be rolled out.
There, we define three groups for the three regions, using the respective filter queries.

Finally, we can tweak the trigger- and error-threshold.

1: Create the rollout

2: Approve the rollout

Since we enabled the approval workflow, the rollout has to be approved before it can be started.

Additionally, a remark can be given.

Note: The user needs the APPROVE_ROLLOUT role.

curl 'https://<HOST>/rest/v1/rollouts/<RO_ID>/approve?remark=Formal+approval+given' -u "<TENANT_ID>\<USERNAME>:<PASSWORD>" -i -X POST

3: Start the rollout

Now that the rollout is approved, it can be started with a single API call.

curl 'https://<HOST>/rest/v1/rollouts/<RO_ID>/start' -u "<TENANT_ID>\<USERNAME>:<PASSWORD>" -i -X POST