Provide a command + APIs in order to calculate+retrieve deltas of desired vs. properties

[thjaeckle]

As part of #696 a new functionality shall be introduced in order to calculate a delta/diff/patch between the desiredProperties and the properties (or reported) state of a digital twin (thing) or of a single feature of it.

The format has to be defined, it could be:

• a JSON patch document: https://tools.ietf.org/html/rfc6902
• a simpler, self defined JSON format
• ...?

The following APIs are added:

• HTTP endpoint(s) in order to retrieve that deltas for complete things and for single features
• Ditto Protocol counterparts in order to do the same via WebSocket and connections

[jufickel-b]

I prefer a JSON Patch document as it matches the requirements and first and foremost because it is a well-known standard.

[thjaeckle]

Maybe this is not required at all and #700 is sufficient in order for a device to retrieve all "unapplied" desired changes.

[ffendt]

From my point of view, the desired properties already are the "delta" (or diff/patch). Moreover, the device knows best how to calculate the delta (if it even needs one) for its business case and the value types it uses.
Thus basically I see no real reason how this functionality would help Ditto users achieving their goals, or am I missing something here?

[thjaeckle]

@ffendt one concern could be that the desired state should not be cleared when the properties state reached the desired value.
That's where a delta would still be beneficial, e.g. in order to save payload.

Not clearing the desired properties could be a requirement, e.g. in order to apply the complete last known "desired" state when a device does a reset to factory settings.
When Ditto would clear the desired state, the last known overall desired state is not tracked.

[ffendt]

Imho we should never clear the desired state automatically and leave this to the device itself. It would be convenient to just return the diff between the reported and desired values to the device (or, using a query flag, returning all desired values). If the device wants to have a clean desired representation, it can delete the unwanted values itself.

Btw: did I misunderstand the meaning of delta in this case? (When thinking of a delta, I think about reported=6, desired=8, --> send delta=2 to the device.

[thjaeckle]

Btw: did I misunderstand the meaning of delta in this case? (When thinking of a delta, I think about reported=6, desired=8, --> send delta=2 to the device.

Oh, that's not what I meant.
With "delta" I meant something like calculating a JSON patch for the "reported" properties which currently differ from the desiredProperties ones, e.g.:

[
  { "op": "replace", "path": "/features/Thermostat/properties/configuration/target-temperature", "value": 22.0 }
]