Bosch IoT Device Management

Acknowledgements

An acknowledgement (ACK) is a confirmation that a request was processed successfully.

With this feature, we provide a quality of service guarantee of “at least once” (aka QoS 1) when processing operations/messages in an end-to-end manner for the Bosch IoT Suite. For example, a processed message from the Bosch IoT Hub will be technically acknowledged only after it was successfully applied in the Things service, and potentially also in 3rd-party applications. Without successful processing, the redelivery mechanisms of Bosch IoT Hub will apply, according the QoS level set there.

Table of contents:

Common use cases

In some IoT use cases, the processing of requests is important and needs to be guaranteed. The new feature of the Things service supports to control this behaviour from an end-to-end perspective. This includes the processing within the Things service, but also the delivery and processing within other services, which listen to the digital twins managed within Bosch IoT Things.

The guaranteed processing is controlled using acknowledgements.

By default, acknowledgements are used for ensuring the successful persistence of thing updates. They are requested, if messages from devices are delivered with a respective demand for QoS 1 (i.e. at least once) from the Bosch IoT Hub, or if applications trigger updates via API. In case of sending telemetry data, which is not crucial for your IoT application (e.g. because it is sent regularly anyway), you can avoid using such acknowledgements, whereas events can request an acknowledgement.

Additional acknowledgements can be requested and confirmed for delivering or processing of messages within other services. This way, you can make sure that also this delivery or processing is finished successfully.

On all connections to the Things service for receiving operations/messages, you can define the required acknowledgement. The events emitted by Things will include the information about your required acknowledgement. The emitting of events to the respective connections (like AMQP, MQTT, Apache Kafka, or HTTP) can directly confirm such an acknowledgment, if the target system confirms to have received it.

To make sure that a message is reported as delivered, or a change is confirmed as applied, only if other layers also confirm the success, you can request an acknowledgement.

By requesting an ACK you can:

  • postpone a response to an API request (e.g. block an HTTP requestAcknowledgements) until one or more specific actions were performed in the Things service (e.g. a modification was successfully persisted).

  • postpone a response until an external subscriber connected to Things reports that he successfully processed an event which e.g. resulted by a persistence change in the Things service.

  • provide a QoS (quality of service) guarantee of “at least once” when processing messages in an end-to-end manner by e.g. technically settling a processed signal from a message broker (e.g. AMQP 1.0 or MQTT) only after it was successfully applied.

The twin channel and the live channel both support acknowledgements. Twin-modifying commands, all live commands, and all live messages may request acknowledgements.

Acknowledgement requests

By default, acknowledgements are not requested for telemetry data (sent via Bosch IoT Hub). This makes it easy for your devices to send e.g. sensor readings, where the loss of one value is not crucial for your IoT application.

However, if your IoT solution needs to listen for a specific event, you might want to trace this delivery.

The twin events, live commands and live messages emitted by Things can include the custom acknowledgement requests in the “requested-acks” header.

This “requested-acks” header can be applied by setting it to an initial request to one of the Things APIs.

The following acknowledgements can be used:

  • Built-in acknowledgement: twin-persisted
    An acknowledgement with this label is issued when a modifying command has successfully updated the digital twin in the Things service persistence.

  • Built-in acknowledgement: live-response
    An acknowledgement with this label is issued when the response to a live command or live message is received.

  • Built-in acknowledgement: search-persisted
    An acknowledgement with this label is issued when a modifying command has successfully updated the search index of the digital twin.

  • Custom acknowledgement labels: you-name-it
    In addition to the built-in acknowledgement requests, a received command or message can contain custom acknowledgement labels. A subscriber can detect that an acknowledgement was requested via the “requested-acks” header. If the subscriber is in charge of handling a requested acknowledgement it issues the acknowledgement.

By default, a twin-modifying command requests the twin-persisted acknowledgement, and a live command or live message requests the live-response acknowledgement.

Redelivery

In case of a NACK, the Bosch IoT Hub will try to redeliver all requests.

If you send live commands via Bosch IoT Hub to subscribers that do not answer with live responses, please set the header response-required explicitly to false, or disable acknowledgements for the Bosch IoT Hub connection. Otherwise, the connection will consider the default acknowledgement live-response unfulfilled, and will therefore request redelivery from Bosch IoT Hub over and over again.

Redelivery is not idempotent

If you enforce the re-delivery of a twin modify command, e.g. by requesting an ACK, it might happen that this value is enforced even though a more recent command has been applied already. However, to avoid such situations, you can additionally work with Conditional requests.

Configuration via connection

At the Things dashboard > tab Connections/Integrations you can configure your connection respectively.

  • In the configuration of your connection’s sources you can enable acknowledgements, define acknowledgements to request as includes from messages consumed by this source, define a filter for your Requested acknowledgements, and add a list of declared acknowledgements.

  • In the configuration of your connection’s targets the Issued acknowledgements can be specified.

Of course, the HTTP API for /solutions/{solutionId}/connections provides the same functionality.

Example

images/confluence/download/attachments/1790647293/connection-ack.png

Declared acknowledgements

The requirement to manage declared acknowledgements has been introduced in order to have global unique identifiers, of which acknowledgements are expected from which connections, and thus, to better trace them in complex scenarios which involve multiple clients and fan-out distribution.

The pattern for naming your declared acknowledgements is: {{connection-id}}:your-identifier.
In case of a Java client you can use {{solution-id}}:your-identifier.
Of course, the connection ID pr solution ID will be dynamically resolved at runtime.

Issued acknowledgements and incoming acknowledgements will only be accepted, if they match to one of the declared acknowledgements for the same connection.

  • For managed connections, you can “declare” the acknowledgement labels that could be provided in the source configuration of the Things dashboard.

  • For WebSocket connections, the client application can define a list of declared acknowledgements as comma separated list within the URL as query parameter. E.g. https://things.eu-1.bosch-iot-suite.com/ws/2?declared-acks={{solution:id}}:my-ws). Further, it is required that only one WebSocket with the same declared acknowledgement is connected at the same time.

Weak acknowledgements

Since there are scenarios, where the subscriber of events or live messages has defined an RQL filter or is not allowed to receive an event by a policy, it is not always possible, that an acknowledgement can be provided.

To avoid that a command fails because of a missing acknowledgement for those reasons, we introduced weak acknowledgements (WACKs).

These weak acknowledgements are issued automatically by Ditto, in case a message or an event is filtered by a subscriber, which declared to provide one or more of the requested acknowledgements for the command.

A weak acknowledgement can be identified by checking the header with value ditto-weak-ack. Weak acknowledgements have this header set to true.

These weak acknowledgements do not cause redelivery of messages consumed by a connection.

Further info

Find further details related to requesting and issuing acknowledgements via HTTP, WebSocket and managed connections at Eclipse Ditto.

Blog post with examples on various scenarios: https://www.eclipse.org/ditto/2020-10-23-end-2-end-acknowledgment.html.

The acknowledgement concept is not proposed to be used for handling “long running acknowledgement” processes. Applications should try to confirm delivery and processing within short time. If long running processing is needed, this should be decoupled by additional means from the acknowledgement itself (e.g. by using a persistent message queuing).

The protocol specification for acknowledgements as well as examples for AMQP, MQTT, HTTP, and Kafka are also part of the Eclipse Ditto documentation.