From 5ebff572b796aa561cdfc0c77ed4fa00cd9b1fee Mon Sep 17 00:00:00 2001 From: Ulf Date: Thu, 7 Apr 2022 11:40:59 +0200 Subject: [PATCH 1/5] Issue 450. Inverse bounded range support. --- spec/VISSv2_Core.html | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/spec/VISSv2_Core.html b/spec/VISSv2_Core.html index 953f9a9..f0be7de 100644 --- a/spec/VISSv2_Core.html +++ b/spec/VISSv2_Core.html @@ -662,11 +662,22 @@

Time Based Filter Operation

Range Filter Operation

- The value contains the range boundary, and the logical operator, {"logic-op":"X", "boundary": "Y"}, - where X is one of the supported logical operators (**), and Y is the boundary of the range. - The value may be an array of two of these objects, - which will then be combined through a logical AND to support expressions of a bounded range. - A range event is triggered whenever a signal is updated, and fulfilling the range expression.

+ The range filter operation supports three types of ranges:
+ 1. Unbounded range
+ 2. Bounded range
+ 3. Inverse of bounded range
+ The range operation issues notifications to the client when the logical expression defined in the "value" key-value pair evaluation is true, and the signal is updated.
+ For the unbounded range, the "value" consists of one JSON object that contains the range boundary, and the logical operator for the boundary, + {"boundary-op":"X", "boundary": "Y"}, + where X is one of the supported logical operators (**), and Y is the boundary of the range.
+ For the other two types, the value consists of an array of two JSON objects, that each contains the same key-value pairs as for the unbounded case, + but where the first object may have an optional key-value pair, "combination-op":"Z". Its value Z MUST be either "AND" or "OR", + and it defines the logical operation that combines the logical expressions of the first and the second objects. + If this key-value pair is left out, the two expressions are combined using the AND logical operator.
+ Example "value" objects of the three types:
+ 1. {"boundary-op":"gt", "boundary": "5"} // x > 5
+ 2. [{"boundary-op":"gt", "boundary": "5"},{"boundary-op":"lt", "boundary": "10"}] // x > 5 AND x < 10
+ 3. [{"boundary-op":"lt", "boundary": "5", "combination-op":"OR"},{"boundary-op":"gt", "boundary": "10"}] // x < 5 OR x > 10

(**)The supported logical operators are ["eq", "ne", "gt", "gte", "lt", "lte"], where "eq" is "equal", "ne" is "not equal", "gt" is "greater than", "gte" is "greater than or equal", "lt" is "less than", "lte" is "less than or equal".
From a782f88461b89be9b430678e2c8347e32534b89e Mon Sep 17 00:00:00 2001 From: Ulf Date: Wed, 13 Apr 2022 11:31:20 +0200 Subject: [PATCH 2/5] Issue 450. Update of the description of range support. --- spec/VISSv2_Core.html | 54 +++++++++++++++++++++++--------------- spec/VISSv2_Transport.html | 4 +-- 2 files changed, 35 insertions(+), 23 deletions(-) diff --git a/spec/VISSv2_Core.html b/spec/VISSv2_Core.html index f0be7de..6238396 100644 --- a/spec/VISSv2_Core.html +++ b/spec/VISSv2_Core.html @@ -605,7 +605,7 @@

Filter Request

The server MUST support the timebased and change types, the other types are optional.
In the JSON object, the key-value pairs "type" and "value" must always be present. The JSON expression may consist of maximum one object with type "paths", plus maximum one object with any other supported type, - which are then logically combined as with an AND operator.
+ which are then logically combined as with an AND operand.
The types timebased, range, change, and curvelog are only applicable for subscription requests. Subscription requests are supported by the websocket and the MQTT transport protocols.
The restriction on how many objects that can be combined is also set by the URL size restriction on 1k characters (*).
@@ -662,23 +662,35 @@

Time Based Filter Operation

Range Filter Operation

