Multiple value subscriptions documentation

[tkurki]

Explain the use case in plain english without abstract concepts.

Specify the precise path by separating the source reference inside square brackets, because the reference is period delimited and not entirely obvious which part of the path is hierarchy and which property name.

Solves #271

[rob42]

I dont think this works. I read that a subscription to a key will return the value AND the values. If I subscribe to navigation.speedThroughWater how will the values object be sent in a delta?. Doesnt this also cause a lot of unnecessary data to be sent regularly when I only want navigation.speedThroughWater.value?, eg how do i get that only?

I think it makes more sense not to send the values in a default subscription, and for the client to check for values?

[tkurki]

Subscriptions result in deltas.

Deltas have no value/values distinction, they are just key-value pairs, where the key is the subscribed path.

If you subscribe to a path for which there are two sources you will get deltas from two sources, but the individual deltas will have just the subscribed path, with source information.

[rob42]

Your PR states "A subscription to a key is for all the updates to that key. If there are multiple sources generating data for that key the client will get all their updates". So that means for multiple SOW values like your gist https://gist.github.com/tkurki/84cd71d2329f3ffae9f0 ( pls ignore misc source vs $source errors etc) I will get a delta something like:

{
    "context": "vessels.motu",
    "updates": [{
        "timestamp": "2015-03-23T01:57:02.256Z",
        "source": "nmea1-II",
        "values": [{
            "path": "navigation.speedThroughWater",
            "value": 3.24
        }]
    }, 
    {
        "source": "nmea2-II",
        "timestamp": "2015-11-15T14:37:32.306Z",
        "values": [{
            "path": "navigation.speedThroughWater.values.nmea2-II",
            "value": 3.24
        }]
    }, 
    {
        "source": "n2k-1-115",
        "timestamp": "2015-11-15T14:37:32.306Z",
        "values": [{
            "path": "navigation.speedThroughWater.values.n2k-1-115",
            "value": 3.21
        }]
    }
    ..etc
}

When all I actually want is:

{
    "context": "vessels.motu",
    "updates": [{
        "timestamp": "2015-03-23T01:57:02.256Z",
        "source": "nmea1-II",
        "values": [{
            "path": "navigation.speedThroughWater",
            "value": 3.24
        }]
    }
}

[tkurki]

No - deltas never have the ...values in the path. Deltas have no knowledge of there being multiple sources.

If you have two sources you will get deltas like (some fields omitted for clarity).

{
  "updates": [{
    "source": :
      "sentence": "DBT",
      "label": "nmea1",
      "talker": "II"
    },
    "values": [{
      "path": "environment.depth.belowTransducer",
      "value": 7.26
    }]
  }]
}

{
  "updates": [{
    "source": {
      "sentence": "DBT",
      "label": "nmea2",
      "talker": "II"
    },
    "values": [{
      "path": "environment.depth.belowTransducer",
      "value": 6.8
    }]
  }]
}

If you subscribe to environment.depth.belowTransducer you will get all deltas from both sources.

My idea here (based on apparently misunderstading your comments) was that you could subscribe to environment.depth.belowTransducer.values[nmea2.II] and you would get deltas just for the source identified by nmea2.II.

The corresponding full structure, that can be used to discover what sources there are and the parameters to use in subscribing to them:

...depth:
{
  "value": 6.8,
  "$source": "nmea2.II",
  "values": {
    "nmea1.II": {
      "value": 7.26,
      "sentence": "DBT",
    },
    "nmea2.II": {
      "value": 6.8,
      "sentence": "DBT"
    }
  }
}

[rob42]

Doesnt that make it difficult to determine which value is the 'official' one? eg the one displayed at environment.depth.belowTransducer?

Not a big issue for a browser based app, but I'm thinking in terms of a much less capable device, eg an arduino that is doing some function where data is required. If it just subscribes for environment.depth.belowTransducer it will get a range of values, and its quite complex to choose and subscribe to one, when you only have 4K of RAM.

IMHO a subscription to environment.depth.belowTransducer should send out the 'official' value, eg the one at environment.depth.belowTransducer.value, and if there are other values they can be found and subscribed by the full query as you described above.

Otherwise, what is the point of value?

[tkurki]

To me it is the exact opposite - with environment.depth.belowTransducer subscription I expect to get all depth information.

A client can retrieve the source for value and subscribe with that to get the data for a particular source.

If the use case for subscribing to the default value I believe we can come up with a reasonable, simple extension to the subscription protocol to support that intent.

I definitely do not want to start messing up the path in delta with value/values - the source is in the delta already, no need to encode the same information in a string field, adding logic to any client that wants to use the real SK key.

[rob42]

In the commit above it states "The client can retrieve the relevant data via REST API." We need to keep in mind that many clients will not be http capable, hence the GET/LIST messages (I cant find the ref just now)

I'm going to commit you pr, as we can adjust later