Updating Many Devices

Overview

This workflow covers the following steps:

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

Updating a Device

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 a Bosch IoT Rollout’s rollout management can be used. Therefore, we will use the hawkBit Device Simulator to set up some demo devices simulating our global fleet, 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 explained here.

$ 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 icon and providing a name and query. The query supports auto-completion. For further reference you can see the How to Filter section. 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*, and AMER_Devices: name==amer*.

Creating a Target Filter in UI

Via Management API

Creating a Target Filter can be done with a single REST call containing the query string (cf. syntax) 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 Target 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 Rollouts 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 definiton 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 icon. Now that the rollout is approved, it can be started by clicking on the icon.

Provision Target in UI

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

$ curl 'https://<HOST>/rest/v1/rollouts' -u "<TENANT_ID>\<USERNAME>:<PASSWORD>" -i -X POST -H 'Content-Type: application/json' -d '{
  "distributionSetId" : 2829,
  "targetFilterQuery" : "description=='Plug and Play*'",
  "name" : "MyOS-Global-Rollout-1.0",
  "description" : "Global rollout of MyOS",
  "groups" : [
  {
      "name" : "EMEA_Devices",
      "description" : "Devices in EMEA",
      "targetFilterQuery" : "name==emea*",
      "successCondition" : {
        "condition" : "THRESHOLD",
        "expression" : "70"
      },
      "successAction" : {
        "expression" : "",
        "action" : "NEXTGROUP"
      },
      "errorAction" : {
        "expression" : "",
        "action" : "PAUSE"
      },
      "errorCondition" : {
        "condition" : "THRESHOLD",
        "expression" : "20"
      }
    },
    {
      "name" : "APAC_Devices",
      "description" : "Devices in APAC",
      "targetFilterQuery" : "name==apac*",
      "successCondition" : {
        "condition" : "THRESHOLD",
        "expression" : "50"
      },
      "successAction" : {
        "expression" : "",
        "action" : "NEXTGROUP"
      },
      "errorAction" : {
        "expression" : "",
        "action" : "PAUSE"
      },
      "errorCondition" : {
        "condition" : "THRESHOLD",
        "expression" : "20"
      }
    },
    {
      "name" : "AMER_Devices",
      "description" : "Devices in AMER",
      "targetFilterQuery" : "name==amer*",
      "successCondition" : {
        "condition" : "THRESHOLD",
        "expression" : "25"
      },
      "successAction" : {
        "expression" : "",
        "action" : "NEXTGROUP"
      },
      "errorAction" : {
        "expression" : "",
        "action" : "PAUSE"
      },
      "errorCondition" : {
        "condition" : "THRESHOLD",
        "expression" : "20"
      }
  }]
}'

{
  "createdBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
  "createdAt": 1530629793920,
  "lastModifiedBy": "CLD:83717175-0650-400a-b6f2-9a4a398fc07a",
  "lastModifiedAt": 1530629793920,
  "name": "MyOS-Global-Rollout-1.0",
  "description": "Global rollout of MyOS",
  "targetFilterQuery": "description=='Plug and Play*'",
  "distributionSetId": 2829,
  "status": "creating",
  "totalTargets": 45,
  "totalTargetsPerStatus": {
    "running": 0,
    "notstarted": 45,
    "scheduled": 0,
    "cancelled": 0,
    "finished": 0,
    "error": 0
  },
  "deleted": false,
  "_links": {
    "start": {
        "href": "https://<HOST>/rest/v1/rollouts/61/start"
    },
    "pause": {
        "href": "https://<HOST>/rest/v1/rollouts/61/pause"
    },
    "resume": {
        "href": "https://<HOST>/rest/v1/rollouts/61/resume"
    },
    "approve": {
        "href": "https://<HOST>/rest/v1/rollouts/61/approve"
    },
    "deny": {
        "href": "https://<HOST>/rest/v1/rollouts/61/deny"
    },
    "groups": {
        "href": "https://<HOST>/rest/v1/rollouts/61/deploygroups?offset=0&limit=50"
    },
    "self": {
        "href": "https://<HOST>/rest/v1/rollouts/61"
    }
  },
  "id": 61
}

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 has to have 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 

Updating a Device [Top ]