From 7a7ddcba17b577fc8ab83d9b4b1069854e310b89 Mon Sep 17 00:00:00 2001
From: Benjamin Leendert Montavon <benjamin.montavon@rwth-aachen.de>
Date: Thu, 3 Mar 2022 11:54:13 +0100
Subject: [PATCH] Continued work on entity properties

---
 OpenAPI/openapi.yml                           |  5 ++
 .../OBJ-Entity/PAR-Calibration.yml            |  7 +-
 .../OBJ-Entities/OBJ-Entity/PAR-State.yml     |  2 +
 .../OBJ-Entities/OBJ-Entity/PAR-Type.yml      |  2 +
 .../OBJ-Entity/VAR-Orientation.yml            | 84 +++++++++++++++++++
 .../OBJ-Entities/OBJ-Entity/VAR-Position.yml  | 81 ++++++++++++++++++
 .../OBJ-LSM/OBJ-Entities/OBJ-Entity/index.yml |  6 +-
 .../OBJ-ROOT/OBJ-LSM/PAR-Calibration.yml      |  5 +-
 OpenAPI/paths/OBJ-ROOT/PAR-Manufacturer.yml   |  7 +-
 OpenAPI/paths/OBJ-ROOT/PAR-State.yml          |  2 +
 OpenAPI/paths/OBJ-ROOT/PAR-Time.yml           |  7 +-
 OpenAPI/paths/OBJ-ROOT/PAR-Version.yml        |  7 +-
 12 files changed, 209 insertions(+), 6 deletions(-)

diff --git a/OpenAPI/openapi.yml b/OpenAPI/openapi.yml
index 083221f..a669f74 100644
--- a/OpenAPI/openapi.yml
+++ b/OpenAPI/openapi.yml
@@ -67,6 +67,11 @@ paths:
     $ref: 'paths/index.yml#/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-Name'
   /OBJ-LSM/OBJ-Entities/{uuid}/PAR-Type/:
     $ref: 'paths/index.yml#/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-Type'
+  /OBJ-LSM/OBJ-Entities/{uuid}/VAR-Orientation/:
+    $ref: 'paths/index.yml#/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/VAR-Orientation'
+  /OBJ-LSM/OBJ-Entities/{uuid}/VAR-Position/:
+    $ref: 'paths/index.yml#/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/VAR-Position'
+
 
 components:
   schemas:
diff --git a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-Calibration.yml b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-Calibration.yml
index dca57ac..1d727f6 100644
--- a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-Calibration.yml
+++ b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-Calibration.yml
@@ -1,7 +1,12 @@
 description: >
   **Calibration identifier**  
 
-  Retrieve a unique calibration string identifying a corresponding certificate.
+  Retrieve a unique calibration string identifying a corresponding certificate.  
+
+    
+
+  This is a *read-only* parameter.
+
 
 get:
   tags:
diff --git a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-State.yml b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-State.yml
index 09a2133..c39c241 100644
--- a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-State.yml
+++ b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-State.yml
@@ -8,6 +8,8 @@ description: >
     * `ERROR`: There is an error which is critical to operation.
     * `MAINTENANCE`: The system ist currently down for a scheduled maintenance operation.  
 
+    
+
   This is a *read-only* parameter.
 get:
   tags:
diff --git a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-Type.yml b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-Type.yml
index 993c797..b32b76a 100644
--- a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-Type.yml
+++ b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/PAR-Type.yml
@@ -4,6 +4,8 @@ description: >
   System-specific identifier of the target type, e.g. SMR-1.5inch.
   The type is not further standardized.  
 
+    
+
   This is a *read-only* parameter.
 
 get:
