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:

Service structure and device integration
- Main responsibilities of the services in this architecture
Introducing the SoftwareUpdatable feature
- SoftwareUpdatable V2 feature overview
Domain model/definitions
- Example communication path for an install-operation:
- Differences in the data-model of Bosch IoT Rollouts as standalone service and the Device Management solution
Using multiple SoftwareUpdatable features
Device authentication (on the download-URLs)
The Bosch IoT Rollouts state-machines and the status reported by the device

Service structure and device integration

images/inline/99f82185c196742678505d45eea674de8349df0a.png

Main responsibilities of the services in this architecture

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

Bosch IoT Rollouts	Campaign management Single-assignments Artifact management and distribution
Bosch IoT Manager	General device management functions Tagging & grouping of devices Mass-operations
Bosch IoT Things	Preserve last know state Event fan-out Per-thing access level security
Bosch IoT Hub	Device authentication Protocol translation
Devices	edge-SW, and other clients Receive commands from IoT Hub Upload state (data) Download updates

Introducing the SoftwareUpdatable feature

As a core concept of Bosch IoT Things 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, Bosch IoT Rollouts 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 Bosch IoT Rollouts. 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 group.name:version."
	   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 (URLs + checksums) 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.

images/inline/163e71f444985bc481a0abedb64d33a8b077454e.png

Example communication path for an install-operation:

A rollout is created by defining a TargetQuery and a DistributionSet containing one or more SoftwareModules.
The targets selected by this query are ordered into RolloutGroups.
Per RolloutGroup a rule is created in Bosch IoT Manager.
The rule will spawn one or more tasks per device containing the install commands with its arguments.
The install operation will be invoked on the SoftwareUpdatable feature having the same SoftwareModuleType as the SoftwareModule in the DistributionSet.
When the device is online it will receive this command via IoT Things and IoT Hub.
In case that the device is behind a gateway, the command will be routed through this gateway.
The feature implementation on the device is responsible to acknowledge the install command and proceed with the installation procedure accordingly to the received parameters.
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.
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 Device Management solution

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

Targets:

Master of data is Bosch IoT Things, therefore targets cannot be created or deleted within IoT Rollouts.
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.

Tags:

Tag management happens through Bosch IoT Manager.
Tags will be created as things and assigned tags are visible in the attributes of the device thing.
Tag creation is still possible through Bosch IoT Rollouts (for backward compatibility and usability reasons, with a switch to a unified UI this might change so we recommend to use Bosch IoT Manager's API instead of IoT Rollouts' APIs if required.
Tags in Bosch IoT Rollouts 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 IoT Manager.

Metadata:

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.

Attributes:

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.

SoftwareModuleType

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 Bosch IoT Rollouts 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.

images/inline/b4b5ce31e796d93fb7d6a9bad18f1c6875c0cea8.png

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.

The Bosch IoT Rollouts state-machines and the status reported by the device

Within Bosch IoT Rollouts 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.

images/inline/d10de288d76c57dab683fd611ade123767d61451.png