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