diff --git a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/VAR-Orientation.yml b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/VAR-Orientation.yml
index e69de29..30d7219 100644
--- a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/VAR-Orientation.yml
+++ b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/VAR-Orientation.yml
@@ -0,0 +1,84 @@
+description: >
+  **Orientation**  
+
+  Current orientation (i.e. last measurement) of the mobile entity.
+  This value should only be different to *null* if the entity is actually capable 
+  of measuring the orientation. The same holds for the covariance estimate.  
+
+  Quaternions have been chosen to unambiguously express orientation across conventions.  
+
+    
+
+  **MQTT**: The updates of this value shall also be published via MQTT using 
+  the same JSON representation. Hence they may also be consumed via MQTT and its websocket
+  extension in the corresponding applications.
+get:
+  tags:
+    - Entity
+  description:
+    $ref: '#/description'
+  parameters:
+    - $ref: '../../../../../parameters/index.yml#/OBJ-Entity-uuid'  
+  responses:
+    '200':
+      description: >
+        **OK**  
+
+        Everything occurred as expected.
+      content:
+        application/json:
+          schema: 
+            $ref: '../../../../../schemas/index.yml#/Variable'
+          example:
+            uuid: PAR-Orientation
+            name: Orientation
+            description: Current orientation of the mobile entity expressed as quaternion.
+            ontology: null
+            datatype: double
+            dimension: [4]
+            unit: C62
+            range: []
+            value: [0.02357738, 0.09441385, 0.21169921, 0.97247806]
+            covariance: [
+                          [9.635354886031938e-06, 0.0004436033096059594, 0.00016144081411989793, 0.0001699398949338537],
+                          [0.0004436033096059594, 0.0002922712707392062, 9.709317499541933e-05, 0.00018066604301265513],
+                          [0.00016144081411989793, 9.709317499541933e-05, 2.1450372592198085e-05, 0.00019699186912319554],
+                          [0.0001699398949338537, 0.00018066604301265513, 0.00019699186912319554, 1.645440660862675e-05]
+                        ]
+            timestamp: "2022-02-01T17:00:01.352916Z"
+    '500':
+      $ref: "../../../../../responses/index.yml#/InternalError"
+
+options:
+  tags:
+    - Entity
+  description:
+    $ref: '#/description'
+  parameters:
+    - $ref: '../../../../../parameters/index.yml#/OBJ-Entity-uuid'  
+  responses:
+    '200':
+      description: >
+        **OK**  
+
+        Everything occurred as expected.
+      content:
+        application/json:
+          schema: 
+            $ref: '../../../../../schemas/index.yml#/Variable'
+          example:
+            uuid: PAR-Orientation
+            name: Orientation
+            description: Current orientation of the mobile entity expressed as quaternion.
+            ontology: null
+            datatype: double
+            dimension: [4]
+            unit: C62
+            range: []
+            value: null
+            covariance: null
+            timestamp: null
+    '500':
+      $ref: "../../../../../responses/index.yml#/InternalError"
+    '501':
+      $ref: "../../../../../responses/index.yml#/NotImplemented"
\ No newline at end of file
diff --git a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/VAR-Position.yml b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/VAR-Position.yml
index e69de29..b3b2a5d 100644
--- a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/VAR-Position.yml
+++ b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/VAR-Position.yml
@@ -0,0 +1,81 @@
+description: >
+  **Position**  
+
+  Current Position (i.e. last measurement) of the mobile entity.
+  This is the core value of interest for Large-Scale Metrology systems. 
+  The value is expected to be in MTR (not implicated by SOIL, but lowering overhead for others). 
+
+     
+
+  **MQTT**: The updates of this value shall also be published via MQTT using 
+  the same JSON representation. Hence they may also be consumed via MQTT and its websocket
+  extension in the corresponding applications.
+get:
+  tags:
+    - Entity
+  description:
+    $ref: '#/description'
+  parameters:
+    - $ref: '../../../../../parameters/index.yml#/OBJ-Entity-uuid'  
+  responses:
+    '200':
+      description: >
+        **OK**  
+
+        Everything occurred as expected.
+      content:
+        application/json:
+          schema: 
+            $ref: '../../../../../schemas/index.yml#/Variable'
+          example:
+            uuid: VAR-Position
+            name: Position [m]
+            description: Current position of the mobile entity.
+            ontology: null
+            datatype: double
+            dimension: [3]
+            unit: MTR
+            range: []
+            value: [3.123, 4.221, 1.522]
+            covariance: [
+                          [0.04074968380933543, 0.081224742424419, 0.0146097707717761],
+                          [0.081224742424419, 0.11810662674797013, 0.01641245412362838],
+                          [0.0146097707717761, 0.01641245412362838, 0.11144618705511516]
+                        ]
+            timestamp: "2022-02-01T17:00:01.352916Z"
+    '500':
+      $ref: "../../../../../responses/index.yml#/InternalError"
+
+options:
+  tags:
+    - Entity
+  description:
+    $ref: '#/description'
+  parameters:
+    - $ref: '../../../../../parameters/index.yml#/OBJ-Entity-uuid'  
+  responses:
+    '200':
+      description: >
+        **OK**  
+
+        Everything occurred as expected.
+      content:
+        application/json:
+          schema: 
+            $ref: '../../../../../schemas/index.yml#/Variable'
+          example:
+            uuid: VAR-Position
+            name: Position [m]
+            description: Current position of the mobile entity.
+            ontology: null
+            datatype: double
+            dimension: [3]
+            unit: MTR
+            range: []
+            value: null
+            covariance: null
+            timestamp: null
+    '500':
+      $ref: "../../../../../responses/index.yml#/InternalError"
+    '501':
+      $ref: "../../../../../responses/index.yml#/NotImplemented"
\ No newline at end of file
diff --git a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/index.yml b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/index.yml
index c38a195..c235154 100644
--- a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/index.yml
+++ b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/OBJ-Entities/OBJ-Entity/index.yml
@@ -11,4 +11,8 @@ PAR-Mode:
 PAR-Name:
   $ref: 'PAR-Name.yml'
 PAR-Type:
-  $ref: 'PAR-Type.yml'
\ No newline at end of file
+  $ref: 'PAR-Type.yml'
+VAR-Orientation:
+  $ref: 'VAR-Position.yml'
+VAR-Position:
+  $ref: 'VAR-Position.yml'
\ No newline at end of file
diff --git a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/PAR-Calibration.yml b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/PAR-Calibration.yml
index 18ad1f7..bf0c47d 100644
--- a/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/PAR-Calibration.yml
+++ b/OpenAPI/paths/OBJ-ROOT/OBJ-LSM/PAR-Calibration.yml
@@ -1,8 +1,11 @@
 description: >
   **Calibration identifier**  
 
-  Retrieve a unique calibration string identifying a corresponding certificate.
+  Retrieve a unique calibration string identifying a corresponding certificate.  
 
+    
+
+  This is a *read-only* parameter.
 get:
   tags:
     - LSM
diff --git a/OpenAPI/paths/OBJ-ROOT/PAR-Manufacturer.yml b/OpenAPI/paths/OBJ-ROOT/PAR-Manufacturer.yml
index a5609a1..3938324 100644
--- a/OpenAPI/paths/OBJ-ROOT/PAR-Manufacturer.yml
+++ b/OpenAPI/paths/OBJ-ROOT/PAR-Manufacturer.yml
@@ -1,7 +1,12 @@
 description: >
   **Manufacturer**  
 
-  String identifying the manufacturer of the device.
+  String identifying the manufacturer of the device.  
+
+    
+
+  This is a *read-only* parameter.
+
 get:
   tags:
     - Root
diff --git a/OpenAPI/paths/OBJ-ROOT/PAR-State.yml b/OpenAPI/paths/OBJ-ROOT/PAR-State.yml
index 46d615c..5c566ba 100644
--- a/OpenAPI/paths/OBJ-ROOT/PAR-State.yml
+++ b/OpenAPI/paths/OBJ-ROOT/PAR-State.yml
@@ -8,6 +8,8 @@ description: >
     * `ERROR`: There is an error which is critical to operation.
     * `MAINTENANCE`: The system ist currently down for a scheduled maintenance operation.  
 
+    
+
   This is a *read-only* parameter.
 get:
   tags:
diff --git a/OpenAPI/paths/OBJ-ROOT/PAR-Time.yml b/OpenAPI/paths/OBJ-ROOT/PAR-Time.yml
index 44ffc13..c960257 100644
--- a/OpenAPI/paths/OBJ-ROOT/PAR-Time.yml
+++ b/OpenAPI/paths/OBJ-ROOT/PAR-Time.yml
@@ -3,7 +3,12 @@ description: >
 
   Current system time. This is a convenience function for time inspection and not meant for 
   precise synchronization. If the latter is required, the system time should be synchronized
-  at operating system level using an according time protocol.
+  at operating system level using an according time protocol.  
+
+    
+
+  This is a *read-only* parameter.
+
 get:
   tags:
     - Root
diff --git a/OpenAPI/paths/OBJ-ROOT/PAR-Version.yml b/OpenAPI/paths/OBJ-ROOT/PAR-Version.yml
index 3694c58..4a6cb2b 100644
--- a/OpenAPI/paths/OBJ-ROOT/PAR-Version.yml
+++ b/OpenAPI/paths/OBJ-ROOT/PAR-Version.yml
@@ -3,7 +3,12 @@ description: >
 
   Incremental version number of the device's and/or interface implementation,
   to allow for introducing and noting breaking changes. The timestamp may
-  correspond to the release date. 
+  correspond to the release date.  
+
+    
+
+  This is a *read-only* parameter.
+
 get:
   tags:
     - Root
-- 
GitLab