- The range filter operation supports three types of ranges:
- 1. Unbounded range
- 2. Bounded range
- 3. Inverse of bounded range
- The range operation issues notifications to the client when the logical expression defined in the "value" key-value pair evaluation is true, and the signal is updated.
- For the unbounded range, the "value" consists of one JSON object that contains the range boundary, and the logical operator for the boundary, - {"boundary-op":"X", "boundary": "Y"}, - where X is one of the supported logical operators (**), and Y is the boundary of the range.
- For the other two types, the value consists of an array of two JSON objects, that each contains the same key-value pairs as for the unbounded case, - but where the first object may have an optional key-value pair, "combination-op":"Z". Its value Z MUST be either "AND" or "OR", - and it defines the logical operation that combines the logical expressions of the first and the second objects. - If this key-value pair is left out, the two expressions are combined using the AND logical operator.
- Example "value" objects of the three types:
- 1. {"boundary-op":"gt", "boundary": "5"} // x > 5
- 2. [{"boundary-op":"gt", "boundary": "5"},{"boundary-op":"lt", "boundary": "10"}] // x > 5 AND x < 10
- 3. [{"boundary-op":"lt", "boundary": "5", "combination-op":"OR"},{"boundary-op":"gt", "boundary": "10"}] // x < 5 OR x > 10

- (**)The supported logical operators are ["eq", "ne", "gt", "gte", "lt", "lte"], + The range filter operation supports two types of ranges, see the following sub chapters.
+

+

Single Boundary Range

+

+ One logical "boundary operand" evaluates the current signal value in relation to the boundary. + If evaluated to true, the server issues a notification message containing the signal value to the subscribing client. + The boundary operand MUST be one of the values shown in the footer (**).
+ Examples
+ {"boundary-op":"gt", "boundary": "5"} // x > 5
+ {"boundary-op":"eq", "boundary": "5"} // x == 5 +

+
+
+

Multi Boundary Range

+

+ Two boundaries with respective boundary operands are evaluated relative to the current signal value. + The logical outcome of the two evaluations are applied as input to a logical AND/OR operation. + If evaluated to true, the server issues a notification message containing the signal value to the subscribing client. + Besides the mandatory "boundary-op", and "boundary" key-value pairs in each JSON object, + the first object may contain a "combination-op" key value pair, which then MUST have either the value "AND", or the value "OR". + If omitted, the result of the two boundary evaluations is per default applied to an AND operation. + The JSON array MUST contain two objects. + The boundary operand MUST be one of the values shown in the footer (**).
+ Examples
+ [{"boundary-op":"gt", "boundary": "5"},{"boundary-op":"lt", "boundary": "10"}] // x > 5 AND x < 10
+ [{"boundary-op":"lt", "boundary": "5", "combination-op":"OR"},{"boundary-op":"gt", "boundary": "10"}] // x < 5 OR x > 10 +

+
+ (**)The supported boundary operands are ["eq", "ne", "gt", "gte", "lt", "lte"], where "eq" is "equal", "ne" is "not equal", "gt" is "greater than", "gte" is "greater than or equal", "lt" is "less than", "lte" is "less than or equal".
Examples can be found in the authorized subscribe and @@ -689,14 +701,14 @@

Range Filter Operation

Change Filter Operation

- The value contains the logical operator for comparison of previous and current values, {"logic-op":"X", "diff":"Y"}, - where X is one of the supported logical operators (**), and Y is the value of the required change.
+ The value contains the logical operand for comparison of previous and current values, {"logic-op":"X", "diff":"Y"}, + where X is one of the supported logical operands (**), and Y is the value of the required change.
For boolean values the following expressions shall be supported:
"value":{"logic-op":"gt", "diff": "0"} This leads to a trigger event when the value goes false->true.
"value":{"logic-op":"lt", "diff": "0"} This leads to a trigger event when the value goes true->false.
"value":{"logic-op":"ne", "diff": "0"} This leads to a trigger event when the value goes true->false OR false->true.

- (**)The supported logical operators are ["eq", "ne", "gt", "gte", "lt", "lte"], + (**)The supported logic operands are ["eq", "ne", "gt", "gte", "lt", "lte"], where "eq" is "equal", "ne" is "not equal", "gt" is "greater than", "gte" is "greater than or equal", "lt" is "less than", "lte" is "less than or equal".
Examples can be found in the [[viss2-transport]] specification. diff --git a/spec/VISSv2_Transport.html b/spec/VISSv2_Transport.html index fbec930..01fdb81 100644 --- a/spec/VISSv2_Transport.html +++ b/spec/VISSv2_Transport.html @@ -1168,7 +1168,7 @@

