Bosch IoT Rollouts

Direct Device Integration API

This API is only available if you are using Bosch IoT Rollouts as a standalone service.

It is not applicable if you are using Bosch IoT Rollouts as part of your Bosch IoT Device Management subscription because there the device connectivity layer is implemented by Bosch IoT Hub. For such a scenario, please read here.

This API is based on HTTP standards and based on a polling mechanism.

The Rollouts update server provides REST resources which are consumed by the device to retrieve software update tasks. That includes the artifact download with support for RFC7233 range requests.

Note: In DDI the target is identified using a controllerId. Controller is used as a term for the actual service/client on the device. This enables users to have even multiple clients on the same target for different tasks, e.g. Firmware update and App management.

Please be aware of the existence of a Quota. We also recommend to check out the target and action state machines.

Table of contents:

Eclipse hawkBit™ compatibility

Bosch IoT Rollouts DDI API is fully compatible to Eclipse hawkBit’s DDI API in version 1 (v1).

As a result hawkBit compatible clients can be used with Rollouts, e.g. SWupdate which is a Linux Update agent with focus on an efficient and safe way to update embedded systems.

The hawkBit project provides Java representations that allow to decode the message body at runtime into a Java object (that is if you have the luxury of Java on your device). The Java models can also be used to encode Java objects into JSON bodies to send a requests to Rollouts. The project as well provides examples leveraging the Feign client.

The model is available on Maven central, e.g. in Maven


State machine mapping

For historical reasons the DDI has a different state machine and status messages than the Target State Machine of the Rollouts update server.

This is kept to ensure that DDI stays compatible for devices out there in the field. A future version “2” of DDI might change that. DDI also defines more states than the update server, e.g. different DDI states are currently mapped by the implementation to RUNNING state. It is possible that in the future Rollouts will fully leverage these additional states.

The DDI API allows the device to provide the following feedback messages:

DDI status.execution type

handling by update server

Mapped ActionStatus type


This is sent by the target as confirmation of a cancellation request by the update server.



This is sent by the target in case an update of a cancellation is rejected, i.e. cannot be fulfilled at this point in time. Note: the target should send a CLOSED->ERROR if it believes it will not be able to proceed the action at all.



Target completes the action either with status.result.finished SUCCESS or FAILURE as result. Note: DDI also defines a status NONE which will not be interpreted by the update server and handled like SUCCESS.



This can be used by the target to inform that it is downloading artifacts of the action.



This can be used by the target to inform that it has downloaded artifacts of the action.



This can be used by the target to inform that it is working on the action.



This can be used by the target to inform that it scheduled on the action.



This can be used by the target to inform that it continued to work on the action.