Bosch IoT Rollouts

Device Management Federation (DMF) API

Table of contents:

Overview

The purpose of the DMF API is indirect device integration through a device management service into Bosch IoT Rollouts. It is message based and optimized for cloud service-to-service interaction. The message transport is AMQP 0-9-1 compatible with message bodies in JSON. The API itself is compatible with the Eclipse hawkBit DMF API.

The DMF API is available in Free plan for evaluation purposes and in the Standard plan for productive use. Note that the API has to be activated (either by Management API or Management UI).

images/confluence/download/attachments/1697844272/enableDmf-version-1-modificationdate-1619011482000-api-v2.png

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

Eclipse hawkBit™ compatibility

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

The hawkBit project provides Java representations that allow to decode the message body at runtime into a Java object. The Java models can also be used to encode Java objects into JSON bodies to send a message to Bosch IoT Rollouts.

The model is available on Maven central.

<dependency>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-dmf-api</artifactId>
<version>0.2.0</version>
</dependency>

Basics

There are three basic concepts of AMQP:

  • Exchanges - what you publish to.

  • Queues - what you consume from. DMF API defines four messages.

  • Bindings - configuration that maps an exchange to a queue.

Queues are just a place for receiving messages. Bindings determine how messages get into them. Queues can also be bound to multiple exchanges.

Exchanges are for publishing messages. The user decides who can publish on the exchange and who can create bindings on that exchange for delivery to a specific queue.

Rollouts off the shelf exchanges and queues

For communication Bosch IoT Rollouts will create all necessary queues, exchanges and the bindings for the user. So it is very easy to communicate with Bosch IoT Rollouts out of the box. The exchange name to sending a message to Bosch IoT Rollouts is dmf.exchange.

The queue name to receive messages from Bosch IoT Rollouts is sp_direct_queue.

Bosch IoT Rollouts sends messages to the sp.direct.exchange which is bound to the sp_direct_queue.

A word on reliability

In general, the AMQP based message transfer as used in DMF does not guarantee end-to-end delivery. However, we encourage DMF users to:

  • Leverage the THING_CREATED poll mechanism as Bosch IoT Rollouts will automatically re-transfer open DOWNLOAD_AND_INSTALL, CANCEL_DOWNLOAD, or CONFIRM messages to the client after every poll (see above).

  • Leverage AMQP’s best practices to ensure a reliable transport of messages send to Bosch IoT Rollouts.

  • Leverage Bosch IoT Rollouts storage of the message correlation-id in the action history to investigate a potential message loss.