Bosch IoT Suite

2021-12-22 - Bosch IoT Things - service update

Our latest service release comes with the following new feature:

Live channel condition

With the latest release Bosch IoT Things supports you to automatically switch between twin and live channel when retrieving device data via API.

By using the new live-channel-condition together with the use-twin strategy, in conjunction with the new response headers, your application can transparently benefit from both channels with just one request. In case the device cannot answer in time, your application will still retrieve a response with the required value, and the response headers make it easy to find out who responded: the live device or its digital twin.

This channel switch is supported via HTTP API, WebSocket, and Ditto protocol over all types of managed connection. With the upcoming Ditto release 2.3 the feature will also be supported via Ditto Java Client.

The conditions can be defined using RQL expressions. See details at Search HTTP API introduction for all Relational operators and Logical operators.

The following schematic overview illustrates the overall communication flow:

images/confluence/download/attachments/2081100745/live-response-and-twin-update.png

Example 1

Use the live-channel-condition to retrieve data from the device itself, if a specific attribute has a defined value. GET .../things/{thingId}?live-channel-condition=eq(attributes/useLiveChannel,true)

If the condition matches, the retrieve command is forwarded to the device as live command defined as Ditto Protocol message, and the device can answer to that by creating a correlated response.

If the condition doesn’t match (e.g. the attribute does not exist or has another value), the service will provide the response data from the digital twin persisted in Bosch IoT Things.

Example 2

Use the ConnectionStatus feature in the condition. If the device is currently ready to receive messages, request live data, otherwise request twin data.

GET .../things/{thingId}?live-channel-condition=gt(features/ConnectionStatus/properties/status/readyUntil,time:now)

New request header

You can additionally make use of the new header live-channel-timeout-strategy. The header value holds a strategy what to do in case a timeout (can also be specified as header) was encountered.

  • If the value cannot be retrieved live from the device itself during the specified timeout, the request will fail (which is the default strategy if not specified otherwise) with a status code 408.

  • Alternatively, if you define use-twin as the live-channel-timeout-strategy strategy, the request will fall back to the persisted twin and return the latest value stored in the digital twin.

New response headers

The response includes two additional headers to indicate which channel was used to retrieve the thing data:

  • live-channel-condition-matched – value could be true or false and states whether the passed live-channel-condition was a match or not

  • channel – value could be twin or live and defines which channel was the origin of the returned data.

Twin update from live data

In line with the procedure described above on how to retrieve live data directly from your device, we have introduced a new type of pre-configured payload mapping, namely UpdateTwinWithLiveResponse.

Upon activation, the digital twin stored in Bosch IoT Things will implicitly be updated with the latest data from the live response sent by the device.

Tip: You can easily activate this mapper using the Connections UI. Select “Devices via Bosch IoT Hub” > Edit > “Payload mapping” > checkbox “Enable updating twins based on received live retrieve command responses”.

The new functionality is based on new features of our open source base Eclipse Ditto.
Further details are described in Eclipse Ditto:

At this occasion, various minor bugs have also been fixed.