Authorized Subscribe

{ "action": "subscribe", "path": "Vehicle/Drivetrain/FuelSystem/Level", - "filter": {"type":"range", "value":[{"logic-op":"gt", "boundary":"49"}, {"logic-op":"lt", "boundary":"51"}]}, + "filter": {"type":"range", "value":[{"boundary-op":"gt", "boundary":"49"}, {"boundary-op":"lt", "boundary":"51"}]}, "authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1...Zw_KSsds", "requestId": "6578" } @@ -1249,7 +1249,7 @@

Range Subscribe

{ "action": "subscribe", "path": "Vehicle/Drivetrain/FuelSystem/Level", - "filter": "filter":{"type":"range","value":[{"logic-op":"gt","boundary":"50"},{"logic-op":"lt","boundary":"55"}]}, + "filter": "filter":{"type":"range","value":[{"boundary-op":"lt","boundary":"50","combination-op":"OR"},{"boundary-op":"gt","boundary":"55"}]}, "requestId": "6578" } From 35a1fcdb461cab0f9524b242c67c68bf094bd58c Mon Sep 17 00:00:00 2001 From: Ulf Date: Tue, 19 Apr 2022 09:49:14 +0200 Subject: [PATCH 3/5] Renamed to operator. --- spec/VISSv2_Core.html | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/spec/VISSv2_Core.html b/spec/VISSv2_Core.html index 6238396..15451e2 100644 --- a/spec/VISSv2_Core.html +++ b/spec/VISSv2_Core.html @@ -605,7 +605,7 @@

Filter Request

The server MUST support the timebased and change types, the other types are optional.
In the JSON object, the key-value pairs "type" and "value" must always be present. The JSON expression may consist of maximum one object with type "paths", plus maximum one object with any other supported type, - which are then logically combined as with an AND operand.
+ which are then logically combined as with an AND operator.
The types timebased, range, change, and curvelog are only applicable for subscription requests. Subscription requests are supported by the websocket and the MQTT transport protocols.
The restriction on how many objects that can be combined is also set by the URL size restriction on 1k characters (*).
@@ -666,9 +666,9 @@

Range Filter Operation

Single Boundary Range

- One logical "boundary operand" evaluates the current signal value in relation to the boundary. + One logical "boundary operator" evaluates the current signal value in relation to the boundary. If evaluated to true, the server issues a notification message containing the signal value to the subscribing client. - The boundary operand MUST be one of the values shown in the footer (**).
+ The boundary operator MUST be one of the values shown in the footer (**).
Examples
{"boundary-op":"gt", "boundary": "5"} // x > 5
{"boundary-op":"eq", "boundary": "5"} // x == 5 @@ -677,20 +677,20 @@

Single Boundary Range

Multi Boundary Range

- Two boundaries with respective boundary operands are evaluated relative to the current signal value. + Two boundaries with respective boundary operators are evaluated relative to the current signal value. The logical outcome of the two evaluations are applied as input to a logical AND/OR operation. If evaluated to true, the server issues a notification message containing the signal value to the subscribing client. Besides the mandatory "boundary-op", and "boundary" key-value pairs in each JSON object, the first object may contain a "combination-op" key value pair, which then MUST have either the value "AND", or the value "OR". If omitted, the result of the two boundary evaluations is per default applied to an AND operation. The JSON array MUST contain two objects. - The boundary operand MUST be one of the values shown in the footer (**).
+ The boundary operator MUST be one of the values shown in the footer (**).
Examples
[{"boundary-op":"gt", "boundary": "5"},{"boundary-op":"lt", "boundary": "10"}] // x > 5 AND x < 10
[{"boundary-op":"lt", "boundary": "5", "combination-op":"OR"},{"boundary-op":"gt", "boundary": "10"}] // x < 5 OR x > 10

