Bosch IoT Device Management

Software update

In order to manage software updates within Bosch IoT Device Management it is important to understand which service is responsible for what
and how the concepts from Bosch IoT Rollouts (as a standalone service) are mapped to the multi-service architecture of the solution.

Table of contents:

This chapter reflects the functionalities of Bosch IoT Rollouts provided as the software update layer of Bosch IoT Device Management.

If you are using Bosch IoT Rollouts as a standalone service, see the official Bosch IoT Rollouts documentation.

This is important, as some functionalities and workflows may differ.

Service structure and device integration


Main responsibilities of the services in this architecture

Let us mention again what are the main responsibilities of each service:

Software update layer

  • Campaign management

  • Single-assignments

  • Artifact management and distribution

Mass management layer

Digital twin layer

  • Preserve last know state

  • Event fan-out

  • Per-thing access level security

Device connectivity layer

  • Device authentication

  • Protocol translation


  • edge-SW, and other clients

  • Receive commands from the device connectivity layer

  • Upload state (data)

  • Download updates

Introducing the SoftwareUpdatable feature

As a core concept of the digital twin layer we find the feature which represents a capability aspect of a device. In order to be able to have an abstraction-layer where all rollout-logic can be built on, the software update layer has defined the so called "SoftwareUpdatable" (SUP) feature definition by specifying an Eclipse Vorto model.
See the SoftwareUpdatable feature detailed specification and integration guide on how it has to be implemented on the device side.

Only a device (thing) which provides at least one SUP-feature will be picked up and listed by the software update layer. Bosch IoT Edge (aka go-client), Edge Services (java-client) and the Zephyr integration provided by Bosch IoT Suite support this feature implementation out-of the box.

The SoftwareUpdatable feature delivers operations to download and install software, operations for removing installed features and properties which enable the device to do detailed reporting about the installation progress and the current state of the device.

The first version "V1" of the SoftwareUpdatable feature has become deprecated with the GA of Bosch IoT Device Management and support will be stopped in the near future - please use version two (V2)!

SoftwareUpdatable V2 feature overview

The software updatable feature is defined in vorto-lang and public accessible via the Vorto GitHub Repository.

The top-level definition is this:

SUP v2
displayname "SoftwareUpdatable"
description "Represents the ability of a device to install and manage a certain type of software."
using org.eclipse.hawkbit.SoftwareUpdateAction;2.0.0
using org.eclipse.hawkbit.SoftwareRemoveAction;2.0.0
using org.eclipse.hawkbit.OperationStatus;2.0.0
using org.eclipse.hawkbit.DependencyDescription;2.0.0
functionblock SoftwareUpdatable {
status {
mandatory softwareModuleType as string "The type of the software managed by this feature."
// Optional software inventory and dependency management: Requrired when remove should be performed
optional installedDependencies as dictionary[string, DependencyDescription] "List of all installed software managed by this feature. The key should be the concatenated"
optional contextDependencies as dictionary[string, DependencyDescription] "Information additional dependencies relevant for software installation, e.g. hardware parts or runtimes like OSGi container or JREs."
// Operation status responses
optional lastOperation as OperationStatus "The last operation's status response."
optional lastFailedOperation as OperationStatus "The last operation status indicating a finished with error."
operations {
// Software installation
install(update as SoftwareUpdateAction) "Instruction to download and install."
download(update as SoftwareUpdateAction) "Instruction to download (without installing)."
cancel(update as SoftwareUpdateAction) "Try to cancel a running installation."
// Software removal
remove(software as SoftwareRemoveAction) "Remove an installed software."
cancelRemove(software as SoftwareRemoveAction) "Try to cancel a remove operation."

Mandatory operations:

  • install, download are expected to be supported by every implementation. The argument (SoftwareUpdateAction) contains all information needed for downloading and verifying the artifacts (URL + checksum) which should be installed.

  • cancel should be there but can be ignored

Mandatory properties:

  • lastOperation is used to communicate the progress/success/failure status of the update from the device back to the server-side and is tracked by IoT Rollouts in order to build up a history of the update progress.

  • softwareModuleType is used by IoT Rollouts in order to identify the feature, to which the commands should be sent for a certain kind of software.

All other properties and operations are not required for realizing a basic software update implementation, but required for more sophisticated device management scenarios.

For a complete and detailed documentation please see the SoftwareUpdatable feature detailed specification and integration guide.

Domain model/definitions

Within the different services, different domain models are used. This is also due to the long history of each of these services. This overview should help in understanding the relationship between these entities.


Example communication path for an install-operation:

  1. A rollout is created by defining a TargetQuery and a DistributionSet containing one or more SoftwareModules.

  2. The targets selected by this query are ordered into RolloutGroups.

  3. Per RolloutGroup a rule is created in the mass management layer.

  4. The rule will spawn one or more tasks per device containing the install commands with its arguments.

  5. The install operation will be invoked on the SoftwareUpdatable feature having the same SoftwareModuleType as the SoftwareModule in the DistributionSet.

  6. When the device is online it will receive this command via digital twin layer to the device connectivity layer.

  7. In case that the device is behind a gateway, the command will be routed through this gateway.

  8. The feature implementation on the device is responsible to acknowledge the install command and proceed with the installation procedure accordingly to the received parameters.

  9. The progress of the installation can be communicated by the device by sending property-updates to the operationStatus on it's feature representation in the thing.

  10. The last transmitted status must be one of the "FINISHED..." status in order to report success/failure of the update.

Differences in the data-model of Bosch IoT Rollouts as standalone service and the software update layer of Bosch IoT Device Management

The data model of Bosch IoT Rollouts is documented in its service documentation.
The management of the following entities has been changed in the software update layer of Bosch IoT Device Management:


  • Master of data is the digital twin layer, therefore targets cannot be created or deleted within the software update layer.

  • In order to create a target/device, the provisioning API should be used.

  • The controllerId within a target is the thing ID.

  • In queries the ID property-name will be mapped on the thing ID.


  • Tag management happens through the mass management layer.

  • Tags will be created as things and assigned tags are visible in the attributes of the device thing.

  • Tag creation is still possible through the software update layer (for backward compatibility and usability reasons, with a switch to a unified UI this might change so we recommend to use the mass management layer's API instead of Bosch IoT Rollouts' APIs if required.

  • Tags in the software update layer require a numerical ID (i.e. for the REST API) so we auto-assign such an ID at the point in time where tag is queried the first time from the mass management layer.


  • Can still be created and managed from Bosch IoT Rollouts but will be located in an attribute in the device thing.

  • Metadata queries are mapped to the attribute in the device thing.


  • Not supported anymore - also the "request controller attributes" API or UI-button does not work.
    Controller attributes are properties reported by the device to Bosch IoT Rollouts (standalone), as part of the Device Management solution context this is the "whole" thing itself.

  • All thing attributes/features/properties can be used for formulating queries - still by now there is no auto-completion support for this.


  • It is not possible to define any arbitrary software module types - they must match the SoftwareUpdatable features available on the device. An auto-import of this type will be done.

Using multiple SoftwareUpdatable features

In cases that involve different types of software which are managed by completely different implementations on the same device, each of these implementations should get its own feature on the digital twin.

A software update within the software update layer can still consist out of different software module types. The installation process will pick the right feature from the thing and send the instructions to the matching implementation on the device.


Structuring different types of updates into different features will become even more useful in cases when the SoftwareUpdatable implementation does report their "installed" dependencies (software inventory) and their "context" dependencies (external, not modifiable) parameters, like CPU architecture, memory and others.

Device authentication (on the download-URLs)

Currently there is no authentication required for the device on the URLs to download the artifacts. Still, the transmitted URLs do only have a limited amount of time until they are valid.

Software update state-machines and the status reported by the device

Within the software update layer there are multiple state machines used. The operation status reported by the SoftwareUpdatable feature will be mapped on the action status on the server-side and finally control the progress of the assignment and the campaign.

Most of the intermediate states are optional, but the final state after receiving a download or install command should always be in one of the FINISHED_... statuses.

For a complete list and more details please see SoftwareUpdatable feature detailed specification and integration guide.