Protocol flow
Example DMF message flow
The following diagram illustrates a typical DMF message flow:
When the user consent flow feature has been enabled, the DMF API flow changes as a new step is introduced, indicating that the action is waiting for user confirmation.
The DMF message flow is provisioning target centric, i.e. there are no bulk messages for multiple targets/devices.
In general, the DMF API defines five messages:
THING_CREATED (Client -> Rollouts)
Initial creation of a provisioning target if it does not exist in the repository yet (plug-and-play). If the device does exist it will result only in an update of the last poll time field of the target. In addition, Bosch IoT Rollouts will also (re-)transmit open update actions back to the client. We generally recommend to send these polls on a regular basis, either whenever the device connects to the device management service or if it has a standing connection in a regular interval. That has the benefit of greater robustness as an update message might have gotten lost and leverages Bosch IoT Rollouts capability to signal to the user that a device is overdue if the poll is coming in the defined time frame (see System Configuration for how to configure the expected poll schedule).
See Messages sent to Bosch IoT Rollouts > THING_CREATED
THING_REMOVED (Client -> Rollouts)
Deletion of a provisioning target. If this message is sent, a hard deletion is triggered on Bosch IoT Rollouts side, that also removes all associated metadata. The deletion can’t be undone.
A THING_DELETED message is sent back to the client, that confirms the deletion of the target.
See Messages sent to Bosch IoT Rollouts >THING_REMOVED
CONFIRM (Rollouts -> Client)
With this message Bosch IoT Rollouts initializes a user confirmation task. It Indicates that there is an update available for the device but a confirmation from the user is required before the software update process can continue.
Applicable only if the user consent flow feature has been enabled prior to the start of the action.
DOWNLOAD_AND_INSTALL (Rollouts -> Client)
Update command for a target. As mentioned above this message will be send when the update is started in Bosch IoT Rollouts and resend after every THING_CREATED.
DOWNLOAD (Rollouts -> Client)
Download only command for a target. As mentioned above this message will be send when the download is started in Bosch IoT Rollouts and resend after every THING_CREATED. This message will be send instead of DOWNLOAD_AND_INSTALL if the Download Only deployment type is selected or if a maintenance window is configured but device is not in the next available window yet.
See Messages sent by Bosch IoT Rollouts > DOWNLOAD_AND_INSTALLorDOWNLOAD
CANCEL_DOWNLOAD (Rollouts -> Client)
Bosch IoT Rollouts tries to inform the device about a canceled update. In many cases that might be too late and as a matter of fact devices can reject the cancellation and continue with the update (see below).
See Messages sent by Bosch IoT Rollouts > CANCEL_DOWNLOAD
MULTI_ACTION (Rollouts -> Client)
When multi.assignments.enabled is enabled, this message exposes all open actions of the device and is sent instead of DOWNLOAD, DOWNLOAD_AND_INSTALL, and CANCEL_DOWNLOAD.
See Messages sent by Bosch IoT Rollouts > MULTI_ACTION
UPDATE_ACTION_STATUS (Client -> Rollouts)
Feedback for an update action. The feedback can be of an intermediate type, e.g. “starting download” or finishing, e.g. “done”.
All feedback messages are stored by Bosch IoT Rollouts in the action history of the target.
Note: The DMF client can set an AMQP correlation-id message property field which is stored by Bosch IoT Rollouts in the targets action history and can be retrieved by users either through the Management UI or Management API.
See Messages sent to Bosch IoT Rollouts > UPDATE_ACTION_STATUS
THING_DELETED (Rollouts -> Client)
Bosch IoT Rollouts informs the device about a deletion of its representation on the Bosch IoT Rollouts server. Consider that after a target is removed Bosch IoT Rollouts will ignore corresponding event messages.
Messages sent by Bosch IoT Rollouts > THING_DELETED