- (**)The supported boundary operands are ["eq", "ne", "gt", "gte", "lt", "lte"], + (**)The supported boundary operators are ["eq", "ne", "gt", "gte", "lt", "lte"], where "eq" is "equal", "ne" is "not equal", "gt" is "greater than", "gte" is "greater than or equal", "lt" is "less than", "lte" is "less than or equal".
Examples can be found in the authorized subscribe and @@ -701,14 +701,14 @@

Multi Boundary Range

Change Filter Operation

- The value contains the logical operand for comparison of previous and current values, {"logic-op":"X", "diff":"Y"}, - where X is one of the supported logical operands (**), and Y is the value of the required change.
+ The value contains the logical operator for comparison of previous and current values, {"logic-op":"X", "diff":"Y"}, + where X is one of the supported logical operators (**), and Y is the value of the required change.
For boolean values the following expressions shall be supported:
"value":{"logic-op":"gt", "diff": "0"} This leads to a trigger event when the value goes false->true.
"value":{"logic-op":"lt", "diff": "0"} This leads to a trigger event when the value goes true->false.
"value":{"logic-op":"ne", "diff": "0"} This leads to a trigger event when the value goes true->false OR false->true.

- (**)The supported logic operands are ["eq", "ne", "gt", "gte", "lt", "lte"], + (**)The supported logic operators are ["eq", "ne", "gt", "gte", "lt", "lte"], where "eq" is "equal", "ne" is "not equal", "gt" is "greater than", "gte" is "greater than or equal", "lt" is "less than", "lte" is "less than or equal".
Examples can be found in the [[viss2-transport]] specification. From 3877d6011448583f5f759d66c8cf4a1c65741a27 Mon Sep 17 00:00:00 2001 From: Ulf Date: Tue, 19 Apr 2022 10:23:06 +0200 Subject: [PATCH 4/5] Change subscription chapter added. --- spec/VISSv2_Transport.html | 42 +++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/spec/VISSv2_Transport.html b/spec/VISSv2_Transport.html index 01fdb81..35929a2 100644 --- a/spec/VISSv2_Transport.html +++ b/spec/VISSv2_Transport.html @@ -1239,7 +1239,7 @@

Curve Logging Subscribe

Range Subscribe

- Subscription to a range of values, that can be either unbounded, or bounded as in the example below. + Subscription to a range of values, that can have either a single boundary, or multipe boundaries as in the example below. For a more information how to use range of values, refer the Range Filter Operation chapter in the [[viss2-core]] documentation.

@@ -1276,6 +1276,46 @@

Range Subscribe

+
+

Change Subscribe

+

+ Subscription to when a signal has changed between two sequential captures. + For a more information how to use change of values, refer the Change Filter Operation chapter in the [[viss2-core]] documentation. +

+

+ Example:
+ Request: + 


+              {
+                "action": "subscribe",
+                "path": "Vehicle/Drivetrain/FuelSystem/Level",
+                "filter": "filter":{"type":"change","value":{"logic-op":"gt","diff":"10"}},
+                "requestId": "6578"
+              }
+
+ Successful response: + 

+              {
+                "action": "subscribe",
+                "subscriptionId": "12345",
+                "requestId": "6578",
+                "ts": "2020-04-15T13:37:00Z"
+              }
+
+ Notification: + 

+              {
+                "action": "subscription",
+                "subscriptionId": "12345",
+                “data”:{“path”: ”Vehicle/Drivetrain/FuelSystem/Level”, 
+                        “dp”:{“value”: ”101”, “ts”: ”2020-04-15T14:00:00Z”},
+                "ts": "2020-04-15T14:00:00Z"
+              }
+
+

+
+
+

Unsubscribe

From e68eb41ec4036d036f9172d73a15f4a74eef781d Mon Sep 17 00:00:00 2001 From: Ulf Date: Tue, 19 Apr 2022 10:27:27 +0200 Subject: [PATCH 5/5] Change subscription chapter layout correction. --- spec/VISSv2_Transport.html | 1 - 1 file changed, 1 deletion(-) diff --git a/spec/VISSv2_Transport.html b/spec/VISSv2_Transport.html index 35929a2..5957f41 100644 --- a/spec/VISSv2_Transport.html +++ b/spec/VISSv2_Transport.html @@ -1274,7 +1274,6 @@

Range Subscribe

-

Change Subscribe