This Direct Device Integration (DDI) API is based on HTTP standards and based on a polling mechanism.
The Rollouts update server provides REST resources that the device uses to retrieve software update tasks. That includes the artifact download, with support for RFC 7233 range requests.
Note: In DDI, the target is identified using a controllerId. Controller refers to the actual service/client on the device. This enables users to run multiple clients on the same target for different tasks, e.g., firmware updates and App management.
Please be aware of the existence of a Quota. We also recommend checking out the target and action state machines.
Access the DDI API documentation:
EU Swagger UI
US Swagger UI
Table of contents:
Eclipse hawkBit™ compatibility
Bosch IoT Rollouts DDI API is fully compatible with Eclipse hawkBit’s DDI API in version 1 (v1).
As a result, hawkBit-compatible clients can be used with Rollouts, e.g., SWupdate, a Linux Update agent focused on an efficient and safe way to update embedded systems.
The hawkBit project provides Java representations that allow you to decode the message body at runtime into a Java object (if you have Java installed on your device). The Java models can also be used to encode Java objects as JSON bodies for requests to Rollouts. The project also provides a guide on creating a Feign REST Client.
The model is available on Maven Central, e.g., in Maven
<dependency> <groupId>org.eclipse.hawkbit</groupId> <artifactId>hawkbit-ddi-api</artifactId> <version>0.9.0</version> <!-- Make sure to replace the version with the latest available release --></dependency>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 remains compatible with devices in the field. A future version “2” of DDI might change that. DDI also defines more states than the update server does; e.g., the implementation currently maps different DDI states to the 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 the update server | Mapped ActionStatus type |
|---|---|---|
CANCELED | This is sent by the target as confirmation of a cancellation request by the update server. | CANCELED |
REJECTED | This is sent by the target if an update to a cancellation is rejected, i.e., cannot be fulfilled at this point in time. Note: the target should send CLOSED->ERROR if it believes it cannot proceed with the action at all. | WARNING |
CLOSED | Target completes the action either with status.result.finished SUCCESS or FAILURE as a result. Note: DDI also defines a status NONE, which the update server does not interpret and treats as SUCCESS. | ERROR (DDI FAILURE) or FINISHED (DDI SUCCESS or NONE) |
DOWNLOAD | This can be used by the target to inform that it is downloading artifacts of the action. | DOWNLOAD |
DOWNLOADED | This can be used by the target to indicate that it has downloaded the action's artifacts. | DOWNLOADED |
PROCEEDING | This can be used by the target to inform that it is working on the action. | RUNNING |
SCHEDULED | This can be used by the target to inform that it scheduled the action. | RUNNING |
RESUMED | This can be used by the target to indicate that it continued working on the action. | RUNNING |
User consent flow enabled
When the user consent flow feature is enabled (which is recommended), some modifications on the DDI interface occur. The main one is that it will not directly expose the update via the deploymentBase resource link (the one polled by the devices to check whether there is an update). Instead, it will provide the updated information via a confirmationBase link so that devices can recognize that there is an update present, but it first requires an explicit confirmation from the user before it can be installed.
When the user consent flow feature is enabled before an update action, an additional WAIT_FOR_CONFIRMATION action status is introduced (see Action state machine).
While the update action is in this status, the device can use the following two execution statuses as a response:
DDI status.execution type | handling by the update server | Mapped ActionStatus type |
|---|---|---|
CONFIRMED | This is used by the target to inform that the user has confirmed the update. | RUNNING |
DENIED | This is used by the target to inform that the user has denied the confirmation request. | WAIT_FOR_CONFIRMATION |
The DDI API also provides a resource to activate auto confirmation. As a result, all current and future actions will automatically be confirmed by listing the initiator as the triggering person. Actions will be automatically confirmed as long as auto-confirmation is active.
Once the confirmation is given by the user via the respective POST method, the action state will change to RUNNING, and the update will be exposed via the deploymentBase link.
If the user confirmation is Denied, the action state will remain in the WAIT_FOR_CONFIRMATION state indefinitely until it's confirmed.
Before enabling the user consent flow feature, you need to ensure that your devices support the different flow and know how to handle this kind of payload.