Acknowledgements

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

tip 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.

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.

note 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.
  • 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.

note 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 therfore 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 sources respectively and define a filter for which messages the new “requested-acks” header should be applied.

In the configuration of your connections targets an acknowledgement to be issued to the requested acknowledgements can be specified.

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

Further info

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

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

Imprint Legal info Privacy statement