After the added option to target the live channel by adding the channel=live to HTTP requests (see also blog post about “HTTP live channel”), Eclipse Ditto version 2.3.0 will in addition support to define a live channel condition, which, when evaluating to true, will retrieve data from a device via the live channel, or fall back to the persisted twin otherwise.

Relying on conditions

Ditto 2.1.0 added support for conditional requests by e.g. specifying a condition query parameter for HTTP API calls.

This mechanism can now additionally be used to formulate a condition through the query parameter live-channel-condition whether data shall be retrieved via the live channel from the device.

Optionally update twin automatically based on retrieved live data

Whenever a device reports back its actual sensor readings, one can be sure that this data is the most recent “truth”.
It therefore is obvious to use that data in order to update the persisted twin managed by Ditto.

This can optionally be enabled by configuring the new UpdateTwinWithLiveResponse mapper in a Ditto managed connection.
This mapper will transform each “live response” retrieving and transporting data from a device to an additional merge command modifying the twin with that live data.

Example: Device is marked to be polled

This is for example helpful if the device does not push its newest sensor readings actively into its twin representation managed by Ditto, but relies on being polled for the newest readings.
In that case, the twin could be marked e.g. as attributes/polling-mode=true:

{
  "thingId": "my.namespace:my-polling-device-1",
  "policyId": "my.namespace:my-polling-device-1",
  "attributes": {
    "polling-mode": true
  },
  "features": {
    "temperature": {
      "properties": {
        "value": 23.42
      }
    }
  }
}

When an IoT application now needs to retrieve the latest temperature value, it can formulate a query (e.g. in HTTP):

GET /api/2/things/my.namespace:my-polling-device-1/features/temperature/properties/value
  ?live-channel-condition=eq(attributes/polling-mode,true)
  &timeout=10s
  &live-channel-timeout-strategy=use-twin

The specified live-channel-condition will evaluate to true, meaning that the retrieve is transformed to a live command and sent to the device, e.g. connected via a managed connection.
Upon receiving the “live retrieve” at the device, the device can create a command response correlated with the same correlation-id and send it back to Ditto with the current value.
This value is then returned as result of the GET, the HTTP response header channel will indicate that the data was sent by the device by having the value live.

If the device does not answer with a correctly correlated response within the given timeout, the request will fall back to the twin channel, retrieving the data from the last known persisted temperature value in the twin managed by Ditto.
The HTTP response header channel will indicate that the data was received by the persisted twin by having the value twin.

Example: Device contains a connection status

Another perfect fit for that feature is when the device (or the device connectivity layer) is able to reflect the connection status of the device in the Ditto managed twin.
When e.g. using Eclipse Hono in combination with Ditto, the ConnectionStatus mapper can be configured in a Ditto managed connection which will automatically update a feature in the twin based on Hono’s device notifications reflecting a "readySince" and "readyUntil" timestamp:

{
  "thingId": "my.namespace:my-connection-aware-device-1",
  "policyId": "my.namespace:my-connection-aware-device-1",
  "features": {
    "ConnectionStatus": {
      "definition": [ "org.eclipse.ditto:ConnectionStatus:1.0.0" ],
      "properties": {
        "status": {
          "readySince": "2021-12-22T14:16:18Z",
          "readyUntil": "9999-12-31T23:59:59Z"
        }
      }
    },
    "temperature": {
      "properties": {
        "value": 23.42
      }
    }
  }
}

In that case, the "readyUntil" will contain a timestamp how long the device will be ready to receive commands, the timestamp "9999-12-31T23:59:59Z" being an alias for indefinitely (once the device disconnects, e.g. from the MQTT adapter of Eclipse Hono, this timestamp will be set to the disconnection time).

Utilizing this “connection awareness”, we can now easily define a query to retrieve data from the real device when it is connected and use the persisted twin when it is not connected or runs into a timeout.
For using the current time as ISO-8601 timestamp, a new placeholder time:now was also introduced, usable in RQL expressions everywhere in Ditto:

GET /api/2/things/my.namespace:my-connection-aware-device-1/features/temperature/properties/value
  ?live-channel-condition=gt(features/ConnectionStatus/properties/status/readyUntil,time:now)
  &timeout=10s
  &live-channel-timeout-strategy=use-twin

Of course every other field in the persisted twin may also be used in the live-channel-condition, if your devices e.g. are aware if they are connected or not by other means (e.g. by setting an attribute), this can be utilized as well.

Feedback?

Please get in touch if you have feedback or questions towards this new functionality.



Ditto

–
The Eclipse Ditto team